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 này 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à điểm yêu thích khi người dùng nhập.

Yêu cầu về Place Autocomplete (Cũ)

Tính năng Place Autocomplete (Cũ) là một phần của Places API, đồng thời dùng chung khoá API và hạn mức với Places API.

Place Autocomplete (Cũ) có thể so khớp các từ và chuỗi con đầy đủ, 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 địa điểm nhanh chóng.

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

• mã toàn cầu là mã vùng gồm 4 ký tự và mã địa phương gồm 6 ký tự trở lên. Ví dụ: mã toàn cầu 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í rõ ràng. Ví dụ: mã cộng gộp được 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ế để hiển thị 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 yêu cầu Chi tiết địa điểm (Cũ) để biết thêm thông tin về bất kỳ địa điểm nào được trả về.

Yêu cầu về tính năng Place Autocomplete (Cũ) là một URL loại HTTP có dạng như sau:

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

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

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

Bạn cần 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ả tham số đều được phân tách bằng ký tự dấu và (&). Danh sách các tham số và giá trị có thể có của các tham số đó được liệt kê bên dưới.

Tham số bắt buộc

input

Chuỗi văn bản cần tìm kiếm. Dịch vụ Place Autocomplete sẽ 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 của chúng.

Thông số tùy chọn

thành phần

Một nhóm đị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. Quốc gia phải được truyền dưới dạng mã quốc gia gồm hai 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ả của bạn ở những địa điểm trong nước Pháp. Bạn phải truyền nhiều quốc gia dưới dạng nhiều bộ lọc country:XX, trong đó ký tự dấu gạch đứng | đóng vai trò là dấu phân tách. Ví dụ: components=country:us|country:pr|country:vi|country:gu|country:mp sẽ giới hạn kết quả của bạn ở những địa điểm trong Hoa Kỳ và các lãnh thổ có tổ chức chưa hợp nhất của Hoa Kỳ.

language

Ngôn ngữ để trả về kết quả.

• Xem danh sách 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ể không đầy đủ.
• Nếu bạn không cung cấp language, thì 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 hết sức để cung cấp đị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 đó, API này sẽ trả về địa chỉ đường phố bằng ngôn ngữ địa phương, được chuyển tự sang một hệ chữ viết mà người dùng có thể đọc được nếu cần, đồng thời tuân thủ ngôn ngữ ưu tiên. Tất cả các địa chỉ khác được trả về bằng ngôn ngữ ưu tiên. Tất 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 tên phù hợp nhất.
• 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ề. Bộ 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à các từ đồng nghĩa với "đường" 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.

locationbias

Ưu tiê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 hình chữ nhật. Nếu bạn không chỉ định tham số này, thì theo mặc định, API sẽ sử dụng tính năng thiên vị địa chỉ IP.

• Xu hướng IP: Hướng dẫn API sử dụng xu hướng địa chỉ IP. Truyền chuỗi ipbias (tuỳ 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 hai cặp vĩ độ/kinh độ theo độ thập phân, biểu thị các điểm nam/tây và bắc/đông của một hình chữ nhật. Hãy 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ả ở 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 hai cặp vĩ độ/kinh độ theo độ thập phân, biểu thị các điểm nam/tây và bắc/đông của một hình chữ nhật. Hãy 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í (trong cụm từ nhập vào) của ký tự cuối cùng mà dịch vụ sử dụng để so khớp cụm từ gợi ý. Ví dụ: nếu giá trị đầu vào là Google và độ lệch là 3, thì dịch vụ sẽ khớp với Goo. Chuỗi được xác định theo độ lệch chỉ được so khớp với từ đầu tiên trong cụm từ đầu vào. Ví dụ: nếu cụm từ đầ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ừ. Thông thường, bạn nên đặt độ lệch thành vị trí của con 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 điểm đến (được trả về dưới dạng distance_meters). Nếu giá trị này bị bỏ qua, thì khoảng cách theo đường thẳng sẽ không được trả về. Phải được 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ể thiên vị kết quả cho một vòng tròn cụ thể bằng cách truyền tham số location và radius. Thao tác này sẽ hướng dẫn dịch vụ Địa điểm ư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ể hiển thị.

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

• Tự động hoàn thành: 50.000 mét
• Nearby Search:
  • với keyword hoặc name: 50.000 mét
  • mà không có keyword hoặc name
    • Tối đa 50.000 mét, được điều chỉnh linh động 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

region

Mã khu vực, đượ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 ngoại lệ đáng chú ý. Ví dụ: ccTLD của Vương quốc Anh là "uk" (.co.uk) trong khi mã ISO 3166-1 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").

sessiontoken

Một chuỗi ngẫu nhiên giúp 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 cụm từ tìm kiếm và kết thúc khi họ chọn một địa điểm và lệnh gọi đến Place Details được thực hiện. Mỗi phiên có thể có nhiều cụm từ tìm kiếm, theo sau là một lựa chọn địa điểm. (Các) khoá API 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 phiên kết thúc, mã thông báo sẽ không còn hợp lệ; ứ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ã phiên, thì phiên đó sẽ được tính phí như thể không có mã phiên nào được cung cấp (mỗi yêu cầu được tính phí riêng).

Bạn nên làm theo 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ã 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 dùng cho tất cả yêu cầu về Place Autocomplete và Place Details trong một phiên đều 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 riêng biệt cho mỗi phiên mới. Nếu bạn sử dụng cùng một mã thông báo cho nhiều phiên, thì mỗi yêu cầu sẽ được tính phí riêng.

strictbounds

Chỉ trả về những địa điểm nằm hoàn toàn trong khu vực được xác định bằng location và radius. Đây là một quy định hạn chế chứ không phải là một 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 khớp với thông tin đầu vào của người dùng.

loại

Bạn có thể hạn chế kết quả của 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 Loại địa điểm. Nếu bạn không chỉ định loại nào, 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 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 có thể chỉ được trả về bằng types=lodging chứ không phải bằng types=restaurant.

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

• Tối đa 5 giá trị trong 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

• Bất kỳ bộ lọc đơn lẻ nào được hỗ trợ trong Bảng 3. Bạn không thể kết hợp các tập hợp kiểu.

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.
• Có bất kỳ loại nào không được nhận dạng.
• Bất kỳ loại nào trong Bảng 1 hoặc Bảng 2 được kết hợp với bất kỳ bộ lọc nào trong Bảng 3.

Ví dụ về 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 có 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 ở các kết quả trong phạm vi 500 mét tính từ Ashbury St và Haight St, 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ỉ 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" với kết quả 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 Place Autocomplete (Cũ)

Phản hồi của Place Autocomplete (Cũ) được trả về theo định dạng được chỉ định bằng cờ output trong đường dẫn URL của yêu cầu. 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

Điều đặc biệt thú vị trong kết quả là 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 truy vấn riêng. Xem Yêu cầu về 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 có hai loại phần tử con:

• Một phần tử <status> chứa siêu dữ liệu về yêu cầu. Hãy xem phần Mã trạng thái bên dưới.
• Không hoặc nhiều phần tử <prediction>, mỗi phần tử chứa thông tin về một địa điểm. Hãy xem phần Kết quả của tính năng Tự động hoàn thành địa điểm (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 sử 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 đó. Việc xử lý cây XML cần được thực hiện cẩn thận để bạn tham chiếu đúng nút và phần tử. Hãy xem bài viết Xử lý XML bằng XPath để được trợ giúp về cách 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 rằng 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 nội dung tìm kiếm được chuyển đến một ranh giới ở một vị trí từ xa.
• INVALID_REQUEST cho biết yêu cầu API không đúng định dạng, thường là do thiếu tham số input.
• OVER_QUERY_LIMIT cho biết bất kỳ điều nào sau đây:
  • Bạn đã vượt quá giới hạn QPS.
  • Tài khoản của bạn chưa được bật tính năng thanh toán.
  • Bạn đã vượt quá khoản tín dụng 200 USD hằng tháng hoặc hạn mức sử dụng do bạn tự đặt ra.
  • Phương thức thanh toán được cung cấp không còn hợp lệ (ví dụ: thẻ tín dụng đã hết hạn).
  Hãy xem phần Câu hỏi thường gặp về Maps để biết thêm thông tin về cách giải quyết 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 lỗi không xác định.

Khi dịch vụ Địa điểm trả về kết quả JSON từ một lượt tìm kiếm, dịch vụ này sẽ đặt các kết quả đó vào 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), thì 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á tính năng Place Autocomplete (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 (Cũ).

Sau đâ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 được là sử dụng tiện ích Place Autocomplete (Cũ) của API JavaScript của Maps, tiện ích Place Autocomplete (Cũ) của SDK Địa điểm 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 SDK Địa điểm cho iOS.
• Tìm hiểu ngay từ đầu về các trường dữ liệu thiết yếu 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 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 xuống cấp một cách linh hoạt nếu API trả về lỗi.
• Đảm bảo ứng dụng của bạn xử lý được trường hợp 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ề trường dữ liệu Place Autocomplete (Cũ) mà bạn cần.

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

Cân nhắc triển khai Place Autocomplete (Cũ) theo phương thức lập trình để sử dụng SKU: Tự động hoàn thành – Giá theo yêu cầu và yêu cầu kết quả của Geocoding API về địa điểm đã chọn thay vì Place Details (Cũ). 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 (Cũ).
• 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 (Cũ) trở xuống, thì mô hình định giá theo yêu cầu có thể tiết kiệm chi phí hơn so với mô hình định giá theo phiên.

Geocoding API có thể là một lựa chọn tiết kiệm chi phí hơn so với Place Details (Phiên bản cũ) cho ứng dụng của bạn, tuỳ thuộc vào hiệu suất sử dụng Place Autocomplete (Phiên bản cũ). Hiệu quả của tính năng Place Autocomplete (Cũ) của 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ố lượng yêu cầu trung bình cho bảng, hãy phân tích số lượng ký tự mà người dùng nhập trung bình trước khi chọn một cụm từ gợi ý của tính năng Place Autocomplete (Cũ) trong ứng dụng của bạn.

Tính năng Tự động hoàn thành địa điểm dựa trên phiên (Cũ) có thông tin chi tiết về địa điểm (Cũ)

Sử dụng tính năng Place Autocomplete dựa trên phiên (Phiên bản cũ) cùng với Place Details (Phiên bản cũ).
Vì ứng dụng của bạn yêu cầu Chi tiết địa điểm (Cũ), 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 địa điểm (Cũ) 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 SKU Dữ liệu đị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.¹

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 về tính năng Place Autocomplete (Cũ) và yêu cầu về Place Details (Cũ) trên 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 Place Autocomplete (Cũ) mà bạn cần.

Triển khai có lập trình
Sử dụng mã phiên với các yêu cầu Place Autocomplete (Cũ). Khi yêu cầu Chi tiết địa điểm (Cũ) 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 Place Autocomplete (Phiên bản cũ)
2. Mã thông báo phiên được dùng trong yêu cầu Place Autocomplete (Cũ)
3. Tham số fields chỉ định trường dữ liệu của tính năng Place Autocomplete (Cũ) mà bạn cần

Tính năng Tự động hoàn thành địa điểm (Cũ) theo yêu cầu bằng Geocoding API

Triển khai Place Autocomplete (Cũ) theo phương thức lập trình mà không cần mã 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 – Per Request (Tự động hoàn thành – Theo yêu cầu) 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 Place Autocomplete (Phiên bản cũ).¹

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.

Place Autocomplete dựa trên phiên (Cũ) cho các ứng dụng chỉ có địa chỉ

Sử dụng tính năng Place Autocomplete dựa trên phiên (Phiên bản cũ) cùng với Place Details (Phiên bản cũ).
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 Place Autocomplete (Cũ) vượt quá chi phí của mức giá theo phiên, nên việc triển khai tính năng Place Autocomplete (Cũ) phải sử dụng mã phiên cho cả yêu cầu Place Autocomplete (Cũ) và yêu cầu Place Details (Cũ) liên quan theo phiên. ¹

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 về tính năng Place Autocomplete (Cũ) và yêu cầu về Place Details (Cũ) đố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ã phiên với các yêu cầu Place Autocomplete (Cũ). Khi yêu cầu Place Details (Cũ) 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 Place Autocomplete (Phiên bản cũ)
2. Mã thông báo phiên được dùng trong yêu cầu Place Autocomplete (Cũ)
3. Tham số fields chỉ định các trường dữ liệu Dữ liệu cơ bản, 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 của tính năng Place Autocomplete (Phiên bản cũ)
Bạn có thể áp dụng các chiến lược như trì hoãn yêu cầu của tính năng Place Autocomplete (Phiên bản cũ) 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ụ: nếu bạn đưa ra yêu cầu Place Autocomplete (Cũ) cho mỗi ký tự sau khi người dùng nhập ký tự thứ ba, thì tức 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 Geocoding API, thì tổng chi phí sẽ là 4 yêu cầu Place Autocomplete (Cũ) theo yêu cầu + Geocoding.¹

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 về cách triển khai Place Autocomplete (Cũ) 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ể được người dùng coi là độ trễ, người dùng có thể muốn xem 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.

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 Place Autocomplete (Phiên bản cũ):

• 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 vào quá trình triển khai Place Autocomplete (Cũ). 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 Place Autocomplete (Cũ) đi kèm với bản đồ, thì 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 Place Autocomplete (Cũ), 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 (Cũ). 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 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 ý không đầy đủ 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ị trí

Tạo độ lệch cho kết quả theo 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 Place Autocomplete (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ả 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ố strictbounds. Thao tác này hướng dẫn tính năng Place Autocomplete (Cũ) chỉ trả về kết quả trong khu vực đó.