Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

查詢自動完成 (舊版)

歐洲經濟區 (EEA) 開發人員

注意：伺服器端和用戶端程式庫

Places API 也適用於 Google 地圖服務的 Java 用戶端、Python 用戶端、Go 用戶端和 Node.js 用戶端。Places API 和用戶端程式庫適用於伺服器應用程式。

如果您要建構用戶端應用程式，請參閱 Places SDK for Android (新版)、Places SDK for iOS (新版) 和 Maps JavaScript API 的 Places Library。

Query Autocomplete (舊版) 可在您輸入文字時傳回建議查詢，為文字地理搜尋提供查詢預測。

Query Autocomplete (舊版) 要求

Query Autocomplete (舊版) 是 Places API (舊版) 的一部分，與 Places API (舊版) 共用 API 金鑰和配額。

Query Autocomplete (舊版) 可讓您在應用程式中，即時新增地理查詢預測功能。使用者可以輸入類別搜尋，例如「臺北附近的披薩」，而不是搜尋特定位置，服務會傳回與字串相符的建議查詢清單。Query Autocomplete (舊版) 可比對完整字詞和子字串，因此應用程式可在使用者輸入內容時傳送查詢，即時提供預測結果。

Query Autocomplete (舊版) 要求的 HTTP 網址格式如下：

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

其中 output 可以是 json 或 xml。

您必須提供特定參數，才能發出 Query Autocomplete (舊版) 要求。依照網址標準，所有參數都會以 & 字元分隔。以下列出參數和可能的值。

必要參數

輸入

要搜尋的文字字串。Place Autocomplete 服務會根據這個字串傳回候選相符項目，並依據觀察到的關聯性排序結果。

選用參數

language

傳回結果時使用的語言。

請參閱支援語言清單。Google 會經常更新支援的語言，因此這份清單可能不完整。
如未提供 language，API 會嘗試使用 Accept-Language 標頭中指定的偏好語言。
API 會盡可能提供使用者和當地人都能看懂的街道地址。為達成這個目標，系統會以當地語言傳回街道地址，並視需要按照偏好語言，將地址音譯為使用者可閱讀的文字。所有其他地址都會以偏好語言傳回。系統會以相同語言傳回所有地址元件，並根據第一個元件選擇語言。
如果沒有偏好語言的名稱，API 會使用最接近的相符項目。
偏好語言對 API 選擇傳回的結果集和傳回順序影響不大。地理編碼器會根據語言，以不同方式解讀縮寫，例如街道類型的縮寫，或在某種語言中有效，但在另一種語言中無效的同義詞。舉例來說，utca 和 tér 在匈牙利文都是街道的意思。

位置

定義搜尋範圍的中心點，以 latitude,longitude 座標表示。Places 服務會根據位置資訊調整搜尋結果，優先顯示 location 和 radius 定義區域內的結果，但仍可能顯示定義區域外的結果。

如果 query 包含明確位置 (例如 Market in Barcelona)，系統可能會覆寫 location 參數。在查詢前後加上引號，也可能會影響 location 和 radius 的權重。

碳補償

服務用來比對預測結果的最後一個字元在輸入字詞中的位置。舉例來說，如果輸入內容為 Google，偏移量為 3，服務就會比對 Goo。系統只會根據偏移量確定的字串，與輸入字詞中的第一個字詞進行比對。舉例來說，如果輸入字詞為 Google abc，偏移量為 3，服務會嘗試比對 Goo abc。如未提供偏移值，服務會使用整個字詞。偏移量通常應設為文字插入點的位置。

半徑

定義傳回地點結果的距離 (以公尺為單位)。您可以傳送 location 和 radius 參數，針對特定圓形範圍調整結果。這樣就能指示 Places 服務優先顯示該圓形範圍內的結果。不過，系統還是有可能會顯示定義區域外的結果。

系統會根據搜尋類型和其他參數，自動將半徑限制在最大值。

自動完成：50,000 公尺
Nearby Search：
- keyword 或 name：50,000 公尺
- 不含 keyword 或 name
  - 上限為 50,000 公尺，系統會根據區域密度動態調整，不受 rankby 參數影響。
  - 使用 rankby=distance 時，系統不會接受半徑參數，並會產生 INVALID_REQUEST。
Query Autocomplete：50,000 公尺
Text Search：50,000 公尺

Query Autocomplete (舊版) 範例

網址

https://maps.googleapis.com/maps/api/place/queryautocomplete/json
  ?input=pizza%20near%20par
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/queryautocomplete/json?input=pizza%20near%20par&key=YOUR_API_KEY'

搜尋「Pizza near Par」，結果以法文顯示：

網址

https://maps.googleapis.com/maps/api/place/queryautocomplete/json
  ?input=pizza%20near%20par
  &language=fr
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/queryautocomplete/json?input=pizza%20near%20par&language=fr&key=YOUR_API_KEY'

請注意，您需要將這些範例中的 API 金鑰替換成自己的金鑰。

Query Autocomplete (舊版) 回應

Query Autocomplete (舊版) 回應會以網址要求路徑中 output 標記指定的格式傳回。以下是使用下列參數查詢時傳回的結果：

網址

https://maps.googleapis.com/maps/api/place/queryautocomplete/json
  ?input=pizza%20near%20par
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/queryautocomplete/json?input=pizza%20near%20par&key=YOUR_API_KEY'

JSON

{
  "predictions":
    [
      {
        "description": "pizza near Paris, France",
        "matched_substrings":
          [{ "length": 5, "offset": 0 }, { "length": 3, "offset": 11 }],
        "structured_formatting":
          {
            "main_text": "pizza",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "near Paris, France",
            "secondary_text_matched_substrings": [{ "length": 3, "offset": 5 }],
          },
        "terms":
          [
            { "offset": 0, "value": "pizza" },
            { "offset": 6, "value": "near" },
            { "offset": 11, "value": "Paris" },
            { "offset": 18, "value": "France" },
          ],
      },
      {
        "description": "pizza near Pari Chowk, NRI City, Omega II, Noida, Uttar Pradesh, India",
        "matched_substrings":
          [{ "length": 5, "offset": 0 }, { "length": 3, "offset": 11 }],
        "structured_formatting":
          {
            "main_text": "pizza",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "near Pari Chowk, NRI City, Omega II, Noida, Uttar Pradesh, India",
            "secondary_text_matched_substrings": [{ "length": 3, "offset": 5 }],
          },
        "terms":
          [
            { "offset": 0, "value": "pizza" },
            { "offset": 6, "value": "near" },
            { "offset": 11, "value": "Pari Chowk" },
            { "offset": 23, "value": "NRI City" },
            { "offset": 33, "value": "Omega II" },
            { "offset": 43, "value": "Noida" },
            { "offset": 50, "value": "Uttar Pradesh" },
            { "offset": 65, "value": "India" },
          ],
      },
      {
        "description": "pizza near Disneyland Park, Disneyland Drive, Anaheim, CA, USA",
        "matched_substrings":
          [{ "length": 5, "offset": 0 }, { "length": 3, "offset": 22 }],
        "structured_formatting":
          {
            "main_text": "pizza",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "near Disneyland Park, Disneyland Drive, Anaheim, CA, USA",
            "secondary_text_matched_substrings":
              [{ "length": 3, "offset": 16 }],
          },
        "terms":
          [
            { "offset": 0, "value": "pizza" },
            { "offset": 6, "value": "near" },
            { "offset": 11, "value": "Disneyland Park" },
            { "offset": 28, "value": "Disneyland Drive" },
            { "offset": 46, "value": "Anaheim" },
            { "offset": 55, "value": "CA" },
            { "offset": 59, "value": "USA" },
          ],
      },
      {
        "description": "pizza near Cathédrale Notre-Dame de Paris, Parvis Notre-Dame - place Jean-Paul-II, Paris, France",
        "matched_substrings":
          [{ "length": 5, "offset": 0 }, { "length": 3, "offset": 36 }],
        "structured_formatting":
          {
            "main_text": "pizza",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "near Cathédrale Notre-Dame de Paris, Parvis Notre-Dame - place Jean-Paul-II, Paris, France",
            "secondary_text_matched_substrings":
              [{ "length": 3, "offset": 30 }],
          },
        "terms":
          [
            { "offset": 0, "value": "pizza" },
            { "offset": 6, "value": "near" },
            { "offset": 11, "value": "Cathédrale Notre-Dame de Paris" },
            { "offset": 43, "value": "Parvis Notre-Dame - place Jean-Paul-II" },
            { "offset": 83, "value": "Paris" },
            { "offset": 90, "value": "France" },
          ],
      },
      {
        "description": "pizza near Paris Beauvais Airport, Route de l'Aéroport, Tillé, France",
        "matched_substrings":
          [{ "length": 5, "offset": 0 }, { "length": 3, "offset": 11 }],
        "structured_formatting":
          {
            "main_text": "pizza",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "near Paris Beauvais Airport, Route de l'Aéroport, Tillé, France",
            "secondary_text_matched_substrings": [{ "length": 3, "offset": 5 }],
          },
        "terms":
          [
            { "offset": 0, "value": "pizza" },
            { "offset": 6, "value": "near" },
            { "offset": 11, "value": "Paris Beauvais Airport" },
            { "offset": 35, "value": "Route de l'Aéroport" },
            { "offset": 56, "value": "Tillé" },
            { "offset": 63, "value": "France" },
          ],
      },
    ],
  "status": "OK",
}

XML

      
<AutocompletionResponse>
 <status>OK</status>
 <prediction>
  <description>pizza near Paris, France</description>
  <term>
   <value>pizza</value>
   <offset>0</offset>
  </term>
  <term>
   <value>near</value>
   <offset>6</offset>
  </term>
  <term>
   <value>Paris</value>
   <offset>11</offset>
  </term>
  <term>
   <value>France</value>
   <offset>18</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>11</offset>
   <length>3</length>
  </matched_substring>
  <structured_formatting>
   <description>pizza</description>
   <subdescription>near Paris, France</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
   <subdescription_matched_substring>
    <offset>5</offset>
    <length>3</length>
   </subdescription_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>pizza near Pari Chowk, NRI City, Omega II, Noida, Uttar Pradesh, India</description>
  <term>
   <value>pizza</value>
   <offset>0</offset>
  </term>
  <term>
   <value>near</value>
   <offset>6</offset>
  </term>
  <term>
   <value>Pari Chowk</value>
   <offset>11</offset>
  </term>
  <term>
   <value>NRI City</value>
   <offset>23</offset>
  </term>
  <term>
   <value>Omega II</value>
   <offset>33</offset>
  </term>
  <term>
   <value>Noida</value>
   <offset>43</offset>
  </term>
  <term>
   <value>Uttar Pradesh</value>
   <offset>50</offset>
  </term>
  <term>
   <value>India</value>
   <offset>65</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>11</offset>
   <length>3</length>
  </matched_substring>
  <structured_formatting>
   <description>pizza</description>
   <subdescription>near Pari Chowk, NRI City, Omega II, Noida, Uttar Pradesh, India</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
   <subdescription_matched_substring>
    <offset>5</offset>
    <length>3</length>
   </subdescription_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>pizza near Disneyland Park, Disneyland Drive, Anaheim, CA, USA</description>
  <term>
   <value>pizza</value>
   <offset>0</offset>
  </term>
  <term>
   <value>near</value>
   <offset>6</offset>
  </term>
  <term>
   <value>Disneyland Park</value>
   <offset>11</offset>
  </term>
  <term>
   <value>Disneyland Drive</value>
   <offset>28</offset>
  </term>
  <term>
   <value>Anaheim</value>
   <offset>46</offset>
  </term>
  <term>
   <value>CA</value>
   <offset>55</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>59</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>22</offset>
   <length>3</length>
  </matched_substring>
  <structured_formatting>
   <description>pizza</description>
   <subdescription>near Disneyland Park, Disneyland Drive, Anaheim, CA, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
   <subdescription_matched_substring>
    <offset>16</offset>
    <length>3</length>
   </subdescription_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>pizza near Cathédrale Notre-Dame de Paris, Parvis Notre-Dame - place Jean-Paul-II, Paris, France</description>
  <term>
   <value>pizza</value>
   <offset>0</offset>
  </term>
  <term>
   <value>near</value>
   <offset>6</offset>
  </term>
  <term>
   <value>Cathédrale Notre-Dame de Paris</value>
   <offset>11</offset>
  </term>
  <term>
   <value>Parvis Notre-Dame - place Jean-Paul-II</value>
   <offset>43</offset>
  </term>
  <term>
   <value>Paris</value>
   <offset>83</offset>
  </term>
  <term>
   <value>France</value>
   <offset>90</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>36</offset>
   <length>3</length>
  </matched_substring>
  <structured_formatting>
   <description>pizza</description>
   <subdescription>near Cathédrale Notre-Dame de Paris, Parvis Notre-Dame - place Jean-Paul-II, Paris, France</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
   <subdescription_matched_substring>
    <offset>30</offset>
    <length>3</length>
   </subdescription_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>pizza near Paris Beauvais Airport, Route de l'Aéroport, Tillé, France</description>
  <term>
   <value>pizza</value>
   <offset>0</offset>
  </term>
  <term>
   <value>near</value>
   <offset>6</offset>
  </term>
  <term>
   <value>Paris Beauvais Airport</value>
   <offset>11</offset>
  </term>
  <term>
   <value>Route de l'Aéroport</value>
   <offset>35</offset>
  </term>
  <term>
   <value>Tillé</value>
   <offset>56</offset>
  </term>
  <term>
   <value>France</value>
   <offset>63</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>11</offset>
   <length>3</length>
  </matched_substring>
  <structured_formatting>
   <description>pizza</description>
   <subdescription>near Paris Beauvais Airport, Route de l'Aéroport, Tillé, France</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
   <subdescription_matched_substring>
    <offset>5</offset>
    <length>3</length>
   </subdescription_matched_substring>
  </structured_formatting>
 </prediction>
</AutocompletionResponse>

地點服務從搜尋傳回 JSON 結果時，會將結果放入 predictions 陣列中。即使服務未傳回任何結果 (例如 location 位於偏遠地區)，仍會傳回空白的 predictions 陣列。XML 回應包含零或多個 <prediction> 元素。

PlacesQueryAutocompleteResponse

欄位	必填	類型	說明
`predictions`	required	Array<PlaceAutocompletePrediction>	包含預測陣列。詳情請參閱 PlaceAutocompletePrediction。
`status`	required	PlacesAutocompleteStatus	包含要求的狀態，也可能包含偵錯資訊，方便您追查要求失敗的原因。詳情請參閱 PlacesAutocompleteStatus。
`error_message`	選填	字串	如果服務傳回 `OK` 以外的狀態碼，回應物件中可能會有額外的 `error_message` 欄位。這個欄位包含更詳細的資訊，說明指定狀態碼背後的原因。系統不一定會傳回這個欄位，且內容可能會有變動。
`info_messages`	選填	Array<string>	如果服務傳回要求規格的其他資訊，回應物件中可能會有額外的 `info_messages` 欄位。只有成功的要求才會傳回這個欄位。系統不一定會傳回這項資訊，且內容可能會有變動。

PlacesAutocompleteStatus

服務傳回的狀態碼。

OK：表示已成功完成 API 要求。
ZERO_RESULTS：表示搜尋成功，但未傳回任何結果。如果搜尋作業收到偏遠位置的邊界，就可能發生這種情況。
INVALID_REQUEST：表示 API 要求的格式有誤，通常是因為缺少 input 參數。
OVER_QUERY_LIMIT，表示下列任一情況：
- 您已超過 QPS 限制。
- 您的帳戶未啟用計費功能。
- 超過每月 $200 美元的抵免額或自行設定的用量上限。
- 您提供的付款方式已失效 (例如信用卡已過期)。
如要進一步瞭解如何解決這項錯誤，請參閱地圖常見問題。
REQUEST_DENIED：表示您的要求遭拒，通常是因為：
- 要求中缺少 API 金鑰。
- key 參數無效。
UNKNOWN_ERROR：表示發生未知錯誤。

Places 服務從搜尋傳回 JSON 結果時，會將結果放入 predictions 陣列中。即使服務未傳回任何結果 (例如 location 位於遠端)，仍會傳回空白的 predictions 陣列。XML 回應包含零或多個 <prediction> 元素。

PlaceAutocompletePrediction

欄位	必填	類型	說明
`description`	required	字串	包含傳回結果的人類可讀名稱。如果是 `establishment` 結果，這通常是商家名稱。這類內容應按原樣讀取。請勿以程式輔助方式剖析格式化地址。
`matched_substrings`	required	Array<PlaceAutocompleteMatchedSubstring>	子字串清單，說明輸入字詞在預測結果文字中的位置，以便視需要醒目顯示該字詞。詳情請參閱 PlaceAutocompleteMatchedSubstring。
`structured_formatting`	required	PlaceAutocompleteStructuredFormat	提供預先格式化的文字，可在自動完成結果中顯示。這類內容應按原樣讀取。請勿以程式輔助方式剖析格式化地址。詳情請參閱 PlaceAutocompleteStructuredFormat。
`terms`	required	Array<PlaceAutocompleteTerm>	包含字詞陣列，用於識別傳回說明的各個部分 (說明部分通常以半形逗號結尾)。陣列中的每個項目都有 `value` 欄位 (包含字詞文字) 和 `offset` 欄位 (定義這個字詞在說明中的起始位置，以 Unicode 字元為單位)。詳情請參閱 PlaceAutocompleteTerm。
`distance_meters`	選填	整數	與出發地的直線距離 (以公尺為單位)。只有使用 `origin` 提出的要求，才會傳回這個欄位。
`place_id`	選填	字串	用來識別特定地點的文字 ID。如要擷取地點資訊，請在 Places API 要求的 placeId 欄位中傳遞這個 ID。如要進一步瞭解地點 ID，請參閱地點 ID 總覽。
`reference`	選填	字串	`reference` 已淘汰。請參閱 place_id。
`types`	選填	Array<string>	包含適用於這個地點的類型陣列。例如：`[ "political", "locality" ]` 或 `[ "establishment", "geocode", "beauty_salon" ]`。陣列可以包含多個值。進一步瞭解地點類型。

PlaceAutocompleteMatchedSubstring

欄位	必填	類型	說明
`length`	required	數字	預測結果文字中相符子字串的長度。
`offset`	required	數字	預測結果文字中相符子字串的起始位置。

PlaceAutocompleteStructuredFormat

欄位	必填	類型	說明
`main_text`	required	字串	包含預測的主要文字，通常是地點名稱。
`main_text_matched_substrings`	required	Array<PlaceAutocompleteMatchedSubstring>	包含具有 `offset` 值和 `length` 的陣列。這些值描述了輸入字詞在預測結果文字中的位置，以便在需要時醒目顯示該字詞。詳情請參閱 PlaceAutocompleteMatchedSubstring。
`secondary_text`	選填	字串	包含預測結果的次要文字，通常是地點的位置。
`secondary_text_matched_substrings`	選填	Array<PlaceAutocompleteMatchedSubstring>	包含具有 `offset` 值和 `length` 的陣列。這些值描述了輸入字詞在預測結果文字中的位置，以便在需要時醒目顯示該字詞。詳情請參閱 PlaceAutocompleteMatchedSubstring。

PlaceAutocompleteTerm

欄位	必填	類型	說明
`offset`	required	數字	定義這個字詞在說明中的起始位置，以萬國碼 (Unicode) 字元為單位
`value`	required	字串	字詞文字。

查詢自動完成 (舊版) 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

Query Autocomplete (舊版) 要求

必要參數

輸入

選用參數

language

位置

碳補償

半徑

Query Autocomplete (舊版) 範例

網址

curl

網址

curl

Query Autocomplete (舊版) 回應

網址

curl

JSON

XML

PlacesQueryAutocompleteResponse

predictions

status

error_message

info_messages

PlacesAutocompleteStatus

PlaceAutocompletePrediction

description

matched_substrings

structured_formatting

terms

distance_meters

place_id

reference

types

PlaceAutocompleteMatchedSubstring

length

offset

PlaceAutocompleteStructuredFormat

main_text

main_text_matched_substrings

secondary_text

secondary_text_matched_substrings

PlaceAutocompleteTerm

offset

value

查詢自動完成 (舊版)

`predictions`

`status`

`error_message`

`info_messages`

`description`

`matched_substrings`

`structured_formatting`

`terms`

`distance_meters`

`place_id`

`reference`

`types`

`length`

`offset`

`main_text`

`main_text_matched_substrings`

`secondary_text`

`secondary_text_matched_substrings`

`offset`

`value`