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

Place Autocomplete (舊版)

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

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

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

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

Place Autocomplete (舊版) 是一項網路服務，可傳回地點預測結果，以回應 HTTP 要求。要求會指定文字搜尋字串和選用的地理邊界。這項服務可用於為文字地理搜尋提供自動完成功能，在使用者輸入內容時傳回商家、地址和搜尋點等地點。

Place Autocomplete (舊版) 要求

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

Place Autocomplete (舊版) 可比對完整字詞和子字串，解析地點名稱、地址和 Plus Code。因此，應用程式可在使用者輸入內容時傳送查詢，即時提供地點預測結果。

Plus Code 必須採用正確格式。也就是說，您必須將加號逸出為 %2B，並將空格逸出為 %20。

全球代碼是四個半形字元的區碼，加上六個半形字元以上的地區代碼。例如，網址逸出全域代碼 849VCWC8+R9 為 849VCWC8%2BR9。
複合代碼是六個半形字元以上的地區代碼，加上明確的位置。舉例來說，網址逸出複合代碼 CWC8+R9 Mountain View, CA, USA 為 CWC8%2BR9%20Mountain%20View%20CA%20USA。

系統會向使用者顯示傳回的預測結果，協助他們選取所需地點。您可以傳送 Place Details (舊版) 要求，索取傳回地點的詳細資訊。

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

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

其中 output 可以是下列任一值：

json (建議)：表示以 JavaScript 物件標記法 (JSON) 輸出
xml 表示輸出為 XML

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

必要參數

輸入

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

選用參數

元件

您想限制結果的地點分組。您可以使用元件，依國家/地區篩選 (最多 5 個)。傳遞國家/地區時，請務必使用雙字元 ISO 3166-1 Alpha-2 相容國家/地區代碼。例如：components=country:fr 會將結果限制在法國境內的地點。如有多個國家/地區，則必須以多個 country:XX 篩選條件的形式傳遞，並以直立線字元 | 做為分隔符號。例如： components=country:us|country:pr|country:vi|country:gu|country:mp 會將結果限制在美國及其非合併組織領土內的地點。

注意：如果使用國家/地區代碼時收到非預期的結果，請確認您使用的代碼是否包含所需的國家/地區、附屬領土和特殊地理區域。如要取得代碼相關資訊，您可以查看維基百科的 ISO 3166 國家/地區代碼清單或 ISO 線上瀏覽平台。

language

傳回結果時使用的語言。

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

位置

要擷取地點資訊的中心點。必須指定為 latitude,longitude。指定位置時，也必須提供 radius 參數。如未提供 radius，系統會忽略 location 參數。

使用 Text Search API 時，如果 `query` 包含明確位置 (例如 `Market in Barcelona`)，系統可能會覆寫 `location` 參數。

locationbias

指定半徑和經緯度，或指定代表矩形點的兩組經緯度，優先顯示特定區域內的結果。如未指定這個參數，API 預設會使用 IP 位址偏向。

IP 偏誤：指示 API 使用 IP 位址偏誤。傳遞字串 ipbias (這個選項沒有其他參數)。
圓形：指定半徑 (以公尺為單位) 的字串，加上經緯度 (以十進制度數表示)。請使用下列格式：circle:radius@lat,lng。
矩形：以十進制度數指定兩組經緯度組合的字串，代表矩形的西南和東北點。請使用下列格式：rectangle:south,west|north,east。請注意，東西向值會納入 -180 到 180 的範圍，南北向值則會限制在 -90 到 90 的範圍。

locationrestriction

指定半徑和經緯度，或指定代表矩形點的兩組經緯度，將結果限制在特定區域。

圓形：指定半徑 (以公尺為單位) 的字串，加上經緯度 (以十進制度數表示)。請使用下列格式：circle:radius@lat,lng。
矩形：以十進制度數指定兩組經緯度組合的字串，代表矩形的西南和東北點。請使用下列格式：rectangle:south,west|north,east。請注意，東西向值會納入 -180 到 180 的範圍，南北向值則會限制在 -90 到 90 的範圍。

碳補償

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

origin

計算與目的地直線距離的起點 (以 distance_meters 傳回)。如果省略這個值，系統就不會傳回直線距離。必須指定為 latitude,longitude。

半徑

定義傳回地點結果的距離 (以公尺為單位)。您可以傳送 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 公尺

區域

區碼，指定為 ccTLD (「頂層網域」) 雙字元值。大多數 ccTLD 代碼與 ISO 3166-1 代碼相同，但有一些需要注意的例外情況。舉例來說，英國的 ccTLD 是「uk」(.co.uk)，而 ISO 3166-1 代碼則是「gb」(技術上代表「大不列顛暨北愛爾蘭聯合王國」)。

sessiontoken

隨機字串，用於識別自動完成工作階段，以便計費。

工作階段是從使用者輸入查詢時開始，到使用者選取地點並呼叫 Place Details 時結束。在每個工作階段中，使用者可以輸入多筆查詢，最終選擇一個地點。在工作階段中，每個要求使用的 API 金鑰都必須屬於同一個 Google Cloud 控制台專案。工作階段結束後，符記就會失效。您的應用程式必須為每個工作階段產生新的符記。如果省略 sessiontoken 參數或重複使用工作階段符記，系統會視為未提供工作階段符記，並針對工作階段收費 (每個要求分別收費)。

建議遵循下列規範：

在所有自動完成工作階段使用工作階段符記。
為每個工作階段產生新的權杖。建議使用第 4 版 UUID。
確認工作階段中所有 Place Autocomplete 和 Place Details 要求使用的 API 金鑰，都屬於同一個 Cloud 控制台專案。
請務必針對每個新的工作階段傳遞不重複的工作階段符記。如果多個工作階段使用同一個權杖，則每個要求會分別計費。

strictbounds

僅傳回完全位於 location 和 radius 定義區域內的地點。這是一項限制，而非偏好設定，也就是說，即使與使用者輸入內容相符，系統也不會傳回這個區域以外的結果。

類型

您可以傳遞 types 參數，將 Place Autocomplete 要求的結果限制為特定類型。這個參數會指定類型或類型集合，如「地點類型」一文所列。如未指定，則會傳回所有類型。

一個地點只能有表 1 或表 2 中列出的單一主要類型。舉例來說，供應餐點的飯店可能只會傳回 types=lodging，而不會傳回 types=restaurant。

types 參數的值可以指定下列其中一項：

表 1或表 2中的值 (最多五個)，如有多個值，請以 | (直線號) 分隔。例如：

types=book_store|cafe
表 3 中任何單一支援的篩選器。您無法混合類型集合。

注意：雖然 geocode 和 establishment 屬於表 2，但在 Place Autocomplete 要求篩選器中，這兩者無法與表 1、2 或 3 中的任何其他類型合併使用。

如有下列情況，要求就會遭拒，並顯示 INVALID_REQUEST 錯誤：

指定超過五個類型。
存在任何無法辨識的類型。
將表 1 或表 2 中的任何類型，與表 3 中的任何篩選器搭配使用。

注意：types 參數僅適用於地點的主要類型，不適用於與地點相關聯的所有類型。雖然每個地點都有主要類型，但並非所有主要類型都受 Places API (新版) 支援。支援的類型包括表 1或表 2中列出的類型。

Place Autocomplete (舊版) 範例

要求在以加州舊金山為中心的區域內，搜尋包含「Amoeba」字串的商家：

網址

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

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'

相同要求，但限制只傳回舊金山 Ashbury St & Haight St 500 公尺內的結果：

網址

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

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'

以下則是針對在搜尋結果中含有 "Vict" (法文) 的地址發出的要求範例：

網址

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

curl

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

要求搜尋包含「Vict」的城市，並以巴西葡萄牙文傳回結果：

網址

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

curl

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

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

Place Autocomplete (舊版) 回應

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

網址

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

curl

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

JSON

{
  "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

    
<?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

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

結果中特別值得注意的是 place_id 元素，可用於透過個別查詢要求更具體的地點詳細資料。請參閱「Place Details (舊版) 要求」。

XML 回應由單一 <AutocompletionResponse> 元素組成，其中包含兩種類型的子元素：

單一 <status> 元素包含要求的相關中繼資料。請參閱下方的狀態碼。
零或多個 <prediction> 元素，每個元素都包含單一地點的相關資訊。如要瞭解這些結果，請參閱「Place Autocomplete (舊版) 結果」。Places API 最多會傳回 5 筆結果。

除非應用程式因故需要 xml，否則建議您使用 json 做為偏好的輸出標記。處理 XML 樹狀結構時，請務必謹慎，確保參照正確的節點和元素。如需處理 XML 的說明，請參閱「使用 XPath 處理 XML」。

在部分自動預測結果中，地點 ID 的 Place Details (舊版) 回應中可能不含 street_number 地址元件。無法插入地點的地址時，通常會發生這種情況。在這種情況下，預測結果的 types 陣列會包含「道路」。如果是說明中含有數字的自動預測結果 (輸入查詢比對成功)，則只有在預測結果的 types 陣列包含下列至少其中一項時，地點 ID 的 Place Details (舊版) 回應才會包含門牌號碼：

street_address
premise
establishment

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	字串	字詞文字。

Place Autocomplete (舊版) 最佳化

本節將說明最佳做法，協助您充分運用 Place Autocomplete (舊版) 服務。

以下列出幾項一般準則：

如要開發有效的使用者介面，最快的方法就是使用 Maps JavaScript API Place Autocomplete (舊版) 小工具、Places SDK for Android Place Autocomplete (舊版) 小工具，或 Places SDK for iOS Place Autocomplete (舊版) UI 控制項。
從一開始就嘗試瞭解 Place Autocomplete (舊版) 的必要資料欄位。
「位置自訂調整」和「位置限制」為自選欄位，但可能會對自動完成效能產生重大影響。
使用錯誤處理機制，可以減輕 API 傳回錯誤時對應用程式效能造成的影響。
確保應用程式能處理未選取任何項目的情況，以便使用者繼續操作。

費用最佳化最佳做法

基本費用最佳化

為了讓 Place Autocomplete (舊版) 服務費用發揮最大效益，請使用 Place Details (舊版) 和 Place Autocomplete (舊版) 小工具中的欄位遮罩，只傳回所需的 Place Autocomplete (舊版) 資料欄位。

進階費用最佳化

建議您透過程式輔助方式導入 Place Autocomplete (舊版)，採用 SKU：Autocomplete - Per Request 定價，並要求已選地點 (而非 Place Details (舊版)) 的相關 Geocoding API 結果。如果同時符合以下兩項條件，搭配 Geocoding API 使用「按要求」計價會比使用「按工作階段」(以工作階段為準) 計價更具成本效益：

如果您只需要針對使用者選取的地點取得經緯度或地址，透過 Geocoding API 擷取這項資訊，支付的費用會比使用 Place Details (舊版) 呼叫更低。
如果使用者在平均四次以內的 Place Autocomplete (舊版) 預測要求選取了自動預測結果，則「按要求」計價可能會比「按工作階段」計價更符合成本效益。

如要選擇最符合應用程式成本效益的 Place Autocomplete (舊版) 導入方式，請在下表中找出符合應用程式需求的資料列。

應用程式需求	使用者選取預測結果前，平均提出的 Place Autocomplete (舊版) 要求數量	建議實作方式
地址和位置以外的 Place Details，例如地點名稱、營業狀態或營業時間	不限人數	以工作階段為準的 Place Autocomplete (舊版) 搭配 Place Details (舊版)
僅限所選預測結果的地址和經緯度	四條以下	搭配 Geocoding API 使用 Place Autocomplete (舊版) (依要求計費)
僅限所選預測結果的地址和經緯度	超過四個	以工作階段為準的 Place Autocomplete (舊版)，適用於僅限地址的應用程式

對您的應用程式而言，Geocoding API 可能比 Place Details (舊版) 更符合成本效益，視 Place Autocomplete (舊版) 使用效能而定。每個應用程式的 Place Autocomplete (舊版) 效率各不相同，可能取決於使用者輸入的內容、使用應用程式的位置，以及是否採用效能最佳化最佳做法。

如要找出表格的平均要求數，請分析使用者在應用程式中選取 Place Autocomplete (舊版) 預測結果前，平均輸入的字元數量。

以工作階段為準的 Place Autocomplete (舊版) 搭配 Place Details (舊版)

搭配 Place Details (舊版) 使用以工作階段為準的 Place Autocomplete (舊版)。
由於您的應用程式需要 Place Details (舊版)，例如地點名稱、商家狀態或營業時間，因此在導入 Place Autocomplete (舊版) 時，應使用每個工作階段的工作階段符記 (透過程式輔助或內建於 JavaScript、Android 或 iOS 小工具)，以及適用的地點資料 SKU (視您要求的地點資料欄位而定)。¹

透過小工具導入
JavaScript、Android 或 iOS 小工具自動內建工作階段管理功能，其中包含對已選取的預測結果提出的 Place Autocomplete (舊版) 要求和 Place Details (舊版) 要求。請務必指定 fields 參數，確保只要求所需的 Place Autocomplete (舊版) 資料欄位。

透過程式輔助方式導入
搭配 Place Autocomplete (舊版) 要求使用工作階段符記。要求所選預測結果的相關 Place Details (舊版) 時，請加入下列參數：

Place Autocomplete (舊版) 回應中的地點 ID
Place Autocomplete (舊版) 要求中使用的工作階段符記
指定所需 Place Autocomplete (舊版) 資料欄位的 fields 參數

Place Autocomplete (舊版) 搭配 Geocoding API (按要求計費)

透過程式輔助方式導入 Place Autocomplete (舊版)，但不使用工作階段符記，並針對已選取的地點預測結果呼叫 Geocoding API。
Geocoding API 提供地址和經緯度座標。提出四次 Autocomplete - Per Request 要求，加上所選地點預測結果的相關 Geocoding API 呼叫，費用低於 Place Autocomplete (舊版) 的每個工作階段費用¹。

建議您採用效能最佳做法，讓使用者以更少的字元找到需要的預測結果。

以工作階段為準的 Place Autocomplete (舊版)，適用於僅限地址的應用程式

搭配 Place Details (舊版) 使用以工作階段為準的 Place Autocomplete (舊版)。
由於您預期在使用者選取 Place Autocomplete (舊版) 預測結果前，平均發出的要求數量超過按工作階段計價的費用，因此在導入 Place Autocomplete (舊版) 時，應針對 Place Autocomplete (舊版) 要求和相關聯的 Place Details (舊版) 要求，使用按工作階段計價的工作階段符記。 ¹

透過小工具導入
JavaScript、Android 或 iOS 小工具自動內建工作階段管理功能，其中包含對已選取的預測結果提出的 Place Autocomplete (舊版) 要求和 Place Details (舊版) 要求。請務必指定 fields 參數，確保只要求需要的欄位。

透過程式輔助方式導入
搭配 Place Autocomplete (舊版) 要求使用工作階段符記。要求所選預測結果的相關 Place Details (舊版) 時，請加入下列參數：

Place Autocomplete (舊版) 回應中的地點 ID
Place Autocomplete (舊版) 要求中使用的工作階段符記
指定地址和幾何圖形等 Basic Data 資料欄位的 fields 參數

考慮延後 Place Autocomplete (舊版) 要求
您可以運用一些策略，例如將 Place Autocomplete (舊版) 要求延後到使用者輸入三或四個字元時再開始，藉此減少應用程式提出要求數量。舉例來說，如果使用者輸入第三個字元後，系統針對每個字元提出 Place Autocomplete (舊版) 要求，則當使用者輸入七個字元，然後選取預測結果，您提出一項 Geocoding API 要求時，總費用會是 4 次 Place Autocomplete (舊版) 按要求計價 + 地理編碼。¹

如果延後要求可以讓平均程式輔助要求少於四次，您可以按照使用 Geocoding API 提高 Place Autocomplete (舊版) 效能的指南操作。請注意，如果使用者希望每輸入一個字就能看到預測結果，可能就會將延後要求視為時間上的延遲。

建議您採用效能最佳做法，讓使用者以更少的字元找到需要的預測結果。

如要瞭解費用，請參閱 Google 地圖平台價目表。

效能最佳做法

以下準則說明如何將 Place Autocomplete (舊版) 效能最佳化：

針對導入的 Place Autocomplete (舊版) 加入國家/地區限制、位置自訂調整和 (適用於程式輔助導入) 語言偏好設定。小工具會從使用者的瀏覽器或行動裝置選擇語言偏好設定，因此不需要設定語言偏好。
如果 Place Autocomplete (舊版) 附帶地圖，您就可以根據地圖可視區域進行位置自訂調整。
如果使用者沒有選擇任何 Place Autocomplete (舊版) 預測結果 (通常是因為這些預測結果並非他們想要的地址)，您可以重複使用原始使用者輸入內容，嘗試取得更相關的結果：
- 如果您預期使用者只會輸入地址資訊，請在 Geocoding API 呼叫中重複使用原始使用者輸入內容。
- 如果您預期使用者會依名稱或地址查詢某個地點，請使用 Place Details (舊版) 要求。如果希望將結果範圍限制在特定區域，請使用位置自訂調整。
適合改回使用 Geocoding API 的其他情況如下：
- 使用者輸入子處所地址，例如建築物內特定單位或公寓的地址。例如，捷克地址「Stroupežnického 3191/17, Praha」在 Place Autocomplete (舊版) 中會產生不完整的預測結果。
- 使用者輸入的地址含有路段前置字元，例如紐約的「23-30 29th St, Queens」或夏威夷考艾島的「47-380 Kamehameha Hwy, Kaneohe」。

位置偏誤

傳送 location 參數和 radius 參數，針對特定區域調整結果。這會指示 Place Autocomplete (舊版) 優先顯示指定區域內的結果。不過，系統還是有可能會顯示定義區域外的結果。您可以使用 includedRegionCodes 參數篩選結果，只顯示指定國家/地區內的地點。

警告：如未提供 radius，系統會忽略 location 參數。

搜尋區域較大時，商家結果的排名通常不夠高，無法顯示在結果中。如果希望商家出現在混合商家/地理編碼結果中，可以指定較小的半徑。或者，您也可以使用 types=establishment，將結果限制為僅限商家。

位置限制

傳送 locationRestriction 參數，將結果限制在指定區域。

您也可以加入 strictbounds 參數，將結果限制在 location 和 radius 參數定義的區域內。這會指示 Place Autocomplete (舊版)「只」傳回該區域內的結果。

Place Autocomplete (舊版) 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

Place Autocomplete (舊版) 要求

必要參數

輸入

選用參數

元件

language

位置

locationbias

locationrestriction

碳補償

origin

半徑

區域

sessiontoken

strictbounds

類型

Place Autocomplete (舊版) 範例

網址

curl

網址

curl

網址

curl

網址

curl

Place Autocomplete (舊版) 回應

網址

curl

JSON

XML

PlacesAutocompleteResponse

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

Place Autocomplete (舊版) 最佳化

費用最佳化最佳做法

基本費用最佳化

進階費用最佳化

以工作階段為準的 Place Autocomplete (舊版) 搭配 Place Details (舊版)

Place Autocomplete (舊版) 搭配 Geocoding API (按要求計費)

以工作階段為準的 Place Autocomplete (舊版)，適用於僅限地址的應用程式

效能最佳做法

位置偏誤

位置限制

Place Autocomplete (舊版)

`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`