Trang này được dịch bởi Cloud Translation API.

Tự động hoàn thành (Mới)

Chọn nền tảng: Android iOS JavaScript Dịch vụ web

Nhà phát triển ở Khu vực kinh tế Châu Âu (EEA)

Giới thiệu

Tính năng Tự động hoàn thành (Mới) là một dịch vụ web trả về các cụm từ gợi ý về địa điểm và cụm từ gợi ý về cụm từ tìm kiếm để phản hồi một yêu cầu HTTP. Trong yêu cầu, hãy chỉ định một chuỗi tìm kiếm văn bản và ranh giới địa lý kiểm soát khu vực tìm kiếm.

Tính năng Tự động hoàn thành (Mới) có thể so khớp với toàn bộ từ và chuỗi con của dữ liệu đầu vào, phân giải tên địa điểm, địa chỉ và mã cộng. Do đó, các ứng dụng có thể gửi truy vấn khi người dùng nhập để cung cấp thông tin dự đoán về địa điểm và truy vấn ngay lập tức.

Phản hồi từ tính năng Tự động hoàn thành (Mới) có thể chứa 2 loại cụm từ gợi ý:

Đề xuất địa điểm: Các địa điểm, chẳng hạn như doanh nghiệp, địa chỉ và địa điểm yêu thích, dựa trên chuỗi văn bản đầu vào và khu vực tìm kiếm được chỉ định. Theo mặc định, các đề xuất về địa điểm sẽ được trả về.
Đề xuất cụm từ tìm kiếm: Cụm từ tìm kiếm khớp với chuỗi văn bản đầu vào và khu vực tìm kiếm. Theo mặc định, các cụm từ tìm kiếm dự đoán sẽ không được trả về. Sử dụng tham số yêu cầu includeQueryPredictions để thêm các cụm từ dự đoán cho truy vấn vào phản hồi.

Ví dụ: bạn gọi tính năng Tự động hoàn thành (Mới) bằng cách sử dụng làm đầu vào một chuỗi chứa một phần thông tin đầu vào của người dùng, "Sicilian piz", với khu vực tìm kiếm giới hạn ở San Francisco, California. Sau đó, phản hồi sẽ chứa một danh sách đề xuất địa điểm khớp với chuỗi tìm kiếm và khu vực tìm kiếm, chẳng hạn như nhà hàng có tên "Sicilian Pizza Kitchen", cùng với thông tin chi tiết về địa điểm đó.

Đề xuất địa điểm được trả về được thiết kế để trình bày cho người dùng nhằm hỗ trợ họ chọn địa điểm dự kiến. Bạn có thể đưa ra yêu cầu Place Details (New) để biết thêm thông tin về bất kỳ kết quả dự đoán địa điểm nào được trả về.

Phản hồi cũng có thể chứa danh sách cụm từ gợi ý cho truy vấn phù hợp với chuỗi tìm kiếm và khu vực tìm kiếm, chẳng hạn như "Sicilian Pizza & Pasta". Mỗi cụm từ tìm kiếm dự đoán trong phản hồi đều có trường text chứa một chuỗi tìm kiếm văn bản được đề xuất. Sử dụng chuỗi đó làm dữ liệu đầu vào cho Tìm kiếm bằng văn bản (Mới) để thực hiện một lượt tìm kiếm chi tiết hơn.

APIs Explorer cho phép bạn đưa ra các yêu cầu trực tiếp để có thể làm quen với API và các lựa chọn API:

Hãy làm thử!

Yêu cầu Tự động hoàn thành (Mới)

Yêu cầu Autocomplete (Mới) là một yêu cầu HTTP POST đến một URL ở dạng:

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

Truyền tất cả các tham số trong nội dung yêu cầu JSON hoặc trong tiêu đề như một phần của yêu cầu POST. Ví dụ:

curl -X POST -d '{
  "input": "pizza",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Các tham số được hỗ trợ

Tham số	Nội dung mô tả
`input`*	Chuỗi văn bản để tìm kiếm (từ đầy đủ, chuỗi con, tên địa điểm, địa chỉ, mã cộng).
`FieldMask` (Tiêu đề HTTP)	Danh sách được phân tách bằng dấu phẩy, chỉ định những trường cần trả về trong phản hồi.
`includedPrimaryTypes`	Giới hạn kết quả ở những địa điểm khớp với một trong tối đa 5 loại chính được chỉ định.
`includePureServiceAreaBusinesses`	Nếu đúng, bao gồm cả những doanh nghiệp không có địa điểm thực tế (doanh nghiệp cung cấp dịch vụ tại cơ sở khách hàng). Giá trị mặc định là false.
`includeQueryPredictions`	Nếu đúng, hãy thêm cả dự đoán về địa điểm và truy vấn vào phản hồi. Giá trị mặc định là false.
`includedRegionCodes`	Mảng gồm tối đa 15 mã quốc gia gồm 2 ký tự để hạn chế kết quả.
`inputOffset`	Độ lệch ký tự Unicode dựa trên 0 của vị trí con trỏ trong chuỗi đầu vào, ảnh hưởng đến các dự đoán. Giá trị mặc định là độ dài đầu vào.
`languageCode`	Ngôn ngữ ưu tiên (mã IETF BCP-47) cho kết quả. Mặc định là tiêu đề Accept-Language hoặc "en".
`locationBias`	Chỉ định một khu vực (hình tròn hoặc hình chữ nhật) để điều chỉnh kết quả tìm kiếm, cho phép kết quả nằm ngoài khu vực. Không thể dùng với locationRestriction.
`locationRestriction`	Chỉ định một khu vực (hình tròn hoặc hình chữ nhật) để hạn chế kết quả tìm kiếm trong khu vực đó. Kết quả bên ngoài khu vực này sẽ bị loại trừ. Không thể dùng với locationBias.
`origin`	Điểm xuất phát (vĩ độ, kinh độ) dùng để tính khoảng cách theo đường thẳng (distanceMeters) đến các đích đến dự đoán.
`regionCode`	Mã khu vực dùng để định dạng phản hồi và đề xuất thiên vị (ví dụ: 'uk', 'fr').
`sessionToken`	Chuỗi do người dùng tạo để nhóm các lệnh gọi Tự động hoàn thành thành một phiên cho mục đích thanh toán.

* Biểu thị trường bắt buộc.

Thông tin về phản hồi

Tính năng Tự động hoàn thành (Mới) trả về một đối tượng JSON dưới dạng phản hồi. Trong phản hồi:

Mảng suggestions chứa tất cả các địa điểm và cụm từ tìm kiếm được dự đoán theo thứ tự dựa trên mức độ liên quan mà người dùng cảm nhận được. Mỗi địa điểm được biểu thị bằng một trường placePrediction và mỗi cụm từ tìm kiếm được biểu thị bằng một trường queryPrediction.
Trường placePrediction chứa thông tin chi tiết về một kết quả dự đoán duy nhất về địa điểm, bao gồm cả mã địa điểm và nội dung mô tả bằng văn bản.
Trường queryPrediction chứa thông tin chi tiết về một cụm từ dự đoán truy vấn.

Lưu ý: Tính năng Tự động hoàn thành (Mới) trả về tổng cộng 5 cụm từ gợi ý, dưới dạng placePredictions, queryPredictions hoặc kết hợp cả hai, tuỳ thuộc vào yêu cầu. Nếu yêu cầu không đặt includeQueryPredictions, thì phản hồi sẽ bao gồm tối đa 5 placePredictions. Nếu yêu cầu đặt includeQueryPredictions, thì phản hồi sẽ bao gồm tối đa 5 cụm từ gợi ý kết hợp giữa placePredictions và queryPredictions.

Đối tượng JSON hoàn chỉnh có dạng:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }]
        },
      ...
    },
    {
      "queryPrediction": {
        "text": {
          "text": "Amoeba Music",
          "matches": [
            {
              "endOffset": 6
            }]
        },
        ...
    }
  ...]
}

Thông số bắt buộc

input

Chuỗi văn bản mà bạn muốn tìm kiếm. Chỉ định toàn bộ từ và chuỗi con, tên địa điểm, địa chỉ và mã địa chỉ. Dịch vụ Autocomplete (Mới) trả về các kết quả trùng khớp đề xuất dựa trên chuỗi này và sắp xếp kết quả dựa trên mức độ liên quan mà người dùng cảm nhận được.

Thông số tùy chọn

FieldMask

Chỉ định danh sách các trường cần trả về trong phản hồi bằng cách tạo một mặt nạ trường phản hồi. Truyền mặt nạ trường phản hồi đến phương thức bằng cách sử dụng tiêu đề HTTP X-Goog-FieldMask.

Chỉ định danh sách các trường đề xuất được phân tách bằng dấu phẩy để trả về. Ví dụ: để truy xuất suggestions.placePrediction.text.text và suggestions.queryPrediction.text.text của đề xuất.
```
  X-Goog-FieldMask: suggestions.placePrediction.text.text,suggestions.queryPrediction.text.text
```
Lưu ý: Không được dùng dấu cách ở bất kỳ vị trí nào trong danh sách trường.

Sử dụng * để truy xuất tất cả các trường.
```
  X-Goog-FieldMask: *
```
includedPrimaryTypes

Một địa điểm chỉ có thể có một loại chính duy nhất trong số các loại được liệt kê trong Bảng A hoặc Bảng B. Ví dụ: loại chính có thể là "mexican_restaurant" hoặc "steak_house".

Theo mặc định, API sẽ trả về tất cả địa điểm dựa trên tham số input, bất kể giá trị loại chính nào được liên kết với địa điểm đó. Hạn chế kết quả ở một loại chính hoặc các loại chính nhất định bằng cách truyền tham số includedPrimaryTypes.

Sử dụng tham số này để chỉ định tối đa 5 giá trị loại trong Bảng A hoặc Bảng B. Một địa điểm phải khớp với một trong các giá trị loại chính được chỉ định để có thể đưa vào phản hồi.

Thay vào đó, tham số này cũng có thể bao gồm một trong hai tham số (regions) hoặc (cities). Bộ sưu tập loại (regions) lọc theo khu vực hoặc phân chia, chẳng hạn như vùng lân cận và mã bưu chính. Bộ sưu tập loại (cities) lọc những địa điểm mà Google xác định là thành phố.

Yêu cầu sẽ bị từ chối kèm theo lỗi INVALID_REQUEST nếu:
- Bạn chỉ định nhiều hơn 5 loại.
- Bạn có thể chỉ định bất kỳ loại nào ngoài (cities) hoặc (regions).
- Mọi loại không nhận dạng được đều được chỉ định.
Lưu ý: Tham số includedPrimaryTypes chỉ hoạt động trên loại chính của địa điểm, chứ không phải tất cả các loại được liên kết với địa điểm đó. Mặc dù mỗi địa điểm đều có một loại chính, nhưng không phải loại chính nào cũng được Places API (mới) hỗ trợ. Các loại được hỗ trợ bao gồm những loại được liệt kê trong Bảng A hoặc Bảng B.
includePureServiceAreaBusinesses

Nếu được đặt thành true, phản hồi sẽ bao gồm những doanh nghiệp đến gặp hoặc giao hàng trực tiếp cho khách hàng, nhưng không có địa điểm kinh doanh thực tế. Nếu được đặt thành false, API sẽ chỉ trả về những doanh nghiệp có địa điểm kinh doanh thực tế.
includeQueryPredictions

Nếu true, phản hồi sẽ bao gồm cả cụm từ gợi ý về địa điểm và cụm từ gợi ý về truy vấn. Giá trị mặc định là false, tức là phản hồi chỉ bao gồm các đề xuất về địa điểm.
includedRegionCodes

Chỉ bao gồm kết quả trong danh sách các khu vực được chỉ định, được chỉ định dưới dạng một mảng có tối đa 15 giá trị ccTLD ("miền cấp cao nhất") gồm 2 ký tự. Nếu bạn bỏ qua tham số này, thì sẽ không có quy tắc hạn chế nào được áp dụng cho phản hồi. Ví dụ: để giới hạn các khu vực ở Đức và Pháp:
```
    "includedRegionCodes": ["de", "fr"]
```
Nếu bạn chỉ định cả locationRestriction và includedRegionCodes, thì kết quả sẽ nằm trong khu vực giao nhau của hai chế độ cài đặt.

Lưu ý: Nếu bạn nhận được kết quả không mong muốn với một mã quốc gia, hãy xác minh rằng bạn đang sử dụng mã bao gồm các quốc gia, lãnh thổ phụ thuộc và khu vực đặc biệt mà bạn dự định quan tâm về mặt địa lý. Bạn có thể tìm thông tin về mã tại Wikipedia: Danh sách mã quốc gia theo tiêu chuẩn ISO 3166 hoặc Nền tảng duyệt web trực tuyến của ISO.
inputOffset

Độ lệch ký tự Unicode dựa trên mốc 0 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ị này sẽ mặc định là độ dài của input.

Lưu ý: Trong bản phát hành Restricted Preview (Xem trước có giới hạn) ban đầu, thuộc tính này có tên là predictionTermOffset.
languageCode

Ngôn ngữ ưu tiên để trả về kết quả. 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 giá trị do languageCode chỉ định, 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.
- Bạn phải sử dụng mã ngôn ngữ IETF BCP-47 để chỉ định ngôn ngữ ưu tiên.
- Nếu bạn không cung cấp languageCode, API sẽ sử dụng giá trị được chỉ định trong tiêu đề Accept-Language. Nếu bạn không chỉ định thuộc tính nào, giá trị mặc định sẽ là en. Nếu bạn chỉ định một mã ngôn ngữ không hợp lệ, API sẽ trả về lỗi INVALID_ARGUMENT.
- Ngôn ngữ ưu tiên có ảnh hưởng nhỏ đến tập hợp kết quả mà API chọn trả về và thứ tự trả về. Điều này cũng ảnh hưởng đến khả năng sửa lỗi chính tả của API.
- API này cố gắng cung cấp một địa chỉ đường phố mà cả người dùng và người dân địa phương đều có thể đọc được, đồng thời phản ánh thông tin đầu vào của người dùng. Đề xuất địa điểm được định dạng khác nhau tuỳ thuộc vào thông tin đầu vào của người dùng trong mỗi yêu cầu.
  - Các cụm từ trùng khớp trong tham số input sẽ được chọn trước, sử dụng tên phù hợp với lựa chọn ưu tiên về ngôn ngữ do tham số languageCode chỉ định (nếu có), nếu không thì sử dụng tên phù hợp nhất với thông tin đầu vào của người dùng.
  - Địa chỉ đường phố được định dạng bằng ngôn ngữ địa phương, bằng một tập lệnh mà người dùng có thể đọc được (nếu có thể), chỉ sau khi các cụm từ trùng khớp được chọn để khớp với các cụm từ trong tham số input.
  - Tất cả các địa chỉ khác đều được trả về bằng ngôn ngữ ưu tiên, sau khi các cụm từ khớp đã được chọn để khớp với các cụm từ trong tham số input. Nếu không có tên bằng ngôn ngữ ưu tiên, API sẽ sử dụng tên gần giống nhất.
locationBias hoặc locationRestriction

Bạn có thể chỉ định locationBias hoặc locationRestriction (chỉ 1 trong 2) để xác định khu vực tìm kiếm. Hãy coi locationRestriction là chỉ định khu vực mà kết quả phải nằm trong, còn locationBias là chỉ định khu vực mà kết quả phải ở gần nhưng có thể nằm ngoài khu vực.

Lưu ý: Nếu bạn bỏ qua cả locationBias và locationRestriction, thì tính năng Tự động hoàn thành (Mới) sẽ sử dụng tính năng thiên vị IP theo mặc định. Với tính năng điều chỉnh theo IP, tính năng Tự động hoàn thành (Mới) sẽ sử dụng địa chỉ IP của thiết bị để điều chỉnh kết quả.
- locationBias
  
  Chỉ định một khu vực để tìm kiếm. Vị trí này đóng vai trò là một thiên kiến, tức là kết quả xung quanh vị trí đã chỉ định có thể được trả về, kể cả kết quả bên ngoài khu vực đã chỉ định.
- locationRestriction
  
  Chỉ định một khu vực để tìm kiếm. Kết quả bên ngoài khu vực được chỉ định sẽ không được trả về.
Chỉ định vùng locationBias hoặc locationRestriction dưới dạng Viewport hình chữ nhật hoặc dưới dạng hình tròn.
- Một hình tròn được xác định bằng tâm điểm và bán kính tính bằng mét. Bán kính phải nằm trong khoảng từ 0 đến 50.000. Giá trị mặc định là 0.0. Đối với locationRestriction, bạn phải đặt bán kính thành một giá trị lớn hơn 0.0. Nếu không, yêu cầu sẽ không trả về kết quả nào.
  
  Ví dụ:
```
"locationBias": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}
```
- Hình chữ nhật là một khung nhìn vĩ độ-kinh độ, được biểu thị dưới dạng hai điểm low và điểm cao đối diện theo đường chéo. Khung nhìn được coi là một vùng khép kín, tức là bao gồm cả ranh giới của vùng đó. Phạm vi vĩ độ phải nằm trong khoảng từ -90 đến 90 độ (bao gồm cả hai giá trị này), còn phạm vi kinh độ phải nằm trong khoảng từ -180 đến 180 độ (bao gồm cả hai giá trị này):
  - Nếu low = high, khung nhìn sẽ bao gồm một điểm duy nhất đó.
  - Nếu low.longitude > high.longitude, thì dải kinh độ sẽ đảo ngược (khung nhìn vượt qua đường kinh độ 180 độ).
  - Nếu low.longitude = -180 độ và high.longitude = 180 độ, thì khung nhìn sẽ bao gồm tất cả kinh độ.
  - Nếu low.longitude = 180 độ và high.longitude = -180 độ, thì phạm vi kinh độ sẽ trống.
  Bạn phải điền cả low và high, đồng thời không được để trống hộp được biểu thị. Khung hiển thị trống sẽ gây ra lỗi.
  
  Ví dụ: khung hiển thị này bao trọn Thành phố New York:
```
"locationBias": {
  "rectangle": {
    "low": {
      "latitude": 40.477398,
      "longitude": -74.259087
    },
    "high": {
      "latitude": 40.91618,
      "longitude": -73.70018
    }
  }
}
```
nguồn gốc

Điểm xuất phát để tính khoảng cách theo đường thẳng đến đích đến (trả về dưới dạng distanceMeters). Nếu bạn bỏ qua giá trị này, khoảng cách theo đường thẳng sẽ không được trả về. Phải được chỉ định dưới dạng toạ độ vĩ độ và kinh độ:
```
"origin": {
    "latitude": 40.477398,
    "longitude": -74.259087
}
```
regionCode

Mã khu vực dùng để định dạng phản hồi, được chỉ định là giá trị gồm 2 ký tự ccTLD ("miền cấp cao nhất"). Hầu hết mã ccTLD đều giống với mã ISO 3166-1, ngoại trừ một số trường hợp đáng chú ý. Ví dụ: ccTLD của Vương quốc Anh là "uk" (.co.uk) trong khi mã ISO 3166-1 của quốc gia này là "gb" (về mặt kỹ thuật là cho thực thể "Vương quốc Anh và Bắc Ireland").

Đề xuất cũng bị thiên vị dựa trên mã vùng. Google đề xuất bạn đặt regionCode theo lựa chọn ưu tiên về khu vực của người dùng.

Nếu bạn chỉ định mã vùng không hợp lệ, API sẽ trả về lỗi INVALID_ARGUMENT. Tham số này có thể ảnh hưởng đến kết quả dựa trên luật hiện hành.
sessionToken

Mã thông báo phiên là chuỗi do người dùng tạo để theo dõi các lệnh gọi Tự động hoàn thành (Mới) dưới dạng "phiên". Tính năng Tự động hoàn thành (Mới) sử dụng mã thông báo phiên để nhóm các giai đoạn truy vấn và lựa chọn của một cụm từ tìm kiếm tự động hoàn thành của người dùng thành một phiên riêng biệt cho mục đích thanh toán. Để biết thêm thông tin, hãy xem phần Mã thông báo phiên.

Chọn các tham số để điều chỉnh kết quả

Các tham số Tự động hoàn thành (Mới) có thể ảnh hưởng đến kết quả tìm kiếm theo cách khác. Bảng sau đây đưa ra các đề xuất về cách sử dụng tham số dựa trên kết quả dự kiến.

Thông số	Đề xuất sử dụng
`regionCode`	Đặt theo lựa chọn ưu tiên theo khu vực của người dùng.
`includedRegionCodes`	Đặt để giới hạn kết quả trong danh sách các khu vực được chỉ định.
`locationBias`	Sử dụng khi bạn muốn kết quả ở trong hoặc xung quanh một khu vực. Nếu có thể, hãy xác định khu vực là khung hiển thị của bản đồ mà người dùng đang xem.
`locationRestriction`	Chỉ sử dụng only khi không nên trả về kết quả bên ngoài một khu vực.
`origin`	Sử dụng khi bạn muốn biết khoảng cách theo đường thẳng đến từng dự đoán. Lưu ý: Không phải dự đoán nào cũng có khoảng cách. Xem phần Thiếu khoảng cách trong phản hồi.

Ví dụ về tính năng Tự động hoàn thành (Mới)

Hạn chế tìm kiếm trong một khu vực bằng cách sử dụng locationRestriction

Lưu ý: Tính năng Tự động hoàn thành (Mới) sử dụng tính năng thiên vị IP theo mặc định để kiểm soát khu vực tìm kiếm. Với tính năng ưu tiên IP, tính năng Tự động hoàn thành (Mới) sẽ sử dụng địa chỉ IP của thiết bị để ưu tiên kết quả. Bạn có thể dùng locationRestriction hoặc locationBias (nhưng không được dùng cả hai) để chỉ định một khu vực tìm kiếm (không bắt buộc).

locationRestriction chỉ định khu vực cần tìm kiếm. Kết quả bên ngoài khu vực được chỉ định sẽ không được trả về. Trong ví dụ sau, bạn sử dụng locationRestriction để giới hạn yêu cầu trong một vòng tròn có bán kính 5.000 mét, tâm là San Francisco:

curl -X POST -d '{
  "input": "Art museum",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Tất cả kết quả trong các khu vực được chỉ định đều nằm trong mảng suggestions:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "museum",
            "point_of_interest"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJI7NivpmAhYARSuRPlbbn_2w",
          "placeId": "ChIJI7NivpmAhYARSuRPlbbn_2w",
          "text": {
            "text": "de Young Museum, Hagiwara Tea Garden Drive, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 15
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "de Young Museum",
              "matches": [
                {
                  "endOffset": 15
                }
              ]
            },
            "secondaryText": {
              "text": "Hagiwara Tea Garden Drive, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "point_of_interest",
            "tourist_attraction",
            "museum"
          ]
        }
      },
      /.../
    ]
  }

Bạn cũng có thể sử dụng locationRestriction để giới hạn phạm vi tìm kiếm trong một khung nhìn hình chữ nhật. Ví dụ sau đây giới hạn yêu cầu ở khu vực trung tâm San Francisco:

  curl -X POST -d '{
    "input": "Art museum",
    "locationRestriction": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

Kết quả nằm trong mảng suggestions:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "museum",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJyQNK-4SAhYARO2DZaJleWRc",
          "placeId": "ChIJyQNK-4SAhYARO2DZaJleWRc",
          "text": {
            "text": "International Art Museum of America, Market Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 14,
                "endOffset": 24
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "International Art Museum of America",
              "matches": [
                {
                  "startOffset": 14,
                  "endOffset": 24
                }
              ]
            },
            "secondaryText": {
              "text": "Market Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "museum",
            "point_of_interest",
            "tourist_attraction",
            "art_gallery",
            "establishment"
          ]
        }
      }
    ]
  }

Tìm kiếm thiên về một khu vực bằng cách sử dụng locationBias

Với locationBias, vị trí này đóng vai trò là một thiên kiến, tức là kết quả xung quanh vị trí được chỉ định có thể được trả về, bao gồm cả kết quả bên ngoài khu vực được chỉ định. Trong ví dụ sau, bạn sẽ thiên vị yêu cầu đối với khu vực trung tâm San Francisco:

curl -X POST -d '{
  "input": "Amoeba",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Giờ đây, kết quả chứa nhiều mục hơn, bao gồm cả kết quả bên ngoài bán kính 5.000 mét:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "store",
          "establishment",
          "home_goods_store"
        ]
      }
    },
    {
      "placePrediction": {
        "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
        "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
        "text": {
          "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Telegraph Avenue, Berkeley, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "establishment",
          "home_goods_store",
          "store"
        ]
      }
    },
    ...
  ]
}

Bạn cũng có thể sử dụng locationBias để giới hạn phạm vi tìm kiếm trong một khung nhìn hình chữ nhật. Ví dụ sau đây giới hạn yêu cầu ở khu vực trung tâm San Francisco:

  curl -X POST -d '{
    "input": "Amoeba",
    "locationBias": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

Mặc dù kết quả tìm kiếm trong khung hình chữ nhật xuất hiện trong phản hồi, nhưng một số kết quả nằm ngoài ranh giới đã xác định do thiên vị. Kết quả cũng nằm trong mảng suggestions:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "text": {
            "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Haight Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
          "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
          "text": {
            "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Telegraph Avenue, Berkeley, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJRdmfADq_woARYaVhnfQSUTI",
          "placeId": "ChIJRdmfADq_woARYaVhnfQSUTI",
          "text": {
            "text": "Amoeba Music, Hollywood Boulevard, Los Angeles, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Hollywood Boulevard, Los Angeles, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
    /.../
    ]
  }

Sử dụng includedPrimaryTypes

Sử dụng tham số includedPrimaryTypes để chỉ định tối đa 5 giá trị loại trong Bảng A, Bảng B hoặc chỉ (regions), hoặc chỉ (cities). Một địa điểm phải khớp với một trong các giá trị loại chính được chỉ định để được đưa vào phản hồi.

Trong ví dụ sau, bạn chỉ định một chuỗi input là "Bóng đá" và sử dụng tham số includedPrimaryTypes để hạn chế kết quả đối với các cơ sở thuộc loại "sporting_goods_store":

curl -X POST -d '{
  "input": "Soccer",
  "includedPrimaryTypes": ["sporting_goods_store"],
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Nếu bạn bỏ qua tham số includedPrimaryTypes, thì kết quả có thể bao gồm các cơ sở thuộc loại mà bạn không muốn, chẳng hạn như "athletic_field".

Yêu cầu dự đoán cụm từ tìm kiếm

Theo mặc định, các cụm từ tìm kiếm dự đoán sẽ không được trả về. Sử dụng tham số yêu cầu includeQueryPredictions để thêm các cụm từ dự đoán cho truy vấn vào phản hồi. Ví dụ:

curl -X POST -d '{
  "input": "Amoeba",
  "includeQueryPredictions": true,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Giờ đây, mảng suggestions chứa cả cụm từ gợi ý về địa điểm và cụm từ gợi ý về truy vấn như minh hoạ ở trên trong phần Giới thiệu về phản hồi. Mỗi cụm từ tìm kiếm dự đoán đều có trường text chứa một chuỗi tìm kiếm văn bản được đề xuất. Bạn có thể đưa ra yêu cầu Tìm kiếm bằng văn bản (Mới) để biết thêm thông tin về bất kỳ dự đoán nào về cụm từ tìm kiếm được trả về.

Lưu ý: Cụm từ gợi ý tìm kiếm sẽ không được trả về khi bạn đặt tham số includedRegionCodes.

Sử dụng nguồn

Trong ví dụ này, hãy thêm origin vào yêu cầu dưới dạng toạ độ vĩ độ và kinh độ. Khi bạn thêm origin, tính năng Tự động hoàn thành (Mới) sẽ thêm trường distanceMeters vào phản hồi. Trường này chứa khoảng cách theo đường thẳng từ origin đến đích đến. Ví dụ này đặt điểm gốc ở trung tâm của San Francisco:

curl -X POST -d '{
  "input": "Amoeba",
  "origin": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Giờ đây, phản hồi bao gồm distanceMeters:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "home_goods_store",
          "establishment",
          "point_of_interest",
          "store",
          "electronics_store"
        ],
        "distanceMeters": 3012
      }
    }
  ]
}

Thiếu khoảng cách trong câu trả lời

Trong một số trường hợp, distanceMeters bị thiếu trong phần nội dung phản hồi, ngay cả khi origin được đưa vào yêu cầu. Điều này có thể xảy ra trong các trường hợp sau:

distanceMeters không được đưa vào thông tin dự đoán route.
distanceMeters không được đưa vào khi giá trị của nó là 0. Đây là trường hợp đối với những dự đoán cách vị trí origin được cung cấp dưới 1 mét.

Các thư viện ứng dụng cố gắng đọc trường distanceMeters ra khỏi một đối tượng đã phân tích cú pháp sẽ trả về một trường có giá trị 0. Để tránh đánh lừa người dùng, đừng hiển thị khoảng cách bằng 0 cho người dùng.

Hãy dùng thử!

APIs Explorer cho phép bạn đưa ra các yêu cầu mẫu để có thể làm quen với API và các lựa chọn API.

Chọn biểu tượng API api ở bên phải trang.
Bạn có thể chỉnh sửa các tham số yêu cầu (không bắt buộc).
Chọn nút Thực thi. Trong hộp thoại, hãy chọn tài khoản mà bạn muốn dùng để đưa ra yêu cầu.
Trong bảng điều khiển APIs Explorer, hãy chọn biểu tượng toàn màn hình fullscreen để mở rộng cửa sổ APIs Explorer.

Tự động hoàn thành (Mới)

Giới thiệu

Yêu cầu Tự động hoàn thành (Mới)

Các tham số được hỗ trợ

Thông tin về phản hồi

Thông số bắt buộc

input

Thông số tùy chọn

FieldMask

includedPrimaryTypes

includePureServiceAreaBusinesses

includeQueryPredictions

includedRegionCodes

inputOffset

languageCode

locationBias hoặc locationRestriction

locationBias

locationRestriction

nguồn gốc

regionCode

sessionToken