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ự động hoàn thành (Mới) là một dịch vụ web trả về 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 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ể khớp với các 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à Plus Codes. 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ừ Autocomplete (Mới) có thể chứa hai loại cụm từ gợi ý:

  • Dự đoán địa điểm: Các địa điểm, chẳng hạn như doanh nghiệp, địa chỉ và đ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, hệ thống sẽ trả về thông tin dự đoán về địa điểm.
  • Cụm từ gợi ý: Các 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, cụm từ gợi ý tìm kiếm sẽ không được trả về. Sử dụng tham số yêu cầu includeQueryPredictions để thêm cụm từ gợi ý tìm kiếm 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 chuỗi đầu vào chứa một phần thông tin do người dùng nhập, "Sicilian piz", với khu vực tìm kiếm giới hạn ở San Francisco, CA. Sau đó, phản hồi sẽ chứa danh sách địa điểm 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ư nhà hàng có tên "Sicilian Pizza Kitchen", cùng với thông tin chi tiết về địa điểm đó.

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

Phản hồi cũng có thể chứa danh sách cụm từ 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 Sicily". Mỗi cụm từ gợi ý tìm kiếm trong phản hồi đều có 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) để thực hiện 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 tuỳ chọn API:

Yêu cầu về tính năng 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 phần nội dung yêu cầu JSON hoặc trong tiêu đề dưới dạng 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 cần tìm kiếm (từ đầy đủ, chuỗi con, tên địa điểm, địa chỉ, Plus Codes).

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, hãy bao gồm các doanh nghiệp không có địa điểm thực tế (doanh nghiệp phục vụ tận nơi). Giá trị mặc định là false.

includeQueryPredictions

Nếu là true, thì cả cụm từ gợi ý về địa điểm và cụm từ gợi ý về cụm từ tìm kiếm đều sẽ được đưa 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 có hai ký tự để giới hạn kết quả.

inputOffset

Độ lệch ký tự Unicode dựa trên số 0 của vị trí con trỏ trong chuỗi đầu vào, ảnh hưởng đến cụm từ gợi ý. 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) để ưu tiên kết quả tìm kiếm, cho phép kết quả nằm ngoài khu vực. Không thể sử dụng với locationRestriction.

locationRestriction

Chỉ định một khu vực (hình tròn hoặc hình chữ nhật) để giới hạn 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ể sử dụng cù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 điểm đến được dự đoán.

regionCode

Mã khu vực dùng để định dạng câu trả lờ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 vào một phiên cho mục đích thanh toán.
* Biểu thị trường bắt buộc.

Thông tin về câu trả lờ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ả đị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 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 cụm từ gợi ý địa điểm, bao gồm cả mã địa điểm và nội dung mô tả bằng văn bản.
    • Để khớp chính xác hơn với thông tin đầu vào của người dùng được cung cấp trong tham số input, nội dung mô tả bằng văn bản của một cụm từ gợi ý về địa điểm có thể bao gồm tên thay thế cho địa điểm, đường phố và các thành phần khác của địa chỉ. Những tên thay thế này có thể khác với tên được trả về trong các trường displayName và địa chỉ của kết quả Chi tiết địa điểm cho cùng một Mã địa điểm.
    • Trong bối cảnh này, tên thay thế cho một số địa điểm có thể bằng một ngôn ngữ khác với dự kiến dựa trên tham số languageCode, tuỳ thuộc vào tên nào khớp chính xác hơn với thông tin mà người dùng nhập.
  • Trường queryPrediction chứa thông tin chi tiết về một cụm từ gợi ý tìm kiếm.

Đố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
            }]
        },
        ...
    }
  ...]
}

Tham 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à Plus Codes. Dịch vụ Tự động hoàn thành (Mới) trả về các kết quả phù hợ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 mà dịch vụ 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 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

Sử dụng * để truy xuất tất cả các trường.

  X-Goog-FieldMask: *

includeFutureOpeningBusinesses

Nếu là true, thì sẽ trả về những doanh nghiệp dự kiến sẽ mở cửa trong tương lai. Giá trị mặc định là false.

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 này trả về tất cả địa điểm dựa trên tham 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ả ở 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. Đị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.

Tham số này cũng có thể bao gồm một trong hai giá trị (regions) hoặc (cities). Bộ sưu tập loại (regions) lọc theo khu vực hoặc phân khu, chẳng hạn như khu phố và mã bưu chính. Bộ lọc tập hợ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:

  • Bạn đã chỉ định 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 đều được chỉ định.

includePureServiceAreaBusinesses

Nếu bạn đặt thành true, thì phản hồi sẽ bao gồm những 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 có địa điểm thực tế. Nếu bạn đặt thành false, thì API chỉ trả về những doanh nghiệp có địa điểm thực tế.

includeQueryPredictions

Nếu true, thì phản hồi sẽ bao gồm cả cụm từ 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 các cụm từ gợi ý 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ị có hai ký tự ccTLD ("miền cấp cao nhất"). Nếu bạn bỏ qua, thì sẽ không có quy định hạn chế nào được áp dụng cho phản hồi. Ví dụ: Để giới hạn khu vực ở Đức và Pháp, hãy làm như sau:

    "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 này.

inputOffset

Độ lệch ký tự Unicode dựa trên số 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.

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ữ 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, thì 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 nhóm 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.
  • Thông tin dự đoán về địa điểm được định dạng theo nhiều cách, tuỳ thuộc vào thông tin mà người dùng nhập trong mỗi yêu cầu.
    • Các cụm từ phù hợp trong tham số input được chọn trước, sử dụng tên phù hợp với ngôn ngữ ưu tiên được chỉ định bởi tham số languageCode khi có sẵn, còn 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.
    • Tên địa điểm có thể được định dạng bằng tên thay thế để khớp với các cụm từ trong tham số input, bao gồm cả tên bằng các ngôn ngữ khác với ngôn ngữ được chỉ định trong tham số languageCode.
    • Đị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ừ phù hợ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 được trả về bằng ngôn ngữ ưu tiên, 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. Nếu không có tên bằng ngôn ngữ ưu tiên, API sẽ sử dụng tên phù hợp 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à việc chỉ định khu vực mà kết quả phải nằm trong đó, còn locationBias là việc chỉ định khu vực mà kết quả phải ở gần nhưng có thể nằm ngoài khu vực đó.

  • 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í đượ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.

  • 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 khu vực locationBias hoặc locationRestriction dưới dạng Khung nhìn hình chữ nhật hoặc dưới dạng hình tròn.

  • 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, nghĩa là nó bao gồm cả ranh giới của nó. Ranh giới vĩ độ phải nằm trong khoảng từ -90 đến 90 độ và ranh giới kinh độ phải nằm trong khoảng từ -180 đến 180 độ:

    • Nếu low = high, thì khung nhìn sẽ bao gồm một điểm duy nhất đó.
    • Nếu low.longitude > high.longitude, thì phạm vi kinh độ sẽ bị đả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ì dải kinh độ sẽ trống.

    Bạn phải điền cả low và high, đồng thời 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 quanh hoàn toà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 điểm đế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ị gồm hai ký tự ccTLD ("miền cấp cao nhất"). Hầu hết các 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 Liên hiệp Anh và Bắc Ireland").

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

Nếu bạn chỉ định mã vùng không hợp lệ, thì 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.

Khi bạn đặt regionCode, các cụm từ gợi ý trong khu vực đó có thể bỏ qua tên quốc gia trong văn bản gợi ý, tức là structuredFormat.secondaryText có thể không xuất hiện. Do đó, hãy đảm bảo ứng dụng của bạn xử lý các trường hợp không xác định hoặc thiếu secondaryText.

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.

Chọn các tham số để thiên vị kết quả

Các tham số của tính năng Tự động hoàn thành (Mới) có thể ảnh hưởng đến kết quả tìm kiếm theo nhiều cách. 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.
Tham số Đề xuất về mức 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 nhậ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 nhìn của bản đồ mà người dùng đang xem.
locationRestriction Chỉ sử dụng 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 có khoảng cách theo đường thẳng đến từng cụm từ gợi ý.

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

Giới hạn kết quả tìm kiếm trong một khu vực bằng cách sử dụng locationRestriction

locationRestriction chỉ định khu vực cần tìm kiếm. Kết quả nằm 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, lấy San Francisco làm tâm:

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 kết quả 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 đối với khu vực trung tâm thành phố 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"
          ]
        }
      }
    ]
  }

Thiên vị kết quả tìm kiếm cho một khu vực bằng cách sử dụng locationBias

Với locationBias, vị trí đóng vai trò là một độ lệch, 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 thiên vị yêu cầu cho 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 để thiên về kết quả 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 đối với khu vực trung tâm thành phố 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 thiên vị. 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 includePrimaryTypes

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). Đị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ả cho 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 cụm từ gợi ý tìm kiếm

Theo mặc định, cụm từ gợi ý tìm kiếm sẽ không được trả về. Sử dụng tham số yêu cầu includeQueryPredictions để thêm cụm từ gợi ý tìm kiếm 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ả cụm từ gợi ý về địa điểm và cụm từ gợi ý về cụm từ tìm kiếm như trình bày ở trên trong phần Giới thiệu về phản hồi. Mỗi cụm từ gợi ý tìm kiếm đề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ể 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ừ gợi ý 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ạ độ vĩ độ và kinh độ. Khi bạn thêm origin, tính năng Tự động hoàn thành (Mới) sẽ bao gồm trường distanceMeters trong phản hồi, chứa khoảng cách đường thẳng từ origin đến điểm đến. Ví dụ này đặt điểm xuất phát là 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

Câu trả lờ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
      }
    }
  ]
}

Tìm doanh nghiệp sẽ mở cửa trong tương lai

Ví dụ sau đây cho thấy một yêu cầu Tự động hoàn thành (Mới) cho các doanh nghiệp sắp khai trương ở New Meadows, Idaho:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "input": "Roberts Greenhouse and Tree Farm",
  "includeFutureOpeningBusinesses": true,
  "locationBias": {
    "circle": {
      "center": {"latitude": 44.9755100, "longitude": -116.2842180},
      "radius": 20
    }
  }
}' \
"https://places.googleapis.com/v1/places:autocomplete"

Phản hồi bao gồm thông tin chi tiết về địa điểm, nhưng không bao gồm ngày khai trương.

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "placeId": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "text": {
          "text": "Roberts Greenhouse and Tree Farm, McLain Street, New Meadows, ID, USA",
          "matches": [
            {
              "endOffset": 32
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Roberts Greenhouse and Tree Farm",
            "matches": [
              {
                "endOffset": 32
              }
            ]
          },
          "secondaryText": {
            "text": "McLain Street, New Meadows, ID, USA"
          }
        },
        "types": [
          "garden_center",
          "establishment",
          "service",
          "store",
          "point_of_interest"
        ]
      }
    }
  ]
}

Thiếu khoảng cách trong phản hồi

Trong một số trường hợp, distanceMeters bị thiếu trong nội dung phản hồi, ngay cả khi origin có trong 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 cho route dự đoán.
  • distanceMeters không được đưa vào khi giá trị của nó là 0, đây là trường hợp cho các dự đoán cách vị trí origin được cung cấp chưa đến 1 mét.

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

Tối ưu hoá tính năng Tự động hoàn thành (Mới)

Phần này mô tả các phương pháp hay nhất để giúp bạn khai thác tối đa dịch vụ Tự động hoàn thành (Mới).

Sau đây là một số nguyên tắc chung:

Các phương pháp hay nhất để tối ưu hoá chi phí

Tối ưu hoá chi phí cơ bản

Để tối ưu hoá chi phí sử dụng dịch vụ Tự động hoàn thành (Mới), hãy sử dụng mặt nạ trường trong các tiện ích Place Details (Mới) và Tự động hoàn thành (Mới) để chỉ trả về trường dữ liệu Tự động hoàn thành (Mới) mà bạn cần.

Tối ưu hoá chi phí nâng cao

Hãy cân nhắc việc triển khai tính năng Tự động hoàn thành (Mới) theo phương thức lập trình để sử dụng SKU: Giá của yêu cầu Tự động hoàn thành và yêu cầu kết quả của Geocoding API về địa điểm đã chọn thay vì Place Details (Mới). Mô hình định giá theo yêu cầu kết hợp với Geocoding API sẽ tiết kiệm chi phí hơn so với mô hình định giá theo phiên (dựa trên phiên) nếu đáp ứng cả hai điều kiện sau:

  • Nếu bạn chỉ cần vĩ độ và kinh độ hoặc địa chỉ của địa điểm mà người dùng đã chọn, thì Geocoding API sẽ cung cấp thông tin này với chi phí thấp hơn so với lệnh gọi Place Details (Mới).
  • Nếu người dùng chọn một cụm từ gợi ý của tính năng tự động hoàn thành trong trung bình 4 yêu cầu cụm từ gợi ý của tính năng Tự động hoàn thành (Mới) trở xuống, thì mức giá theo yêu cầu có thể tiết kiệm chi phí hơn so với mức giá theo phiên.
Để chọn cách triển khai tính năng Tự động hoàn thành (Mới) có chi phí thấp nhất cho ứng dụng của bạn, hãy tìm hàng trong bảng sau đây phù hợp với nhu cầu của ứng dụng.
Những thông tin cần có trong đơn đăng ký Số yêu cầu trung bình về tính năng Tự động hoàn thành (Mới) trước khi người dùng chọn một cụm từ gợi ý Cách triển khai được đề xuất
Thông tin chi tiết về địa điểm ngoài địa chỉ và vị trí, chẳng hạn như tên địa điểm, trạng thái doanh nghiệp hoặc giờ mở cửa Số lượng bất kỳ Tính năng Tự động hoàn thành dựa trên phiên (Mới) có Thông tin chi tiết về địa điểm (Mới)
Chỉ địa chỉ và vĩ độ/kinh độ của cụm từ gợi ý đã chọn 4 trở xuống Tính năng Tự động hoàn thành theo yêu cầu (Mới) với Geocoding API
Chỉ địa chỉ và vĩ độ/kinh độ của cụm từ gợi ý đã chọn Hơn 4 Tính năng Tự động hoàn thành (Mới) dựa trên phiên cho các ứng dụng chỉ có địa chỉ

Geocoding API có thể là một lựa chọn tiết kiệm chi phí hơn so với Place Details (Mới) cho ứng dụng của bạn, tuỳ thuộc vào hiệu suất sử dụng Autocomplete (Mới). Hiệu suất của tính năng Tự động hoàn thành (Mới) trong mỗi ứng dụng sẽ khác nhau tuỳ thuộc vào nội dung người dùng nhập, nơi ứng dụng được sử dụng và liệu các phương pháp hay nhất để tối ưu hoá hiệu suất đã được triển khai hay chưa.

Để tìm số yêu cầu trung bình cho bảng, hãy phân tích xem trung bình người dùng nhập bao nhiêu ký tự trước khi chọn một cụm từ gợi ý của tính năng Tự động hoàn thành (Mới) trong ứng dụng của bạn.

Tính năng Tự động hoàn thành (Mới) dựa trên phiên có Place Details (Mới)

Sử dụng tính năng Tự động hoàn thành (Mới) dựa trên phiên với Place Details (Mới).
Vì ứng dụng của bạn yêu cầu Chi tiết địa điểm (Mới), chẳng hạn như tên địa điểm, trạng thái doanh nghiệp hoặc giờ mở cửa, nên việc triển khai tính năng Tự động hoàn thành (Mới) phải sử dụng mã thông báo phiên (theo phương thức lập trình hoặc được tích hợp vào các tiện ích JavaScript, Android hoặc iOS) cho mỗi phiên cộng với các SKU Địa điểm hiện hành, tuỳ thuộc vào trường dữ liệu địa điểm mà bạn yêu cầu.1

Triển khai tiện ích
Tính năng quản lý phiên được tích hợp tự động vào các tiện ích JavaScript, Android hoặc iOS. Trong đó bao gồm cả yêu cầu Tự động hoàn thành (Mới) và yêu cầu Place Details (Mới) về cụm từ gợi ý đã chọn. Hãy nhớ chỉ định tham số fields để đảm bảo bạn chỉ yêu cầu trường dữ liệu Tự động hoàn thành (Mới) mà bạn cần.

Triển khai có lập trình
Sử dụng mã thông báo phiên với các yêu cầu Tự động hoàn thành (Mới). Khi yêu cầu Place Details (Mới) về cụm từ gợi ý đã chọn, hãy thêm các tham số sau:

  1. Mã địa điểm từ phản hồi của tính năng Tự động hoàn thành (Mới)
  2. Mã thông báo phiên được dùng trong yêu cầu Tự động hoàn thành (Mới)
  3. Tham số fields chỉ định trường dữ liệu của tính năng Tự động hoàn thành (Mới) mà bạn cần

Tính năng Tự động hoàn thành (Mới) theo yêu cầu bằng Geocoding API

Triển khai tính năng Tự động hoàn thành (Mới) theo phương thức lập trình mà không cần mã thông báo phiên và gọi Geocoding API trên cụm từ gợi ý địa điểm đã chọn.
Geocoding API cung cấp địa chỉ và toạ độ vĩ độ/kinh độ. Việc thực hiện 4 yêu cầu Autocomplete Requests cộng với một lệnh gọi Geocoding API về cụm từ gợi ý địa điểm đã chọn sẽ có chi phí thấp hơn chi phí cho mỗi phiên của Autocomplete (Mới).1

Hãy cân nhắc áp dụng các phương pháp hay nhất về hiệu suất để giúp người dùng nhận được cụm từ gợi ý mà họ đang tìm kiếm chỉ với ít ký tự hơn.

Tính năng Tự động hoàn thành dựa trên phiên (Mới) cho các ứng dụng chỉ có địa chỉ

Sử dụng tính năng Tự động hoàn thành (Mới) dựa trên phiên với Place Details (Mới).
Vì số lượng yêu cầu trung bình mà bạn dự kiến thực hiện trước khi người dùng chọn một cụm từ gợi ý của tính năng Tự động hoàn thành (Mới) vượt quá chi phí của mức giá theo phiên, nên việc triển khai tính năng Tự động hoàn thành (Mới) phải sử dụng mã thông báo phiên cho cả yêu cầu Tự động hoàn thành (Mới) và yêu cầu Chi tiết địa điểm (Mới) liên quan theo phiên. 1

Triển khai tiện ích
Tính năng quản lý phiên được tích hợp tự động vào các tiện ích JavaScript, Android hoặc iOS. Trong đó bao gồm cả yêu cầu Tự động hoàn thành (Mới) và yêu cầu Place Details (Mới) đối với cụm từ gợi ý đã chọn. Hãy nhớ chỉ định tham số fields để đảm bảo bạn chỉ yêu cầu các trường cần thiết.

Triển khai có lập trình
Sử dụng mã thông báo phiên với các yêu cầu Tự động hoàn thành (Mới). Khi yêu cầu Place Details (Mới) về cụm từ gợi ý đã chọn, hãy thêm các tham số sau:

  1. Mã địa điểm từ phản hồi của tính năng Tự động hoàn thành (Mới)
  2. Mã thông báo phiên được dùng trong yêu cầu Tự động hoàn thành (Mới)
  3. Tham số fields chỉ định các trường chẳng hạn như địa chỉ và hình học

Cân nhắc việc trì hoãn yêu cầu Tự động hoàn thành (Mới)
Bạn có thể áp dụng các chiến lược như trì hoãn yêu cầu Tự động hoàn thành (Mới) cho đến khi người dùng nhập 3 hoặc 4 ký tự đầu tiên để ứng dụng của bạn đưa ra ít yêu cầu hơn. Ví dụ: việc đưa ra yêu cầu về tính năng Tự động hoàn thành (Mới) cho mỗi ký tự sau khi người dùng nhập ký tự thứ ba có nghĩa là nếu người dùng nhập 7 ký tự rồi chọn một cụm từ gợi ý mà bạn đưa ra một yêu cầu về Geocoding API, thì tổng chi phí sẽ là 4 yêu cầu về tính năng Tự động hoàn thành (Mới) + Mã hoá địa lý.1

Nếu việc trì hoãn yêu cầu có thể giúp số yêu cầu có lập trình trung bình của bạn giảm xuống dưới 4, thì bạn có thể làm theo hướng dẫn triển khai Autocomplete (Mới) hiệu suất cao bằng Geocoding API. Xin lưu ý rằng việc trì hoãn yêu cầu có thể khiến người dùng cảm thấy có độ trễ khi họ mong đợi thấy thông tin dự đoán sau mỗi lần nhấn phím mới.

Hãy cân nhắc việc áp dụng các phương pháp hay nhất về hiệu suất để giúp người dùng nhận được cụm từ gợi ý mà họ đang tìm kiếm với ít ký tự hơn.

  1. Để biết chi phí, hãy xem bảng giá của Google Maps Platform.

Các phương pháp hay nhất về hiệu suất

Các nguyên tắc sau đây mô tả cách tối ưu hoá hiệu suất của tính năng Tự động hoàn thành (Mới):

  • Thêm các quy định hạn chế theo quốc gia, thiên vị vị trí và (đối với việc triển khai có lập trình) ngôn ngữ ưu tiên cho việc triển khai Tính năng tự động hoàn thành (Mới). Bạn không cần đặt ngôn ngữ ưu tiên cho các tiện ích vì các tiện ích này sẽ chọn ngôn ngữ ưu tiên từ trình duyệt hoặc thiết bị di động của người dùng.
  • Nếu tính năng Tự động hoàn thành (Mới) đi kèm với bản đồ, bạn có thể thiên vị vị trí theo khung nhìn bản đồ.
  • Trong trường hợp người dùng không chọn một trong các cụm từ gợi ý của tính năng Tự động hoàn thành (Mới), thường là do không có cụm từ gợi ý nào là địa chỉ kết quả mong muốn, bạn có thể sử dụng lại thông tin đầu vào ban đầu của người dùng để cố gắng nhận được kết quả phù hợp hơn:
    • Nếu bạn muốn người dùng chỉ nhập thông tin địa chỉ, hãy sử dụng lại thông tin đầu vào ban đầu của người dùng trong lệnh gọi đến Geocoding API.
    • Nếu bạn muốn người dùng nhập cụm từ tìm kiếm cho một địa điểm cụ thể theo tên hoặc địa chỉ, hãy sử dụng yêu cầu Chi tiết địa điểm (Mới). Nếu bạn chỉ muốn nhận kết quả ở một khu vực cụ thể, hãy sử dụng tính năng thiên vị vị trí.
    Các trường hợp khác mà bạn nên quay lại sử dụng Geocoding API bao gồm:
    • Người dùng nhập địa chỉ của cơ sở phụ, chẳng hạn như địa chỉ của các căn hộ hoặc căn hộ cụ thể trong một toà nhà. Ví dụ: địa chỉ "Stroupežnického 3191/17, Praha" ở Séc sẽ trả về một cụm từ gợi ý một phần trong tính năng Tự động hoàn thành (Mới).
    • Người dùng nhập địa chỉ có tiền tố đoạn đường như "23-30 29th St, Queens" ở Thành phố New York hoặc "47-380 Kamehameha Hwy, Kaneohe" trên đảo Kauai ở Hawaii.

Thiên vị vị trí

Ưu tiên kết quả cho một khu vực cụ thể bằng cách truyền tham số location và tham số radius. Thao tác này hướng dẫn tính năng Tự động hoàn thành (Mới) ưu tiên hiển thị kết quả trong khu vực đã xác định. Kết quả bên ngoài khu vực đã xác định vẫn có thể xuất hiện. Bạn có thể sử dụng tham số includedRegionCodes để lọc kết quả nhằm chỉ hiển thị những địa điểm trong một quốc gia cụ thể.

Hạn chế về vị trí

Giới hạn kết quả trong một khu vực cụ thể bằng cách truyền tham số locationRestriction.

Bạn cũng có thể giới hạn kết quả ở khu vực được xác định bằng location và tham số radius bằng cách thêm tham số locationRestriction. Thao tác này hướng dẫn tính năng Tự động hoàn thành (Mới) chỉ trả về kết quả trong khu vực đó.

Hãy dùng thử!

APIs Explorer 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 api ở bên phải trang.

  2. Chỉnh sửa các tham số yêu cầu (không bắt buộc).

  3. Chọn nút Execute (Thực thi). Trong hộp thoại, hãy chọn tài khoản mà bạn muốn dùng để gửi yêu cầu.

  4. 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.