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:

  • Cụm từ gợi ý về địa điểm: Những đị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 đã nhập và khu vực tìm kiếm được 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. Các dự đoán truy vấn không được trả về theo mặc định. 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ể đưa ra yêu cầu Chi tiết địa điểm (Mới) để nhận thêm thông tin về mọi dự đoán về địa điểm đượ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 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.

API Explorer cho phép bạn đưa ra các yêu cầu trực tiếp để bạn có thể 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 qua HTTP tới một URL có 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 mà chúng tôi nhận thấy được. 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.

Đố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 đề xuất.

      X-Goog-FieldMask: places.displayName,places.formattedAddress

    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 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 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. Đị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 câu trả lờ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 nhận dạng được đều được chỉ định.

  • includePureServiceAreaBusinesses

    Nếu bạn đặt thành true, thì câu trả lời sẽ bao gồm những doanh nghiệp trực tiếp đến 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 dự đoán về địa điểm và truy vấn. 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 khu vực 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 nội dung dự đoán được trả về. Nếu trống, độ dài mặc định là input.

  • 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ữ BCP-47 theo IETF để 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 đối tượng 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ó), còn nếu không thì 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 khu vực 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 đó.

    • locationBias

      Chỉ định một vùng để 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à một khung nhìn vĩ độ – kinh độ, được biểu thị dưới dạng hai đường chéo đối diện low và điểm cao. Một khung nhìn được coi là một khu vực đóng, có nghĩa là khu vực đó bao gồm cả ranh giới của khung nhìn đó. 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 cắt ngang đường kinh độ 180 độ).
      • Nếu low.longitude = -180 độ và high.longitude = 180 độ, khung nhìn sẽ bao gồm tất cả cá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 tọa độ 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 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

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 vùng đượ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ể dùng locationRestriction để hạn chế nội dung 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ả đượ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 hướng 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ể dùng locationBias để hạn chế nội dung 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 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 xu hướng. Kết quả cũng có 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 thông tin 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 địa điểm và thông tin dự đoán truy vấn như hiển thị ở trên trong phần Giới thiệu về phản hồi. 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ề.

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ạ độ theo 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.

  1. Chọn biểu tượng API, Mở rộng Trình khám phá API., ở bên phải trang.
  2. Bạn có thể mở rộng phần Hiện các tham số chuẩn và đặt tham số fields thành mặt nạ trường.
  3. Chỉnh sửa Phần nội dung yêu cầu (không bắt buộc).
  4. Chọn nút Thực thi. Trong cửa sổ bật lên, hãy chọn tài khoản mà bạn muốn dùng để gửi yêu cầu.

  5. Trong bảng điều khiển API Explorer (Trình khám phá API), hãy chọn biểu tượng mở rộng, Mở rộng Trình khám phá API., để mở rộng cửa sổ API Explorer.