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

Giới thiệu

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

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

Phản hồi từ tính năng Tự động hoàn thành (Mới) có thể chứa 2 loại cụm từ gợi ý:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Thông số bắt buộc

• input

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

Thông số tùy chọn

• FieldMask

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

  Chỉ định một 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: *

• includedPrimaryTypes

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

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

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

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

  Yêu cầu bị từ chối kèm theo lỗi INVALID_REQUEST nếu:

  • Bạn chỉ định nhiều hơn 5 loại.
  • Bạn có thể chỉ định bất kỳ loại nào ngoài (cities) hoặc (regions).
  • Mọi loại không nhận dạng được đều được chỉ định.

• includePureServiceAreaBusinesses

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

• includeQueryPredictions

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

• includedRegionCodes

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

      "includedRegionCodes": ["de", "fr"]

  Nếu bạn chỉ định cả locationRestriction và includedRegionCodes, thì kết quả sẽ nằm trong khu vực giao nhau của hai chế độ cài đặt.

• inputOffset

  Độ lệch ký tự Unicode dựa trên mốc 0 cho biết vị trí con trỏ trong input. Vị trí con trỏ có thể ảnh hưởng đến những nội dung dự đoán được trả về. Nếu trống, giá trị này sẽ mặc định là độ dài của input.

• languageCode

  Ngôn ngữ ưu tiên để trả về kết quả. Kết quả có thể bằng nhiều ngôn ngữ nếu ngôn ngữ được dùng trong input khác với giá trị do languageCode chỉ định, hoặc nếu địa điểm được trả về không có bản dịch từ ngôn ngữ địa phương sang languageCode.

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

• locationBias hoặc locationRestriction

  Bạn có thể chỉ định locationBias hoặc locationRestriction (chỉ 1 trong 2) để xác định khu vực tìm kiếm. Hãy coi locationRestriction là 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 vùng locationBias hoặc locationRestriction dưới dạng khung hiển thị hình chữ nhật hoặc dưới dạng hình tròn.

  • Một hình tròn được xác định bằng tâm điểm và bán kính tính bằng mét. Bán kính phải nằm trong khoảng từ 0 đến 50.000. Giá trị mặc định là 0.0. Đối với locationRestriction, bạn phải đặt bán kính thành một giá trị lớn hơn 0.0. Nếu không, yêu cầu sẽ không trả về kết quả nào.

    Ví dụ:

    "locationBias": {
      "circle": {
        "center": {
          "latitude": 37.7937,
          "longitude": -122.3965
        },
        "radius": 500.0
      }
    }

  • Hình chữ nhật là một khung nhìn theo vĩ độ và kinh độ, được biểu thị dưới dạng hai điểm low và điểm cao đối diện theo đường chéo. Khung nhìn được coi là một vùng khép kín, tức là bao gồm cả ranh giới của vùng đó. Phạm vi vĩ độ phải nằm trong khoảng từ -90 đến 90 độ (bao gồm cả hai giá trị này), còn phạm vi kinh độ phải nằm trong khoảng từ -180 đến 180 độ (bao gồm cả hai giá trị này):

    • Nếu low = high, khung nhìn sẽ bao gồm điểm duy nhất đó.
    • Nếu low.longitude > high.longitude, thì dải kinh độ sẽ đảo ngược (khung nhìn vượt qua đường kinh độ 180 độ).
    • Nếu low.longitude = -180 độ và high.longitude = 180 độ, thì khung nhìn sẽ bao gồm tất cả 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, đồng thời không được để trống hộp được biểu thị. Khung hiển thị trống sẽ dẫn đến lỗi.

    Ví dụ: khung hiển thị này bao trọn Thành phố New York:

    "locationBias": {
      "rectangle": {
        "low": {
          "latitude": 40.477398,
          "longitude": -74.259087
        },
        "high": {
          "latitude": 40.91618,
          "longitude": -73.70018
        }
      }
    }

• nguồn gốc

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

  "origin": {
      "latitude": 40.477398,
      "longitude": -74.259087
  }

• regionCode

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

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

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

• sessionToken

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

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

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

Hạn chế tìm kiếm trong một khu vực bằng locationRestriction

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

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

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

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

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

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

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

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

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

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

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

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

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

Bạn cũng có thể dùng locationBias để điều chỉnh kết quả tìm kiếm cho phù hợp với 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 hiển thị hình chữ nhật xuất hiện trong phản hồi, nhưng một số kết quả nằm ngoài ranh giới đã xác định do thiên vị. Kết quả cũng nằm trong mảng suggestions:

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

Sử dụng includedPrimaryTypes

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

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

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

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

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

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

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

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

Sử dụng nguồn

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

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

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

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

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

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

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

Các thư viện ứng dụng cố gắng đọc trường distanceMeters ra khỏi một đối tượng đã phân tích cú pháp sẽ trả về một trường có giá trị 0. Để tránh 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).

Dưới đây là một số nguyên tắc chung:

• Cách nhanh nhất để phát triển giao diện người dùng hoạt động là sử dụng tiện ích Tự động hoàn thành (Mới) của Maps JavaScript API, tiện ích Tự động hoàn thành (Mới) của Places SDK cho Android hoặc tiện ích Tự động hoàn thành (Mới) của Places SDK cho iOS.
• Ngay từ đầu, hãy hiểu rõ các trường dữ liệu quan trọng của tính năng Tự động hoàn thành (Mới).
• Các trường thiên vị vị trí và hạn chế vị trí là không bắt buộc nhưng có thể ảnh hưởng đáng kể đến hiệu suất của tính năng tự động hoàn thành.
• Sử dụng tính năng xử lý lỗi để đảm bảo ứng dụng của bạn giảm hiệu suất một cách thích hợp nếu API trả về lỗi.
• Đảm bảo ứng dụng của bạn xử lý khi không có lựa chọn nào và cung cấp cho người dùng cách để tiếp tục.

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ụ Autocomplete (New), hãy sử dụng mặt nạ trường trong các tiện ích Place Details (New) và Autocomplete (New) để chỉ trả về các trường dữ liệu Autocomplete (New) 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 theo chương trình tính năng Tự động hoàn thành (Mới) để truy cập vào SKU: Giá yêu cầu Tự động hoàn thành và yêu cầu kết quả Geocoding API về địa điểm đã chọn thay vì Chi tiết về địa điểm (Mới). Mức 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ức giá theo phiên (dựa trên phiên) nếu cả hai điều kiện sau đây đều được đáp ứng:

• Nếu bạn chỉ cần 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 ít hơn một lệnh gọi Place Details (New).
• Nếu người dùng chọn một cụm từ dự đoán tự động hoàn thành trong trung bình 4 yêu cầu dự đoán Tự động hoàn thành (Mới) hoặc ít hơn, 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.

Ứng dụng của bạn có yêu cầu thông tin nào khác ngoài địa chỉ và vĩ độ/kinh độ của kết quả dự đoán đã chọn không?

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

Các nguyên tắc sau đây mô tả những 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ế về quốc gia, ưu tiên vị trí và (đối với các cách triển khai có lập trình) lựa chọn ưu tiên ngôn ngữ vào chế độ triển khai Autocomplete (New) (Tự động hoàn thành (Mới)). Không cần lựa chọn ưu tiên về ngôn ngữ đối với các tiện ích vì chúng chọn lựa chọn ưu tiên về ngôn ngữ 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ể điều chỉnh vị trí theo khung hiển thị 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ả mà họ muốn, bạn có thể sử dụng lại nội dung đầ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 chỉ muốn người dùng 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 một 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 về địa điểm (Mới). Nếu 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 dùng Geocoding API bao gồm:
  • Người dùng nhập địa chỉ của một phần trong cơ sở, chẳng hạn như địa chỉ của các căn hộ hoặc đơn vị cụ thể trong một toà nhà. Ví dụ: địa chỉ "Stroupežnického 3191/17, Praha" của Cộng hoà 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ề vị trí

Điều chỉnh 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ố components để lọc kết quả và chỉ cho thấy những địa điểm trong một quốc gia cụ thể.

Hạn chế về vị trí

Hạn chế kết quả ở 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 do location và tham số radius xác định bằng cách thêm tham số locationRestriction. Thao tác này hướng dẫn tính năng Autocomplete (Mới) chỉ trả về kết quả trong khu vực đó.

Hãy dùng thử!

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

1. Chọn biểu tượng API api ở bên phải trang.

2. Bạn có thể chỉnh sửa các tham số yêu cầu (không bắt buộc).

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

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 (toàn màn hình) để mở rộng cửa sổ APIs Explorer.