Place Autocomplete (Cũ)

Place Autocomplete (Phiên bản cũ) là một dịch vụ web trả về các cụm từ gợi ý về địa điểm để phản hồi một yêu cầu HTTP. Yêu cầu chỉ định một chuỗi tìm kiếm dạng văn bản và ranh giới địa lý không bắt buộc. Bạn có thể sử dụng dịch vụ này để cung cấp chức năng tự động hoàn thành cho các cụm từ tìm kiếm địa lý dựa trên văn bản, bằng cách trả về các địa điểm như doanh nghiệp, địa chỉ và địa điểm yêu thích khi người dùng nhập.

Yêu cầu Place Autocomplete (Phiên bản cũ)

Place Autocomplete (cũ) là một phần của Places API và dùng chung một khoá API và hạn mức với Places API.

Place Autocomplete (Phiên bản cũ) có thể so khớp với các từ và chuỗi con đầy đủ, giải quyết 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 ngay lập tức.

Bạn phải định dạng mã địa chỉ đúng cách. Điều này có nghĩa là bạn phải thoát dấu cộng thành %2B và thoát dấu cách thành %20.

• mã toàn cầu là mã vùng gồm 4 ký tự và mã cục bộ gồm 6 ký tự trở lên. Ví dụ: mã chung thoát URL 849VCWC8+R9 là 849VCWC8%2BR9.
• mã kết hợp là mã địa phương gồm 6 ký tự (hoặc dài hơn) có vị trí cụ thể. Ví dụ: mã kết hợp có ký tự thoát URL CWC8+R9 Mountain View, CA, USA là CWC8%2BR9%20Mountain%20View%20CA%20USA.

Các kết quả dự đoán đượ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 mà họ muốn. Bạn có thể gửi một yêu cầu Chi tiết về địa điểm (Phiên bản cũ) để biết thêm thông tin về bất kỳ địa điểm nào được trả về.

Yêu cầu Place Autocomplete (cũ) là một URL loại HTTP có dạng sau:

https://maps.googleapis.com/maps/api/place/autocomplete/output?parameters

trong đó output có thể là một trong hai giá trị sau:

• json (nên dùng) cho biết đầu ra ở dạng Ký hiệu đối tượng JavaScript (JSON)
• xml cho biết đầu ra dưới dạng XML

Bạn phải có một số tham số nhất định để bắt đầu yêu cầu Place Autocomplete (Cũ). Theo tiêu chuẩn trong URL, tất cả các tham số đều được phân tách bằng ký tự dấu và (&). Danh sách các thông số và giá trị có thể của các thông số đó được liệt kê dưới đây.

Thông số bắt buộc

• input

  Chuỗi văn bản mà bạn muốn tìm kiếm. Dịch vụ Place Autocomplete sẽ 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

• thành phần

  Một nhóm những địa điểm mà bạn muốn giới hạn kết quả. Bạn có thể sử dụng các thành phần để lọc theo tối đa 5 quốc gia. Bạn phải truyền quốc gia dưới dạng mã quốc gia gồm 2 ký tự, tương thích với ISO 3166-1 Alpha-2. Ví dụ: components=country:fr sẽ giới hạn kết quả ở những địa điểm tại Pháp. Bạn phải truyền nhiều quốc gia dưới dạng nhiều bộ lọc country:XX, với dấu gạch đứng | làm dấu phân cách. Ví dụ: components=country:us|country:pr|country:vi|country:gu|country:mp sẽ giới hạn kết quả ở những địa điểm thuộc Hoa Kỳ và các lãnh thổ có tổ chức chưa hợp nhất của quốc gia này.

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

• language

  Ngôn ngữ mà bạn muốn nhận kết quả.

  • Xem danh sách các ngôn ngữ được hỗ trợ. Google thường xuyên cập nhật các ngôn ngữ được hỗ trợ, vì vậy, danh sách này có thể chưa đầy đủ.
  • Nếu bạn không cung cấp language, API sẽ cố gắng sử dụng ngôn ngữ ưu tiên như được chỉ định trong tiêu đề Accept-Language.
  • 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. Để đạt được mục tiêu đó, phương thức này sẽ trả về địa chỉ đường phố bằng ngôn ngữ địa phương, được chuyển tự sang một kịch bản mà người dùng có thể đọc được (nếu cần), tuân theo ngôn ngữ ưu tiên. Tất cả các địa chỉ khác đều được trả về bằng ngôn ngữ ưu tiên. Tất cả các thành phần địa chỉ đều được trả về bằng cùng một ngôn ngữ, được chọn từ thành phần đầu tiên.
  • Nếu không có tên bằng ngôn ngữ ưu tiên, API sẽ sử dụng kết quả trùng khớp gần nhất.
  • 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ề. Trình mã hoá địa lý diễn giải các từ viết tắt theo nhiều cách tuỳ thuộc vào ngôn ngữ, chẳng hạn như từ viết tắt cho các loại đường phố hoặc từ đồng nghĩa có thể hợp lệ trong một ngôn ngữ nhưng không hợp lệ trong ngôn ngữ khác. Ví dụ: utca và tér là từ đồng nghĩa với đường phố trong tiếng Hungary.

• vị trí

  Điểm xung quanh để truy xuất thông tin về địa điểm. Bạn phải chỉ định giá trị này là latitude,longitude. Bạn cũng phải cung cấp tham số radius khi chỉ định một vị trí. Nếu bạn không cung cấp radius, thì tham số location sẽ bị bỏ qua.

  Khi sử dụng API Tìm kiếm văn bản, tham số `location` có thể bị ghi đè nếu `query` chứa một vị trí rõ ràng, chẳng hạn như `Chợ ở Barcelona`.

• locationbias

  Ưu tiên kết quả ở một khu vực cụ thể bằng cách chỉ định bán kính cộng với vĩ độ/kinh độ hoặc hai cặp vĩ độ/kinh độ đại diện cho các điểm của một hình chữ nhật. Nếu bạn không chỉ định tham số này, API sẽ sử dụng tính năng thiên vị địa chỉ IP theo mặc định.

  • Thiên vị theo IP: Hướng dẫn API sử dụng tính năng thiên vị theo địa chỉ IP. Truyền chuỗi ipbias (lựa chọn này không có tham số bổ sung).
  • Hình tròn: Một chuỗi chỉ định bán kính theo mét, cộng với vĩ độ/kinh độ theo độ thập phân. Hãy dùng định dạng sau: circle:radius@lat,lng.
  • Hình chữ nhật: Một chuỗi chỉ định 2 cặp vĩ độ/kinh độ theo độ thập phân, biểu thị các điểm phía nam/tây và phía bắc/đông của một hình chữ nhật. Sử dụng định dạng sau:rectangle:south,west|north,east. Lưu ý rằng các giá trị đông/tây được gói trong phạm vi -180, 180 và các giá trị bắc/nam được giới hạn trong phạm vi -90, 90.

• locationrestriction

  Giới hạn kết quả trong một khu vực cụ thể bằng cách chỉ định bán kính cộng với vĩ độ/kinh độ hoặc hai cặp vĩ độ/kinh độ đại diện cho các điểm của một hình chữ nhật.

  • Hình tròn: Một chuỗi chỉ định bán kính theo mét, cộng với vĩ độ/kinh độ theo độ thập phân. Hãy dùng định dạng sau: circle:radius@lat,lng.
  • Hình chữ nhật: Một chuỗi chỉ định 2 cặp vĩ độ/kinh độ theo độ thập phân, biểu thị các điểm phía nam/tây và phía bắc/đông của một hình chữ nhật. Sử dụng định dạng sau:rectangle:south,west|north,east. Lưu ý rằng các giá trị đông/tây được gói trong phạm vi -180, 180 và các giá trị bắc/nam được giới hạn trong phạm vi -90, 90.

• độ lệch

  Vị trí của ký tự cuối cùng mà dịch vụ dùng để so khớp các cụm từ gợi ý trong cụm từ tìm kiếm. Ví dụ: nếu đầu vào là Google và độ lệch là 3, thì dịch vụ sẽ khớp với Goo. Chuỗi do độ lệch xác định chỉ được so khớp với từ đầu tiên trong cụm từ đầu vào. Ví dụ: nếu từ khoá đầu vào là Google abc và độ lệch là 3, thì dịch vụ sẽ cố gắng so khớp với Goo abc. Nếu không có độ lệch nào được cung cấp, dịch vụ sẽ sử dụng toàn bộ cụm từ. Khoảng bù thường được đặt ở vị trí của dấu nháy văn bản.

• 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 distance_meters). 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ề. Bạn phải chỉ định là latitude,longitude.

• bán kính

  Xác định khoảng cách (tính bằng mét) để trả về kết quả về địa điểm. Bạn có thể điều chỉnh kết quả theo một vòng tròn cụ thể bằng cách truyền tham số location và radius. Khi đó, dịch vụ Places sẽ được hướng dẫn ưu tiên hiển thị kết quả trong vòng tròn đó; kết quả bên ngoài khu vực đã xác định vẫn có thể xuất hiện.

  Bán kính sẽ tự động được giới hạn ở giá trị tối đa tuỳ thuộc vào loại tìm kiếm và các thông số khác.

  • Tự động hoàn thành: 50.000 mét
  • Tìm kiếm lân cận:
    • có keyword hoặc name: 50.000 mét
    • không có keyword hoặc name
      • Tối đa 50.000 mét, được điều chỉnh linh hoạt dựa trên mật độ khu vực, không phụ thuộc vào tham số rankby.
      • Khi sử dụng rankby=distance, tham số bán kính sẽ không được chấp nhận và sẽ dẫn đến INVALID_REQUEST.
  • Tự động hoàn thành cụm từ tìm kiếm: 50.000 mét
  • Tìm kiếm văn bản: 50.000 mét

• khu vực

  Mã vùng, đượ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").

• sessiontoken

  Một chuỗi ngẫu nhiên xác định một phiên tự động hoàn thành cho mục đích thanh toán.

  Phiên bắt đầu khi người dùng bắt đầu nhập một cụm từ tìm kiếm và kết thúc khi họ chọn một địa điểm và thực hiện lệnh gọi đến Place Details. Mỗi phiên có thể có nhiều cụm từ tìm kiếm, sau đó là một lựa chọn về địa điểm. (Các) khoá API được dùng cho mỗi yêu cầu trong một phiên phải thuộc cùng một dự án trên Google Cloud Console. Sau khi một phiên kết thúc, mã thông báo sẽ không còn hợp lệ nữa; ứng dụng của bạn phải tạo một mã thông báo mới cho mỗi phiên. Nếu bạn bỏ qua tham số sessiontoken hoặc nếu bạn sử dụng lại mã thông báo phiên, thì phiên sẽ bị tính phí như thể bạn không cung cấp mã thông báo phiên (mỗi yêu cầu sẽ được tính phí riêng).

  Bạn nên tuân thủ các nguyên tắc sau:

  • Sử dụng mã thông báo phiên cho tất cả các phiên tự động hoàn thành.
  • Tạo một mã thông báo mới cho mỗi phiên. Bạn nên sử dụng UUID phiên bản 4.
  • Đảm bảo rằng(các) khoá API được dùng cho tất cả các yêu cầu về Place Autocomplete và Place Details trong một phiên thuộc cùng một dự án trên Cloud Console.
  • Hãy nhớ truyền một mã thông báo phiên duy nhất cho mỗi phiên mới. Việc sử dụng cùng một mã thông báo cho nhiều phiên sẽ dẫn đến việc mỗi yêu cầu được tính phí riêng lẻ.

• strictbounds

  Chỉ trả về những địa điểm nằm hoàn toàn trong khu vực do location và radius xác định. Đây là một quy định hạn chế chứ không phải thiên kiến, nghĩa là kết quả bên ngoài khu vực này sẽ không được trả về ngay cả khi kết quả đó khớp với hoạt động đầu vào của người dùng.

• loại

  Bạn có thể hạn chế kết quả của một yêu cầu Place Autocomplete ở một loại nhất định bằng cách truyền tham số types. Tham số này chỉ định một loại hoặc một tập hợp loại, như được liệt kê trong Các loại địa điểm. Nếu bạn không chỉ định gì, thì tất cả các loại sẽ được trả về.

  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 1 hoặc Bảng 2. Ví dụ: một khách sạn có phục vụ đồ ăn chỉ có thể trả về bằng types=lodging chứ không được trả về bằng types=restaurant.

  Đối với giá trị của tham số types, bạn có thể chỉ định một trong hai giá trị sau:

  • Tối đa 5 giá trị từ Bảng 1 hoặc Bảng 2. Đối với nhiều giá trị, hãy phân tách từng giá trị bằng dấu | (thanh dọc). Ví dụ:

    types=book_store|cafe

  • Mọi bộ lọc đơn lẻ được hỗ trợ trong Bảng 3. Bạn không thể kết hợp các bộ sưu tập loại.

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

  • Bạn chỉ định nhiều hơn 5 loại.
  • Có mọi loại không nhận dạng được.
  • Mọi loại trong Bảng 1 hoặc Bảng 2 đều được kết hợp với bất kỳ bộ lọc nào trong Bảng 3.

Ví dụ về tính năng Place Autocomplete (Phiên bản cũ)

Yêu cầu về các cơ sở có chứa chuỗi "Amoeba" trong một khu vực ở trung tâm San Francisco, California:

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=amoeba
      &types=establishment
      &location=37.76999%2C-122.44696
      &radius=500
      &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&key=YOUR_API_KEY'

Cùng một yêu cầu, nhưng chỉ giới hạn ở kết quả trong vòng 500 mét từ đường Ashbury và đường Haight, San Francisco:

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=amoeba
      &types=establishment
      &location=37.76999%2C-122.44696&radius=500
      &strictbounds=true
      &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&strictbounds=true&key=YOUR_API_KEY'

Yêu cầu về địa chỉ có chứa "Vict" với kết quả bằng tiếng Pháp:

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=Vict
      &types=geocode
      &language=fr
      &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=geocode&language=fr&key=YOUR_API_KEY'

Yêu cầu về các thành phố có chứa "Vict" bằng tiếng Bồ Đào Nha (Brazil):

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=Vict
      &types=(cities)
      &language=pt_BR&key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=(cities)&language=pt_BR&key=YOUR_API_KEY'

Xin lưu ý rằng bạn cần thay thế khoá API trong các ví dụ này bằng khoá của riêng bạn.

Phản hồi của tính năng Place Autocomplete (Cũ)

Phản hồi của Place Autocomplete (Phiên bản cũ) được trả về theo định dạng do cờ output chỉ ra trong đường dẫn URL của yêu cầu. Các kết quả bên dưới cho biết những gì có thể được trả về cho một truy vấn có các tham số sau:

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=Paris
      &types=geocode
      &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Paris&types=geocode&key=YOUR_API_KEY'

{
  "predictions":
    [
      {
        "description": "Paris, France",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
        "reference": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "France",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "France" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, TX, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJmysnFgZYSoYRSfPTL2YJuck",
        "reference": "ChIJmysnFgZYSoYRSfPTL2YJuck",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "TX, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "TX" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, TN, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJ4zHP-Sije4gRBDEsVxunOWg",
        "reference": "ChIJ4zHP-Sije4gRBDEsVxunOWg",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "TN, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "TN" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, Brant, ON, Canada",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJsamfQbVtLIgR-X18G75Hyi0",
        "reference": "ChIJsamfQbVtLIgR-X18G75Hyi0",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "Brant, ON, Canada",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "Brant" },
            { "offset": 14, "value": "ON" },
            { "offset": 18, "value": "Canada" },
          ],
        "types": ["neighborhood", "political", "geocode"],
      },
      {
        "description": "Paris, KY, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJsU7_xMfKQ4gReI89RJn0-RQ",
        "reference": "ChIJsU7_xMfKQ4gReI89RJn0-RQ",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "KY, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "KY" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
    ],
  "status": "OK",
}

    
<?xml version="1.0" encoding="UTF-8"?>
<AutocompletionResponse>
 <status>OK</status>
 <prediction>
  <description>Paris, France</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>France</value>
   <offset>7</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>France</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, TX, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJmysnFgZYSoYRSfPTL2YJuck</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TX</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJmysnFgZYSoYRSfPTL2YJuck</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>TX, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, TN, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJ4zHP-Sije4gRBDEsVxunOWg</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TN</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJ4zHP-Sije4gRBDEsVxunOWg</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>TN, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, Brant, ON, Canada</description>
  <type>neighborhood</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJsamfQbVtLIgR-X18G75Hyi0</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>Brant</value>
   <offset>7</offset>
  </term>
  <term>
   <value>ON</value>
   <offset>14</offset>
  </term>
  <term>
   <value>Canada</value>
   <offset>18</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJsamfQbVtLIgR-X18G75Hyi0</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>Brant, ON, Canada</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, KY, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJsU7_xMfKQ4gReI89RJn0-RQ</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>KY</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJsU7_xMfKQ4gReI89RJn0-RQ</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>KY, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
</AutocompletionResponse>

   

PlacesAutocompleteResponse

Trong số các kết quả, bạn đặc biệt quan tâm đến các phần tử place_id. Bạn có thể dùng các phần tử này để yêu cầu thông tin chi tiết cụ thể hơn về địa điểm bằng một cụm từ tìm kiếm riêng. Xem yêu cầu Chi tiết địa điểm (Phiên bản cũ).

Phản hồi XML bao gồm một phần tử <AutocompletionResponse> duy nhất với hai loại phần tử con:

• Một phần tử <status> duy nhất chứa siêu dữ liệu về yêu cầu. Hãy xem Mã trạng thái bên dưới.
• Từ 0 phần tử <prediction> trở lên, mỗi phần tử chứa thông tin về một địa điểm. Hãy xem Kết quả của tính năng Place Autocomplete (Phiên bản cũ) để biết thông tin về những kết quả này. Places API trả về tối đa 5 kết quả.

Bạn nên dùng json làm cờ đầu ra ưu tiên, trừ phi ứng dụng của bạn yêu cầu xml vì lý do nào đó. Bạn cần cẩn thận khi xử lý các cây XML để tham chiếu các nút và phần tử thích hợp. Hãy xem phần Xử lý XML bằng XPath để được trợ giúp xử lý XML.

PlacesAutocompleteStatus

Mã trạng thái do dịch vụ trả về.

• OK cho biết yêu cầu API đã thành công.
• ZERO_RESULTS cho biết quá trình tìm kiếm đã thành công nhưng không trả về kết quả nào. Điều này có thể xảy ra nếu cụm từ tìm kiếm được truyền một ranh giới ở một vị trí từ xa.
• INVALID_REQUEST cho biết yêu cầu API bị lỗi định dạng, thường là do thiếu tham số input.
• OVER_QUERY_LIMIT cho biết bất kỳ thông tin nào sau đây:
  • Bạn đã vượt quá giới hạn QPS.
  • Bạn chưa bật tính năng thanh toán cho tài khoản của mình.
  • Bạn đã vượt quá hạn mức sử dụng tự đặt hoặc hạn mức tín dụng 200 USD hằng tháng.
  • Phương thức thanh toán bạn cung cấp không còn hợp lệ (ví dụ: thẻ tín dụng đã hết hạn).
  Xem phần Câu hỏi thường gặp về Maps để biết thêm thông tin về cách khắc phục lỗi này.
• REQUEST_DENIED cho biết yêu cầu của bạn đã bị từ chối, thường là do:
  • Yêu cầu thiếu khoá API.
  • Tham số key không hợp lệ.
• UNKNOWN_ERROR cho biết đã xảy ra lỗi không xác định.

Khi dịch vụ Places trả về kết quả JSON từ một cụm từ tìm kiếm, dịch vụ này sẽ đặt các kết quả đó trong một mảng predictions. Ngay cả khi dịch vụ không trả về kết quả nào (chẳng hạn như nếu location ở xa), dịch vụ vẫn trả về một mảng predictions trống. Phản hồi XML bao gồm 0 hoặc nhiều phần tử <prediction>.

PlaceAutocompletePrediction

PlaceAutocompleteMatchedSubstring

PlaceAutocompleteStructuredFormat

PlaceAutocompleteTerm

Tối ưu hoá Place Autocomplete (Phiên bản cũ)

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ụ Place Autocomplete (Legacy).

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

• Cách nhanh nhất để phát triển một giao diện người dùng hoạt động là sử dụng tiện ích Place Autocomplete (Cũ) của Maps JavaScript API, tiện ích Place Autocomplete (Cũ) của Places SDK cho Android hoặc thành phần điều khiển trên giao diện người dùng Place Autocomplete (Cũ) của Places SDK cho iOS.
• Ngay từ đầu, hãy tìm hiểu các trường dữ liệu cần thiết của tính năng Place Autocomplete (Phiên bản cũ).
• 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ụ Place Autocomplete (Cũ), hãy sử dụng mặt nạ trường trong các tiện ích Place Details (Cũ) và Place Autocomplete (Cũ) để chỉ trả về các trường dữ liệu Place Autocomplete (Cũ) 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 Place Autocomplete (Cũ) để truy cập vào SKU: Autocomplete – Mức giá theo yêu cầu và yêu cầu kết quả Geocoding API về địa điểm đã chọn thay vì Place Details (Cũ). 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 đề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 (Legacy).
• 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 Place Autocomplete (Phiên bản cũ) 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 địa điểm (Phiên bản cũ):

• Thêm các hạn chế theo quốc gia, thiên vị vị trí và (đối với các cách triển khai có lập trình) ngôn ngữ ưu tiên vào cách triển khai Place Autocomplete (Cũ). 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 Place Autocomplete (Legacy) đ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 kết quả dự đoán của tính năng Place Autocomplete (phiên bản cũ), thường là do không có kết quả dự đoán nào là địa chỉ mà họ muốn, bạn có thể sử dụng lại hoạt động đầ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 hoạt động đầ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 (Phiên bản cũ). 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 sử 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ẽ cho ra một cụm từ gợi ý một phần trong tính năng Place Autocomplete (Phiên bản cũ).
  • 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 Place Autocomplete (Phiên bản cũ) ư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ả 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ố strictbounds. Thao tác này hướng dẫn tính năng Place Autocomplete (Phiên bản cũ) chỉ trả về kết quả trong khu vực đó.