Method: places.autocomplete

Trả về thông tin dự đoán cho đầu vào đã cho.

Yêu cầu HTTP

POST https://places.googleapis.com/v1/places:autocomplete

URL sử dụng cú pháp Chuyển mã gRPC.

Nội dung yêu cầu

Nội dung yêu cầu chứa dữ liệu có cấu trúc sau:

Biểu diễn dưới dạng JSON 
{
  "input": string,
  "locationBias": {
    object (LocationBias)
  },
  "locationRestriction": {
    object (LocationRestriction)
  },
  "includedPrimaryTypes": [
    string
  ],
  "includedRegionCodes": [
    string
  ],
  "languageCode": string,
  "regionCode": string,
  "origin": {
    object (LatLng)
  },
  "inputOffset": integer,
  "includeQueryPredictions": boolean,
  "sessionToken": string
}
Trường
input

string

Bắt buộc. Chuỗi văn bản mà bạn muốn tìm kiếm.
locationBias

object (LocationBias)

Không bắt buộc. Kết quả sai lệch đến một vị trí được chỉ định.

Bạn phải đặt tối đa một trong hai giá trị locationBias hoặc locationRestriction. Nếu bạn không đặt biểu tượng nào thì kết quả sẽ bị sai lệch theo địa chỉ IP, nghĩa là địa chỉ IP sẽ được ánh xạ tới một vị trí không chính xác và được dùng làm tín hiệu xu hướng.
locationRestriction

object (LocationRestriction)

Không bắt buộc. Giới hạn kết quả ở một vị trí đã chỉ định.

Bạn phải đặt tối đa một trong hai giá trị locationBias hoặc locationRestriction. Nếu bạn không đặt biểu tượng nào thì kết quả sẽ bị sai lệch theo địa chỉ IP, nghĩa là địa chỉ IP sẽ được ánh xạ tới một vị trí không chính xác và được dùng làm tín hiệu xu hướng.
includedPrimaryTypes[]

string

Không bắt buộc. Đã bao gồm loại địa điểm chính (ví dụ: "nhà hàng" hoặc "gas_station") trong Bảng A hoặc Bảng B trong Loại địa điểm (https://developers.google.com/maps/documentation/places/web-service/place-types) hoặc chỉ (khu vực) hoặc chỉ (thành phố). Địa điểm chỉ được trả về nếu loại chính của địa điểm có trong danh sách này. Bạn có thể chỉ định tối đa 5 giá trị. Nếu không có loại nào được chỉ định, hàm sẽ trả về tất cả Loại địa điểm.
includedRegionCodes[]

string

Không bắt buộc. Chỉ bao gồm kết quả ở những khu vực được chỉ định, được chỉ định là tối đa 15 mã vùng gồm hai ký tự CLDR. Một tập rỗng sẽ không hạn chế kết quả. Nếu bạn đặt cả locationRestriction và includedRegionCodes, thì kết quả sẽ nằm ở khu vực giao lộ.
languageCode

string

Không bắt buộc. Ngôn ngữ mà kết quả trả về. Giá trị mặc định là en-US. Kết quả có thể ở nhiều ngôn ngữ nếu ngôn ngữ dùng trong input khác với languageCode hoặc nếu Địa điểm được trả về không có bản dịch từ ngôn ngữ địa phương sang languageCode.
regionCode

string

Không bắt buộc. Mã vùng, được chỉ định dưới dạng mã vùng gồm hai ký tự CLDR. Điều này ảnh hưởng đến việc định dạng địa chỉ, thứ hạng kết quả và có thể ảnh hưởng đến kết quả trả về. Việc này không giới hạn kết quả ở khu vực được chỉ định. Để giới hạn kết quả ở một khu vực, hãy dùng region_code_restriction.
origin

object (LatLng)

Không bắt buộc. Điểm gốc để tính khoảng cách trắc địa đến điểm đến (được trả về là distanceMeters). Nếu bỏ qua giá trị này, hàm sẽ không trả về khoảng cách trắc địa.
inputOffset

integer

Không bắt buộc. Độ lệch ký tự Unicode dựa trên 0 của input cho biết vị trí con trỏ trong input. Vị trí con trỏ có thể ảnh hưởng đến những cụm từ gợi ý được trả về.

Nếu trống, độ dài mặc định là input.
includeQueryPredictions

boolean

Không bắt buộc. Nếu đúng, câu trả lời sẽ bao gồm cả thông tin dự đoán về địa điểm và cụm từ tìm kiếm. Nếu không, phản hồi sẽ chỉ trả về các gợi ý về Địa điểm.
sessionToken

string

Không bắt buộc. Một chuỗi xác định một phiên Tự động hoàn thành cho mục đích thanh toán. Phải là chuỗi base64 an toàn cho URL và tên tệp với độ dài tối đa 36 ký tự ASCII. Nếu không, lỗi INVALID_ARGUMENT sẽ được trả về.

Phiên hoạt động bắt đầu khi người dùng bắt đầu nhập cụm từ tìm kiếm và kết thúc khi họ chọn một địa điểm và thực hiện lệnh gọi đến phần Chi tiết địa điểm hoặc Xác thực địa chỉ. Mỗi phiên có thể có nhiều truy vấn, theo sau là một yêu cầu Chi tiết địa điểm hoặc Xác thực địa chỉ. Thông tin đăng nhập dùng cho mỗi yêu cầu trong một phiên phải thuộc cùng một dự án Google Cloud Console. Sau khi phiên kết thúc, mã thông báo không còn hợp lệ; ứng dụng của bạn phải tạo mã thông báo mới cho mỗi phiên. Nếu thông số sessionToken bị bỏ qua hoặc nếu bạn sử dụng lại mã thông báo phiên, thì phiên sẽ được tính phí như thể không có mã thông báo phiên nào được cung cấp (mỗi yêu cầu sẽ được tính phí riêng).

Bạn nên làm theo các nguyên tắc sau:

  • Sử dụng mã thông báo phiên cho tất cả các lệnh gọi Tự động hoàn thành địa điểm.
  • Tạo mã thông báo mới cho mỗi phiên hoạt động. Bạn nên sử dụng mã nhận dạng duy nhất (UUID) phiên bản 4.
  • Đảm bảo rằng thông tin đăng nhập dùng cho tất cả các yêu cầu Tự động hoàn thành địa điểm, Chi tiết về địa điểm và Xác thực địa chỉ trong một phiên hoạt động đều thuộc về cùng một dự án Cloud Console.
  • Hãy nhớ truyền một mã thông báo phiên duy nhất cho mỗi phiên mới. Nếu bạn sử dụng cùng một mã thông báo cho nhiều phiên, thì mỗi yêu cầu sẽ bị tính phí riêng.

Nội dung phản hồi

Proto phản hồi cho places.autocomplete.

Nếu thành công, phần nội dung phản hồi sẽ chứa dữ liệu có cấu trúc sau:

Biểu diễn dưới dạng JSON 
{
  "suggestions": [
    {
      object (Suggestion)
    }
  ]
}
Trường
suggestions[]

object (Suggestion)

Chứa danh sách các đề xuất, được sắp xếp theo thứ tự giảm dần về mức độ liên quan.

LocationBias

Khu vực cần tìm kiếm. Kết quả có thể sai lệch về khu vực được chỉ định.

Biểu diễn dưới dạng JSON 
{

  // Union field type can be only one of the following:
  "rectangle": {
    object (Viewport)
  },
  "circle": {
    object (Circle)
  }
  // End of list of possible types for union field type.
}
Trường

Trường kết hợp type.

type chỉ có thể là một trong những trạng thái sau đây:
rectangle

object (Viewport)

Một khung nhìn được xác định bởi một góc đông bắc và một góc phía tây nam.
circle

object (Circle)

Hình tròn được xác định bởi một điểm tâm và bán kính.

LocationRestriction

Khu vực cần tìm kiếm. Kết quả sẽ được giới hạn trong khu vực được chỉ định.

Biểu diễn dưới dạng JSON 
{

  // Union field type can be only one of the following:
  "rectangle": {
    object (Viewport)
  },
  "circle": {
    object (Circle)
  }
  // End of list of possible types for union field type.
}
Trường

Trường kết hợp type.

type chỉ có thể là một trong những trạng thái sau đây:
rectangle

object (Viewport)

Một khung nhìn được xác định bởi một góc đông bắc và một góc phía tây nam.
circle

object (Circle)

Hình tròn được xác định bởi một điểm tâm và bán kính.

Đề xuất

Kết quả đề xuất Tự động hoàn thành.

Biểu diễn dưới dạng JSON 
{

  // Union field kind can be only one of the following:
  "placePrediction": {
    object (PlacePrediction)
  },
  "queryPrediction": {
    object (QueryPrediction)
  }
  // End of list of possible types for union field kind.
}
Trường

Trường kết hợp kind.

kind chỉ có thể là một trong những trạng thái sau đây:
placePrediction

object (PlacePrediction)

Thông tin dự đoán về một Địa điểm.
queryPrediction

object (QueryPrediction)

Thông tin dự đoán cho một truy vấn.

PlacePrediction

Kết quả dự đoán cho cụm từ gợi ý của tính năng Tự động hoàn thành địa điểm.

Biểu diễn dưới dạng JSON 
{
  "place": string,
  "placeId": string,
  "text": {
    object (FormattableText)
  },
  "structuredFormat": {
    object (StructuredFormat)
  },
  "types": [
    string
  ],
  "distanceMeters": integer
}
Trường
place

string

Tên tài nguyên của Địa điểm được đề xuất. Tên này có thể được dùng trong các API khác chấp nhận Tên địa điểm.
placeId

string

Giá trị nhận dạng duy nhất của địa điểm được đề xuất. Bạn có thể dùng giá trị nhận dạng này trong những API khác chấp nhận Mã địa điểm.
text

object (FormattableText)

Chứa tên mà con người có thể đọc được cho kết quả được trả về. Đối với các kết quả thành lập, thông tin này thường là tên và địa chỉ của doanh nghiệp.

text được đề xuất cho các nhà phát triển muốn hiển thị một thành phần trên giao diện người dùng. Nếu muốn hiển thị hai thành phần riêng biệt nhưng có liên quan với nhau, nhà phát triển nên sử dụng structuredFormat. Đây là hai cách khác nhau để thể hiện thông tin dự đoán về địa điểm. Người dùng không nên cố gắng phân tích cú pháp structuredFormat thành text hoặc ngược lại.

Văn bản này có thể khác với displayName do places.get trả về.

Có thể bằng nhiều ngôn ngữ nếu yêu cầu input và languageCode bằng các ngôn ngữ khác nhau hoặc nếu Địa điểm không có bản dịch từ ngôn ngữ địa phương sang languageCode.
structuredFormat

object (StructuredFormat)

Bảng phân tích chi tiết dự đoán Địa điểm thành văn bản chính có chứa tên của Địa điểm và văn bản phụ có chứa các đối tượng địa lý bổ sung (chẳng hạn như một thành phố hoặc khu vực).

structuredFormat được đề xuất cho các nhà phát triển muốn hiển thị hai thành phần giao diện người dùng riêng biệt nhưng có liên quan. Các nhà phát triển muốn hiển thị một thành phần trên giao diện người dùng duy nhất có thể sử dụng text. Đây là hai cách khác nhau để thể hiện thông tin dự đoán về địa điểm. Người dùng không nên cố gắng phân tích cú pháp structuredFormat thành text hoặc ngược lại.
types[]

string

Danh sách các loại áp dụng cho Địa điểm này trong Bảng A hoặc Bảng B trên https://developers.google.com/maps/documentation/places/web-service/place-types.

Loại là phân loại một Địa điểm. Những địa điểm thuộc loại được chia sẻ sẽ có những đặc điểm tương tự.
distanceMeters

integer

Chiều dài của đường trắc địa tính bằng mét từ origin nếu origin được chỉ định. Một số cụm từ gợi ý như tuyến đường có thể không được điền sẵn cho trường này.

FormattableText

Văn bản đại diện cho một thông tin dự đoán về Địa điểm hoặc truy vấn. Văn bản có thể được sử dụng nguyên trạng hoặc định dạng.

Biểu diễn dưới dạng JSON 
{
  "text": string,
  "matches": [
    {
      object (StringRange)
    }
  ]
}
Trường
text

string

Văn bản có thể được sử dụng nguyên trạng hoặc định dạng bằng matches.
matches[]

object (StringRange)

Danh sách các dải chuỗi xác định vị trí khớp với yêu cầu đầu vào trong text. Bạn có thể dùng dải ô để định dạng các phần cụ thể của text. Chuỗi con có thể không phải là kết quả khớp chính xác của input nếu việc khớp được xác định bằng tiêu chí khác ngoài so khớp chuỗi (ví dụ: sửa lỗi chính tả hoặc chuyển tự).

Các giá trị này là độ lệch ký tự Unicode của text. Các dải ô được đảm bảo được sắp xếp theo giá trị bù trừ tăng dần.

StringRange

Xác định chuỗi con trong một văn bản đã cho.

Biểu diễn dưới dạng JSON 
{
  "startOffset": integer,
  "endOffset": integer
}
Trường
startOffset

integer

Mức chênh lệch từ 0 của ký tự Unicode đầu tiên của chuỗi (bao gồm cả giá trị này).
endOffset

integer

Độ lệch từ 0 của ký tự Unicode cuối cùng (không bao gồm).

StructuredFormat

Chứa bảng chi tiết của một địa điểm hoặc dự đoán truy vấn thành văn bản chính và văn bản phụ.

Đối với các dự đoán về địa điểm, văn bản chính sẽ chứa tên cụ thể của Địa điểm đó. Đối với các dự đoán truy vấn, văn bản chính chứa truy vấn.

Văn bản phụ chứa các đối tượng làm phân biệt bổ sung (chẳng hạn như thành phố hoặc vùng) để xác định thêm Địa điểm hoặc tinh chỉnh truy vấn.

Biểu diễn dưới dạng JSON 
{
  "mainText": {
    object (FormattableText)
  },
  "secondaryText": {
    object (FormattableText)
  }
}
Trường
mainText

object (FormattableText)

Đại diện cho tên của Địa điểm hoặc truy vấn.
secondaryText

object (FormattableText)

Biểu thị các đối tượng riêng biệt bổ sung (chẳng hạn như thành phố hoặc vùng) để xác định thêm Địa điểm hoặc tinh chỉnh truy vấn.

QueryPrediction

Kết quả dự đoán cho thông tin dự đoán Tự động hoàn thành truy vấn.

Biểu diễn dưới dạng JSON 
{
  "text": {
    object (FormattableText)
  },
  "structuredFormat": {
    object (StructuredFormat)
  }
}
Trường
text

object (FormattableText)

Văn bản được dự đoán. Văn bản này không đại diện cho Địa điểm mà là một cụm từ tìm kiếm có thể dùng trong một điểm cuối tìm kiếm (ví dụ: Tìm kiếm văn bản).

text được đề xuất cho các nhà phát triển muốn hiển thị một thành phần trên giao diện người dùng. Nếu muốn hiển thị hai thành phần riêng biệt nhưng có liên quan với nhau, nhà phát triển nên sử dụng structuredFormat. Đây là hai cách khác nhau để thể hiện thông tin dự đoán truy vấn. Người dùng không nên cố gắng phân tích cú pháp structuredFormat thành text hoặc ngược lại.

Có thể bằng các ngôn ngữ hỗn hợp nếu yêu cầu input và languageCode bằng các ngôn ngữ khác nhau hoặc nếu một phần của truy vấn không có bản dịch từ ngôn ngữ địa phương sang languageCode.
structuredFormat

object (StructuredFormat)

Bảng phân tích dự đoán truy vấn thành văn bản chính có chứa truy vấn và văn bản phụ có chứa các đối tượng địa lý bổ sung (chẳng hạn như thành phố hoặc khu vực).

structuredFormat được đề xuất cho các nhà phát triển muốn hiển thị hai thành phần giao diện người dùng riêng biệt nhưng có liên quan. Các nhà phát triển muốn hiển thị một thành phần trên giao diện người dùng duy nhất có thể sử dụng text. Đây là hai cách khác nhau để thể hiện thông tin dự đoán truy vấn. Người dùng không nên cố gắng phân tích cú pháp structuredFormat thành text hoặc ngược lại.