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,
  "includePureServiceAreaBusinesses": boolean
}
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. Chuyển hướng kết quả đến 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 giá trị cho cả hai, thì kết quả sẽ bị thiên lệch theo đị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 thiên lệch.
locationRestriction

object (LocationRestriction)

Không bắt buộc. Hạn chế 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 giá trị cho cả hai, thì kết quả sẽ bị thiên lệch theo đị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 thiên lệch.
includedPrimaryTypes[]

string

Không bắt buộc. Đã thêm loại Địa điểm chính (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). Đị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, hệ thống sẽ trả về tất cả cá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. 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 vùng giao nhau.
languageCode

string

Không bắt buộc. Ngôn ngữ dùng để trả về kết quả. 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ự theo CLDR. Điều này ảnh hưởng đến cách định dạng địa chỉ, thứ hạng kết quả và có thể ảnh hưởng đến kết quả được trả về. Việc này không giới hạn kết quả ở khu vực đã chỉ định. Để hạn chế kết quả ở một khu vực, hãy sử dụng region_code_restriction.
origin

object (LatLng)

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

integer

Không bắt buộc. Độ dời 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 nội dung 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, phản hồi sẽ bao gồm cả thông tin dự đoán về Địa điểm và truy vấn. Nếu không, phản hồi sẽ chỉ trả về kết quả dự đoán 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à một URL và tên tệp an toàn ở định dạng base64, có độ dài tối đa 36 ký tự ASCII. Nếu không, hệ thống sẽ trả về lỗi INVALID_ARGUMENT.

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 lệnh 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 Chi tiết về địa điểm hoặc Xác thực địa chỉ. Thông tin xác thự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ệ nữa; ứ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 thông số sessionToken hoặc sử dụng lại mã thông báo phiên, thì phiên 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 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 Tự động hoàn thành địa điểm.
  • Tạo 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 xác thực dùng cho tất cả các yêu cầu Tự động hoàn thành địa điểm, Thông tin chi tiết về địa điểm và Xác thực địa chỉ trong một phiên đều thuộc cùng một dự án trê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 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 bạn đặt trường này thành true. Doanh nghiệp hoạt động tại khu vực kinh doanh thuần tuý 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 của họ. 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. Đối với những doanh nghiệp này, 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í.

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ể bị thiên lệch xung quanh khu vự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 hợp nhất type.

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

object (Viewport)

Một khung nhìn được xác định bởi một góc hướng Đông Bắc và một góc hướng 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 hợp hợp nhất type.

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

object (Viewport)

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

object (Circle)

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

Đề xuất

Kết quả đề xuất của tính năng 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 giá trị sau:
placePrediction

object (PlacePrediction)

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

object (QueryPrediction)

Kết quả 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ể sử 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 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 những 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. 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ó thể muố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 nhiều ngôn ngữ 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).

Bạn nên sử dụng structuredFormat cho những nhà phát triển muốn hiển thị hai thành phần trê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à một cách phân loại Địa điểm. Những địa điểm có cùng loại sẽ có các đặc điểm tương tự nhau.
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ố thông tin dự đoán như tuyến đường có thể không điền vào trường này.

FormattableText

Văn bản đại diện cho một Địa điểm hoặc cụm từ tìm kiếm được gợi ý. Bạn có thể sử dụng văn bản như hiện có 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 định dạng bằng matches.
matches[]

object (StringRange)

Danh sách các dải chuỗi xác định vị trí yêu cầu đầu vào khớp 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 khớp chính xác với input nếu việc so khớp được xác định theo 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 phiên âm).

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

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

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

integer

Độ dời 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 nội dung dự đoán cụm từ tìm kiếm thành văn bản chính và văn bản phụ.

Đối với kết quả 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 nội dung 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 khác giúp phân biệt (chẳng hạn như thành phố hoặc khu vực) để xác định rõ hơn Đị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 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) để xác định rõ hơn Địa điểm hoặc tinh chỉnh truy vấn.

QueryPrediction

Kết quả dự đoán cho 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 Đị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. 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ó thể muốn sử dụng structuredFormat. Đây là hai cách khác nhau để thể hiện nội dung 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 nhiều ngôn ngữ nếu yêu cầu input và languageCode bằng nhiều ngôn ngữ 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ữ bản địa 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).

Bạn nên sử dụng structuredFormat cho những nhà phát triển muốn hiển thị hai thành phần trên giao diện người dùng riêng biệt nhưng có liên quan. 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ể sử dụng text. Đây là hai cách khác nhau để thể hiện nội dung 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.