Method: places.autocomplete

Trả về kết quả dự đoán cho dữ liệu đầ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 cần tìm kiếm.

locationBias

object (LocationBias)

Không bắt buộc. Bù trừ kết quả tới một vị trí được chỉ định.

Bạn chỉ được đặ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ẽ được thiên vị 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. Hạn chế kết quả trong một vị trí được chỉ định.

Bạn chỉ được đặ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ẽ được thiên vị 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") từ https://developers.google.com/maps/documentation/places/web-service/place-types. Địa điểm chỉ được trả về nếu loại chính của địa điểm đó được đưa vào 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, tất cả các loại Địa điểm sẽ được trả về.

includedRegionCodes[]

string

Không bắt buộc. Chỉ bao gồm kết quả trong các khu vực được chỉ định, được chỉ định ở mức tối đa 15 mã vùng hai ký tự CLDR. Việc để trống nhóm sẽ không hạn chế các kết quả. Nếu bạn đặt cả locationRestrictionincludedRegionCodes, kết quả sẽ nằm trong khu vực giao nhau.

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ể bằng nhiều ngôn ngữ nếu ngôn ngữ được sử 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 định dạng địa chỉ, thứ hạng của kết quả và có thể ảnh hưởng đến những kết quả được trả về. Điều này không hạn chế kết quả trong khu vực được chỉ định. Để chỉ hiển thị kết quả theo 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 giá trị này bị bỏ qua, khoảng cách trắc địa sẽ không được trả về.

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 truy vấn dự đoán được trả về.

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

includeQueryPredictions

boolean

Không bắt buộc. Nếu đúng, câu trả lời sẽ bao gồm cả các gợi ý về địa điểm và truy vấn. Nếu không, câu trả lờ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 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, có độ dài tối đa là 36 ký tự ASCII. Nếu không, hệ thống sẽ trả về lỗi INVALID_ qu.

Phiên bắt đầu khi người dùng bắt đầu nhập truy vấn và kết thúc khi họ chọn một địa điểm và thực hiện cuộc gọi đế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 Thông tin chi tiết về địa điểm hoặc Yêu cầu xác thực địa chỉ. Thông tin đăng nhập được dùng cho từng yêu cầu trong một phiên phải thuộc cùng một dự án trên Google Cloud Console. Sau khi một phiên kết thúc, mã thông báo này không còn hợp lệ nữa. Ứng dụng phải tạo một mã thông báo mới cho mỗi phiên. Nếu tham 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 hoạt động sẽ bị 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 được tính phí riêng).

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

  • Sử dụng mã phiên cho tất cả các lệnh gọi Tự động hoàn thành địa điểm.
  • Tạo một mã thông báo mới cho mỗi phiên. 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 được dùng cho tất cả yêu cầu Tự động hoàn thành về địa điểm, Chi tiết địa điểm và Xác thực địa chỉ trong một phiên đều thuộc 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. Việc sử dụng cùng một mã thông báo cho nhiều phiên sẽ khiến mỗi yêu cầu được tính phí riêng.

Nội dung phản hồi

Proto của 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ự mức độ liên quan giảm dần.

LocationBias

Khu vực sẽ tìm kiếm. Kết quả có thể không chính xác xung quanh 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 hợp type.

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

rectangle

object (Viewport)

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

circle

object (Circle)

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

LocationRestriction

Khu vực sẽ tìm kiếm. Kết quả sẽ được giới hạn ở 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 hợp type.

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

rectangle

object (Viewport)

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

circle

object (Circle)

Một đường 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 hợp kind.

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

placePrediction

object (PlacePrediction)

Dự đoán cho một Địa điểm.

queryPrediction

object (QueryPrediction)

Dự đoán cho một truy vấn.

PlacePrediction

Kết quả dự đoán cho một cụm từ dự đoán Tự động hoàn thành theo đị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 sử 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. Số nhận dạng này có thể được sử dụng trong các API khác chấp nhận ID địa điểm.

text

object (FormattableText)

Chứa tên mà con người có thể đọc được của kết quả được trả về. Đối với kết quả thành lập, đây thường là tên và địa chỉ 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. Các nhà phát triển muốn hiển thị 2 thành phần giao diện người dùng riêng biệt nhưng có liên quan đến giao diện người dùng có thể muốn sử dụng structuredFormat. Hai cách để thể hiện thông tin dự đoán về địa điểm là hai cách khác nhau. 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ể hỗ trợ nhiều ngôn ngữ nếu yêu cầu inputlanguageCode 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 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ụ chứa các đối tượng phân biệt 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ị 2 thành phần giao diện người dùng riêng biệt nhưng có liên quan với nhau. 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 có thể nên sử dụng text. Hai cách để thể hiện thông tin dự đoán về địa điểm là hai cách khác nhau. 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 phù hợp với Địa điểm này trong Bảng A hoặc Bảng B trong https://developers.google.com/maps/documentation/places/web-service/place-types.

Một loại là phân loại một Địa điểm. Các địa điểm có loại chung sẽ có các đặ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ố dự đoán như tuyến đường có thể không được điền vào trường này.

FormattableText

Văn bản biểu thị thông tin dự đoán về Địa điểm hoặc cụm từ tìm kiếm. 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 dùng nguyên trạng hoặc định dạng bằng matches.

matches[]

object (StringRange)

Danh sách các dải ô xác định vị trí yêu cầu đầu vào khớp trong text. Bạn có thể dùng các dải ô để định dạng các phần cụ thể của text. Chuỗi con có thể không khớp chính xác với input nếu kết quả trùng khớp được xác định bằng các tiêu chí khác ngoài việc 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 sắp xếp theo giá trị chênh lệch tăng dần.

StringRange

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

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

integer

Độ lệch dựa trên 0 của ký tự Unicode đầu tiên của chuỗi (bao gồm).

endOffset

integer

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

StructuredFormat

Chứa bảng chi tiết dự đoán địa điểm hoặc 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 có chứa tên cụ thể của Địa điểm đó. Đối với các truy vấn dự đoán, văn bản chính sẽ chứa truy vấn đó.

Văn bản phụ chứa các đối tượng địa lý khác biệt bổ sung (chẳng hạn như một 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)

Đại diện cho các đối tượng địa lý khác nhau (chẳng hạn như một thành phố hoặc khu vực) để xác định thêm Địa điểm hoặc tinh chỉnh truy vấn.

QueryPrediction

Kết quả dự đoán cho cụm từ 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)

Nội dung đượ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 văn bản có thể dùng trong đ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. Các nhà phát triển muốn hiển thị 2 thành phần giao diện người dùng riêng biệt nhưng có liên quan đến giao diện người dùng có thể muốn sử dụng structuredFormat. Đây là 2 cách thể hiện thông tin dự đoán của cụm từ tìm kiế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.

Có thể hỗ trợ nhiều ngôn ngữ nếu yêu cầu inputlanguageCode 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 chi tiết dự đoán cụm từ tìm kiếm thành văn bản chính chứa cụm từ tìm kiếm và văn bản phụ chứa các đối tượng riêng biệt khác (chẳng hạn như một thành phố hoặc vùng).

structuredFormat được đề xuất cho các nhà phát triển muốn hiển thị 2 thành phần giao diện người dùng riêng biệt nhưng có liên quan với nhau. 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 có thể nên sử dụng text. Đây là 2 cách thể hiện thông tin dự đoán của cụm từ tìm kiế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.