這項產品或功能為舊版。如要進一步瞭解舊版狀態，請參閱「舊版產品和功能」。如要改用 Places API (新版)，請參閱遷移指南。

查詢自動完成 (舊版)

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

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

您也可以透過 Java 用戶端、Python 用戶端、Go 用戶端和 Node.js 用戶端使用 Places API。Places API 和用戶端程式庫適用於伺服器應用程式。

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

查詢自動完成 (舊版) 可在您輸入文字時傳回建議的查詢，為文字型地理搜尋提供查詢預測。

Query Autocomplete (舊版) 要求

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

查詢自動完成 (舊版) 可讓您在應用程式中即時新增地理查詢預測。使用者不必搜尋特定地點，只要輸入類別搜尋內容 (例如「紐約附近的披薩」)，服務就會傳回符合該字串的建議查詢清單。由於查詢自動完成 (舊版) 可比對完整字詞和子字串，應用程式可在使用者輸入內容時傳送查詢，即時提供預測結果。

查詢自動完成 (舊版) 要求是採用下列形式的 HTTP 網址：

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

其中 output 可以是 json 或 xml。

您必須提供特定參數，才能發出查詢自動完成 (舊版) 要求。依照網址標準，所有參數都會以 & 字元分隔。以下列出參數及其可能的值。

必要參數

輸入

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

選用參數

language

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

定義要搜尋的點 (以 latitude,longitude 座標表示)。 Places 服務會使用位置資訊調整搜尋結果，優先顯示 location 和 radius 定義區域內的結果，但仍可能顯示定義區域外的結果。

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

服務用來比對預測結果的最後一個字元在輸入字詞中的位置。舉例來說，如果輸入內容為 Google，且位移為 3，服務會比對 Goo。系統會根據偏移量判斷字串，並只比對輸入字詞中的第一個字。舉例來說，如果輸入的字詞是「Google abc」，且偏移值為 3，服務會嘗試比對「Goo abc」。如未提供偏移量，服務會使用整個詞彙。一般來說，位移應設為文字插入點的位置。
半徑

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

系統會根據搜尋類型和其他參數，自動將半徑限制在最大值內。
- 自動完成：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 (Legacy) 範例

網址

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'

要求「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 (Legacy) 回應

系統會以網址要求路徑中 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>

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

PlacesQueryAutocompleteResponse

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

PlacesAutocompleteStatus

服務傳回的狀態碼。

OK：表示 API 要求成功。
ZERO_RESULTS 表示搜尋成功，但未傳回任何結果。如果搜尋傳遞的界線位於遠端位置，就可能發生這種情況。
INVALID_REQUEST：表示 API 要求格式有誤，通常是因為缺少 input 參數。
OVER_QUERY_LIMIT，表示下列任一情況：
- 您已超過每秒查詢次數限制。
- 您的帳戶尚未啟用帳單功能。
- 超過每月 $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`	選用	陣列<字串>	包含適用於這個地點的類型陣列。例如： `[ "political", "locality" ]` 或 `[ "establishment", "geocode", "beauty_salon" ]`。陣列可以包含多個值。進一步瞭解地點類型。

PlaceAutocompleteMatchedSubstring

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

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 (Legacy) 範例

網址

curl

網址

curl

Query Autocomplete (Legacy) 回應

網址

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`