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

Place Autocomplete (舊版)

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

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

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

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

Place Autocomplete (舊版) 是一項 Web 服務，可根據 HTTP 要求傳回地點預測結果。要求會指定文字搜尋字串和選用的地理範圍。這項服務可為文字型地理搜尋提供自動完成功能，在使用者輸入內容時傳回地點 (例如商家、地址和搜尋點)。

Place Autocomplete (舊版) 要求

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

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

你必須正確設定加號代碼格式。也就是說，您必須將加號逸出為 %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` 包含明確位置 (例如「巴塞隆納的市場」)，系統可能會覆寫 `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 參數，針對特定圓形範圍調整結果。這樣就能指示地點介面集服務優先顯示該圓形範圍內的結果，不過系統還是有可能會顯示定義區域外的結果。

系統會根據搜尋類型和其他參數，自動將半徑限制在最大值內。
- 自動完成：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，但無法與表 1、2 或 3 中的任何其他類型，合併用於 Place Autocomplete 要求篩選器。

如有下列情況，要求就會遭拒，並顯示 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 (舊版) 回應

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

網址

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`	選用	陣列<字串>	如果服務傳回要求規格的額外資訊，回應物件中可能會有額外的 `info_messages` 欄位。只有在要求成功時，系統才會傳回這個欄位。這項屬性不一定會傳回，且內容可能會變更。

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

XML 回應包含單一 <AutocompletionResponse> 元素，以及兩種子元素：

單一 <status> 元素包含要求的相關中繼資料。請參閱下方的「狀態碼」一節。
零或多個 <prediction> 元素，每個元素都包含單一地點的資訊。如要瞭解這些結果，請參閱「Place Autocomplete (Legacy) Results」。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，表示下列任一情況：
- 您已超過每秒查詢次數限制。
- 您的帳戶尚未啟用帳單功能。
- 超過每月 $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	字串	字詞的文字。

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 (舊版)，採用按請求計價的 Autocomplete SKU，並要求已選地點 (而非 Place Details (舊版)) 的相關 Geocoding API 結果。如果同時符合以下兩項條件，搭配 Geocoding API 使用「按要求」計價會比使用「按工作階段」(以工作階段為準) 計價更具成本效益：

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

如要瞭解如何選取符合需求的 Place Autocomplete (舊版) 導入方式，請回答下列問題，並選取對應的分頁標籤。

除了所選預測結果的地址和經緯度，應用程式是否需要任何其他資訊？

是，需要更多詳細資料

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

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

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

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

否，只需要地址和位置資訊

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

為了找出以下問題的解答，請分析使用者在應用程式中選取 Place Autocomplete (舊版) 預測結果前，平均輸入的字元數量。

使用者是否會在平均四次以內的要求中選取 Place Autocomplete (舊版) 預測結果？

是

透過程式輔助方式導入 Place Autocomplete (舊版)，但不使用工作階段符記，並針對已選取的地點預測結果呼叫 Geocoding API。
Geocoding API 提供地址和經緯度座標。提出四次自動完成 - 按要求計價要求，加上所選地點預測結果的相關 Geocoding API 呼叫，總費用會低於 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 (舊版) Per Request + Geocoding。¹

如果延後要求可以讓平均程式輔助要求少於四次，您可以按照使用 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 (舊版)

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