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

Dịch vụ Tự động hoàn thành (Mới) là một dịch vụ web trả về thông tin dự đoán về địa điểm 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à các giới hạn địa lý kiểm soát khu vực tìm kiếm.

Dịch vụ Tự động hoàn thành (Mới) có thể so khớp theo từ đầy đủ 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ã địa điểm. 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ề vị trí và truy vấn ngay lập tức.

Phản hồi từ API Tự động hoàn thành (Mới) có thể chứa hai loại dự đoán:

Dự đoán địa điểm: Các địa điểm, chẳng hạn như doanh nghiệp, địa chỉ và điểm tham quan, dựa trên chuỗi văn bản đầu vào và khu vực tìm kiếm đã chỉ định. Theo mặc định, hệ thống sẽ trả về kết quả dự đoán về địa điểm.
Dự đoán cụm từ tìm kiếm: Chuỗi truy vấn 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, hệ thống không trả về kết quả dự đoán cụm từ tìm kiếm. Sử dụng tham số yêu cầu includeQueryPredictions để thêm nội dung dự đoán truy vấn vào phản hồi.

Ví dụ: bạn gọi API bằng cách sử dụng một chuỗi chứa một phần dữ liệu đầu vào của người dùng, "Sicilian piz", với phạm vi tìm kiếm giới hạn ở San Francisco, California. Sau đó, phản hồi sẽ chứa một danh sách dự đoán đị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 đó.

Dự đoán địa điểm được trả về được thiết kế để hiển thị cho người dùng nhằm hỗ trợ họ chọn địa điểm mong muốn. Bạn có thể tạo yêu cầu Thông tin chi tiết về địa điểm (Mới) để biết thêm thông tin về bất kỳ địa điểm nào được dự đoán trả về.

Phản hồi cũng có thể chứa danh sách cụm từ tìm kiếm được gợi ý khớp với chuỗi tìm kiếm và khu vực tìm kiếm, chẳng hạn như "Pizza và mì ống kiểu Sicilia". Mỗi nội dung dự đoán truy vấn trong phản hồi bao gồm trường text chứa 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ính năng Tìm kiếm văn bản (Mới) để tìm kiếm chi tiết hơn.

Trình khám phá API cho phép bạn tạo các yêu cầu trực tiếp để làm quen với API và các tuỳ chọn API:

Hãy làm thử!

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

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

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

Truyền tất 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

Giới thiệu về phản hồi

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 được nhận thấy. Mỗi địa điểm được biểu thị bằng một trường placePrediction và mỗi truy vấn đượ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 dự đoán địa điểm, bao gồm 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 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. Ví dụ: nếu yêu cầu không đặt includeQueryPredictions, thì nội dung phản hồi sẽ bao gồm tối đa 5 placePredictions. Nếu yêu cầu đặt includeQueryPredictions, thì nội dung 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 cần tìm kiếm. Chỉ định từ đầy đủ và chuỗi con, tên địa điểm, địa chỉ và mã địa điểm. Dịch vụ Tự động hoàn thành (Mới) sẽ trả về các kết quả trùng khớp 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 được nhận thấy.

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 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.place và suggestions.placePrediction.text của nội dung đề xuất.
```
  X-Goog-FieldMask: places.displayName,places.formattedAddress
```
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: *
```
Ký tự đại diện "*" sẽ chọn tất cả các trường.
includedPrimaryTypes

Một địa điểm chỉ có thể có một loại chính 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 thông số input, bất kể giá trị loại chính được liên kết với địa điểm đó. Hạn chế kết quả thuộc 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 đưa vào phản hồi.

Thay vào đó, thông số này cũng có thể bao gồm một trong hai (regions) hoặc (cities). Bộ lọc thu thập loại (regions) cho các khu vực hoặc bộ phận, chẳng hạn như khu vực lân cận và mã bưu chính. Bộ lọc sưu tập loại (cities) cho 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:
- Chỉ định nhiều hơn 5 loại.
- Bất kỳ loại nào được chỉ định ngoài (cities) hoặc (regions).
- Mọi loại không được nhận dạng sẽ đượ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 hỗ trợ bởi API Địa điểm (Mới). 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 bạn đặt thành true, phản hồi sẽ bao gồm những doanh nghiệp trực tiếp đến thăm hoặc giao hàng cho khách hàng, nhưng không có địa điểm kinh doanh thực tế. Nếu bạn đặt thành false, API sẽ chỉ trả về những doanh nghiệp có địa điểm thực tế.
includeQueryPredictions

Nếu là true, phản hồi sẽ bao gồm cả thông tin gợi ý về địa điểm và cụm từ tìm kiếm. Giá trị mặc định là false, nghĩa là phản hồi chỉ bao gồm thông tin dự đoán về địa điểm.
includedRegionCodes

Chỉ bao gồm kết quả từ danh sách các khu vực được chỉ định, được chỉ định dưới dạng một mảng gồm tối đa 15 giá trị gồm hai ký tự ccTLD ("miền cấp cao nhất"). Nếu bạn bỏ qua, hệ thống sẽ không áp dụng quy định hạn chế nào 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, kết quả sẽ nằm trong vùng giao nhau của hai chế độ cài đặt.
inputOffset

Độ dời ký tự Unicode dựa trên 0 cho biết vị trí con trỏ trong input. Vị trí con trỏ có thể ảnh hưởng đến kết quả 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 Bản xem trước riêng tư ban đầu, thuộc tính này được gọi là predictionTermOffset.
languageCode

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

Bạn có thể chỉ định locationBias hoặc locationRestriction, nhưng không được chỉ định cả hai để xác định vùng tìm kiếm. Hãy coi locationRestriction là chỉ định vùng mà kết quả phải nằm trong đó và locationBias là chỉ định vùng mà kết quả phải nằm gần nhưng có thể nằm ngoài vùng đó.

Lưu ý: Nếu bạn bỏ qua cả locationBias và locationRestriction, thì theo mặc định, API sẽ sử dụng độ lệch IP. Với tính năng thiên vị IP, API sử dụng địa chỉ IP của thiết bị để thiên vị kết quả.
- locationBias
  
  Chỉ định một khu vực để tìm kiếm. Vị trí này đóng vai trò là độ lệch, nghĩa là kết quả xung quanh vị trí đã chỉ định có thể được trả về, bao gồm 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. Hệ thống sẽ không trả về kết quả nằm ngoài khu vực đã chỉ định.
Chỉ định vùng locationBias hoặc locationRestriction dưới dạng Khung nhìn hình chữ nhật hoặc dưới dạng vòng tròn.
- Đường 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 50000. 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à khung nhìn vĩ độ-kinh độ, được biểu thị dưới dạng hai low và điểm cao đối diện nhau theo đường chéo. Khung nhìn được coi là một vùng kín, nghĩa là bao gồm cả ranh giới của vùng đó. Giới hạn vĩ độ phải nằm trong khoảng từ -90 đến 90 độ và giới hạn kinh độ phải nằm trong khoảng từ -180 đến 180 độ:
  - 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ẽ bị đảo ngược (khung nhìn sẽ cắt ngang đườ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 và hộp được biểu thị không được để trống. Khung nhìn trống sẽ dẫn đến lỗi.
  
  Ví dụ: khung nhìn này bao gồm toàn bộ 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 gốc để tính khoảng cách theo đường thẳng đến đích đến (được trả về dưới dạng distanceMeters). Nếu bạn bỏ qua giá trị này, thì 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 dưới dạng giá trị hai ký tự ccTLD ("miền cấp cao nhất"). Hầu hết mã ccTLD giống với mã ISO 3166-1, ngoại trừ một số trường hợp ngoại lệ đáng chú ý. Ví dụ: ccTLD của Vương quốc Anh là "uk" (.co.uk) trong khi mã ISO 3166-1 là "gb" (về mặt kỹ thuật là cho thực thể "Vương quốc Anh và Bắc Ireland").

Nếu bạn chỉ định mã vùng không hợp lệ, API sẽ trả về lỗi INVALID_ARGUMENT. Thông 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à các 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 lượ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.

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

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

Theo mặc định, API sử dụng độ lệch IP để kiểm soát khu vực tìm kiếm. Với tính năng thiên vị IP, API sử dụng địa chỉ IP của thiết bị để thiên vị kết quả. Bạn có thể tuỳ ý sử dụng locationRestriction hoặc locationBias, nhưng không được sử dụng cả hai để chỉ định một khu vực cần tìm kiếm.

locationRestriction chỉ định khu vực để tìm kiếm. Hệ thống sẽ không trả về kết quả nằm ngoài khu vực đã chỉ định. Trong ví dụ sau, bạn sử dụng locationRestriction để giới hạn yêu cầu ở 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 đã 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 nội dung tìm kiếm ở Khung hiển thị 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ả được chứa 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"
          ]
        }
      }
    ]
  }

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

Với locationBias, vị trí đóng vai trò là độ lệch, nghĩa 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 đến trung tâm thành phố 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

Kết quả hiện chứa nhiều mục hơn, bao gồm cả kết quả nằm 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 nội dung tìm kiếm ở Khung hiển thị 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 nhìn 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 bị thiên vị. Kết quả cũng được chứa 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 từ 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 chuỗi input là "Soccer" (Bóng đá) và sử dụng tham số includedPrimaryTypes để giới hạn kết quả ở 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 nội dung gợi ý cụm từ tìm kiếm

Theo mặc định, hệ thống không trả về kết quả dự đoán cụm từ tìm kiếm. Sử dụng tham số yêu cầu includeQueryPredictions để thêm nội dung dự đoán 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

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

Lưu ý: Nội dung gợi ý truy vấn sẽ không được trả về khi bạn đặt tham số includedRegionCodes.

Sử dụng nguồn gốc

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, API 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. Ví dụ này đặt gốc thành 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

Phản hồi hiện 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
      }
    }
  ]
}

Hãy dùng thử!

Trình khám phá API cho phép bạn tạo các yêu cầu mẫu để bạn có thể làm quen với API và các tuỳ chọn API.

Hãy dùng thử!

Trình khám phá API cho phép bạn tạo các yêu cầu mẫu để bạn có thể làm quen với API và các tuỳ 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 sử dụng để gửi yêu cầu.
Trong bảng điều khiển Trình khám phá API, hãy chọn biểu tượng toàn màn hình fullscreen để mở rộng cửa sổ Trình khám phá API.

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

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

Giới thiệu 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

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

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

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

Sử dụng includedPrimaryTypes

Yêu cầu nội dung gợi ý cụm từ tìm kiếm

Sử dụng nguồn gốc

Hãy dùng thử!

Hãy dùng thử!