Method: places.autocomplete

Trả về các 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 với 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,
  "includePureServiceAreaBusinesses": boolean,
  "includeFutureOpeningBusinesses": boolean
}
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. Thiên vị kết quả cho một vị trí được chỉ định.

Bạn chỉ nên đặt tối đa một trong hai thuộc tính locationBias hoặc locationRestriction. Nếu bạn không đặt cả hai, kết quả sẽ bị ảnh hưởng bởi địa chỉ IP, tức là địa chỉ IP sẽ được liên kết với một vị trí không chính xác và được dùng làm tín hiệu ảnh hưởng.
locationRestriction

object (LocationRestriction)

Không bắt buộc. Giới hạn kết quả ở một vị trí cụ thể.

Bạn chỉ nên đặt tối đa một trong hai thuộc tính locationBias hoặc locationRestriction. Nếu bạn không đặt cả hai, kết quả sẽ bị ảnh hưởng bởi địa chỉ IP, tức là địa chỉ IP sẽ được liên kết với một vị trí không chính xác và được dùng làm tín hiệu ảnh hưởng.
includedPrimaryTypes[]

string

Không bắt buộc. Loại Địa điểm chính được đưa vào (ví dụ: "nhà hàng" hoặc "trạm xăng") trong Loại Địa điểm (https://developers.google.com/maps/documentation/places/web-service/place-types), hoặc chỉ (regions), hoặc chỉ (cities). Một Đị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 bạn không chỉ định loại nào, thì 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ả ở các khu vực được chỉ định, được chỉ định tối đa 15 mã khu vực gồm 2 ký tự theo quy ước của CLDR. Một tập hợp trố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 trong khu vực giao nhau.
languageCode

string

Không bắt buộc. Ngôn ngữ mà bạn muốn nhận kết quả. 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 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 CLDR gồm 2 ký tự. Điều này ảnh hưởng đến định dạng địa chỉ, thứ hạng kết quả và có thể ảnh hưởng đến những kết quả được trả về. Thao tá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ả trong một khu vực, hãy sử dụng region_code_restriction.
origin

object (LatLng)

Không bắt buộc. Điểm xuất phát để tính khoảng cách trắc địa đến đích đến (trả về dưới dạng distanceMeters). Nếu bạn bỏ qua giá trị này, 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 mốc 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 nội dung dự đoán được trả về.

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

boolean

Không bắt buộc. Nếu đúng, phản hồi sẽ bao gồm cả Địa điểm và cụm từ tìm kiếm dự đoán. Nếu không, phản hồi sẽ chỉ trả về các cụm từ 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à một chuỗi base64 an toàn cho URL và tên tệp, có độ dài tối đa 36 ký tự ASCII. Nếu không, lỗi INVALID_ARGUMENT sẽ được trả về.

Phiên bắt đầu khi người dùng bắt đầu nhập một 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 Place Details 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 Place Details hoặc Xác thực địa chỉ. Thông tin đăng nhập được dùng cho mỗi 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 sẽ không còn hợp lệ; ứng dụng của bạn phải tạo một mã thông báo mới cho mỗi phiên. Nếu bạn bỏ qua tham số sessionToken hoặc nếu bạn sử dụng lại mã thông báo phiên, thì phiên sẽ bị tính phí như thể bạn không cung cấp mã thông báo phiên (mỗi yêu cầu sẽ được tính phí riêng).

Bạn nên tuân thủ 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 Place Autocomplete.
  • Tạo một mã thông báo mới cho mỗi phiên. Bạn nên sử dụng UUID phiên bản 4.
  • Đảm bảo rằng thông tin xác thực được dùng cho tất cả các yêu cầu về Place Autocomplete, Place Details và Xác thực địa chỉ trong một phiên đều thuộc cùng một dự án trên Bảng điều khiển Cloud.
  • 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ẽ dẫn đến việc mỗi yêu cầu được tính phí riêng lẻ.
includePureServiceAreaBusinesses

boolean

Không bắt buộc. Bao gồm các doanh nghiệp chỉ cung cấp dịch vụ tại cơ sở khách hàng nếu trường được đặt thành true. Doanh nghiệp chỉ cung cấp dịch vụ tại cơ sở khách hàng là doanh nghiệp trực tiếp cung cấp dịch vụ tận nơi hoặc giao hàng cho khách hàng nhưng không phục vụ khách hàng tại địa chỉ doanh nghiệp. Ví dụ: Những doanh nghiệp cung cấp dịch vụ vệ sinh hoặc sửa ống nước. Những doanh nghiệp đó không có địa chỉ thực tế hoặc vị trí trên Google Maps. Places sẽ không trả về các trường, bao gồm location, plusCode và các trường khác liên quan đến vị trí cho những doanh nghiệp này.
includeFutureOpeningBusinesses

boolean

Không bắt buộc. Nếu đúng, hãy thêm những doanh nghiệp chưa mở cửa nhưng sẽ mở cửa trong tương lai.

Nội dung phản hồi

Giao thức 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.

Phạm vi uỷ quyền

Yêu cầu một trong các phạm vi OAuth sau:

  • https://www.googleapis.com/auth/maps-platform.places.autocomplete
  • https://www.googleapis.com/auth/maps-platform.places
  • https://www.googleapis.com/auth/cloud-platform

LocationBias

Vùng cần tìm kiếm. Kết quả có thể thiên 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 nhóm type.

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

object (Viewport)

Một khung hiển thị được xác định bằng một góc đông bắc và một góc tây nam.
circle

object (Circle)

Một hình tròn được xác định bằng điểm giữa và bán kính.

LocationRestriction

Vùng cần tìm kiếm. Kết quả sẽ bị 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 nhóm type.

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

object (Viewport)

Một khung hiển thị được xác định bằng một góc đông bắc và một góc tây nam.
circle

object (Circle)

Một hình tròn được xác định bằng điểm giữa 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 nhóm kind.

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

object (PlacePrediction)

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

object (QueryPrediction)

Thông tin dự đoán cho một cụm từ tìm kiếm.

PlacePrediction

Kết quả dự đoán cho một 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. Bạn có thể dùng tên này trong các API khác chấp nhận tên Địa điểm.
placeId

string

Giá trị nhận dạng riêng biệt của Địa điểm được đề xuất. Bạn có thể dùng giá trị nhận dạng này trong các 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 kết quả về cơ sở, đây thường là tên và địa chỉ của doanh nghiệp.

text là thành phần được đề xuất cho những nhà phát triển muốn hiển thị một phần tử giao diện người dùng duy nhất. Những nhà phát triển muốn hiển thị 2 thành phần riêng biệt nhưng có liên quan trên giao diện người dùng có thể muốn sử dụng structuredFormat. Đây là hai cách khác nhau để biểu thị một kết quả dự đoán Đị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)

Thông tin dự đoán về Địa điểm được chia thành văn bản chính chứa tên của Địa điểm và văn bản phụ chứa các đặc điểm bổ sung để phân biệt (chẳng hạn như thành phố hoặc khu vực).

structuredFormat được đề xuất cho những nhà phát triển muốn hiển thị 2 phần tử riêng biệt nhưng có liên quan trên giao diện người dùng. Những nhà phát triển muốn hiển thị một phần tử trên giao diện người dùng duy nhất có thể muốn sử dụng text. Đây là hai cách khác nhau để biểu thị một kết quả dự đoán Đị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 tại https://developers.google.com/maps/documentation/places/web-service/place-types.

Loại là một danh mục của Địa điểm. Những địa điểm có cùng loại 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 bạn chỉ định origin. Một số thông tin dự đoán (chẳng hạn như tuyến đường) có thể không xuất hiện trong trường này.

FormattableText

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

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 được định dạng bằng matches.
matches[]

object (StringRange)

Một danh sách các dải ô chuỗi xác định vị trí mà yêu cầu đầu vào khớp trong text. Bạn có thể dùng các dải ô này để định dạng các phần cụ thể của text. Các chuỗi con có thể không khớp chính xác với input nếu tiêu chí khớp không phải là tiêu chí khớp chuỗi (ví dụ: sửa lỗi chính tả hoặc chuyển tự).

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

StringRange

Xác định một 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

Độ lệch dựa trên số 0 của ký tự Unicode đầu tiên trong 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 thông tin chi tiết về một Địa điểm hoặc cụm từ gợi ý thành văn bản chính và văn bản phụ.

Đối với tính năng dự đoán Địa điểm, văn bản chính chứa tên cụ thể của Địa điểm. Đối với tính năng dự đoán cụm từ tìm kiếm, văn bản chính chứa cụm từ tìm kiếm.

Văn bản phụ chứa các đặc điểm bổ sung để phân biệt (chẳng hạn như thành phố hoặc khu vực) nhằm xác định Địa điểm hoặc tinh chỉnh cụm từ tìm kiếm.

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

object (FormattableText)

Biểu thị tên của Địa điểm hoặc cụm từ tìm kiếm.
secondaryText

object (FormattableText)

Biểu thị các đặc điểm bổ sung giúp phân biệt (chẳng hạn như 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 một cụm từ gợi ý của tính năng Tự động hoàn thành cụm từ tìm kiếm.

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 một Địa điểm, mà là một cụm từ tìm kiếm bằng văn bản 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 là thành phần được đề xuất cho những nhà phát triển muốn hiển thị một phần tử giao diện người dùng duy nhất. Những nhà phát triển muốn hiển thị 2 thành phần riêng biệt nhưng có liên quan trên giao diện người dùng có thể muốn sử dụng structuredFormat. Đây là hai cách khác nhau để biểu thị một cụm từ tìm kiếm dự đoá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ể sử dụng nhiều ngôn ngữ nếu yêu cầu input và languageCode có ngôn ngữ khác nhau hoặc nếu một phần của cụm từ tìm kiếm không có bản dịch từ ngôn ngữ địa phương sang languageCode.
structuredFormat

object (StructuredFormat)

Phân tích 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 tính năng bổ sung giúp phân biệt (chẳng hạn như thành phố hoặc khu vực).

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