簡介
Autocomplete (新版) 是一項網路服務，可根據 HTTP 要求傳回地點預測和查詢預測結果。在要求中，指定文字搜尋字串和地理範圍，以控管搜尋區域。
「自動完成 (新版)」可比對輸入內容的完整字詞和子字串，解析地點名稱、地址和 Plus Codes。因此，應用程式可在使用者輸入內容時傳送查詢，即時提供地點和查詢預測結果。
Autocomplete (新版) 的回應可能包含兩種預測結果：
- 地點預測：根據指定的輸入文字字串和搜尋區域，預測地點 (例如商家、地址和搜尋點)。系統預設會傳回地點預測結果。
- 查詢預測：符合輸入文字字串和搜尋區域的查詢字串。系統預設不會傳回查詢預測。使用
includeQueryPredictions要求參數，在回應中加入查詢預測。
舉例來說，您可以使用含有部分使用者輸入內容的字串「Sicilian piz」，並將搜尋範圍限制在加州舊金山，藉此呼叫 Autocomplete (New)。接著，回應會包含符合搜尋字串和搜尋區域的地點預測清單，例如名為「Sicilian Pizza Kitchen」的餐廳，以及該地點的詳細資料。
傳回的地點預測結果會顯示給使用者，協助他們選取所需地點。您可以提出 Place Details (New) 要求，取得任何傳回地點預測結果的詳細資訊。
回應也可能包含符合搜尋字串和搜尋區域的查詢預測清單，例如「西西里披薩和義大利麵」。回應中的每個查詢預測結果都包含 text 欄位，內含建議的文字搜尋字串。將該字串做為 Text Search (新版) 的輸入內容，執行更詳細的搜尋。
您可以使用 APIs Explorer 傳送即時要求，熟悉 API 和 API 選項：
自動完成 (新版) 要求
自動完成 (新版) 要求是傳送至以下格式網址的 HTTP POST 要求：
https://places.googleapis.com/v1/places:autocomplete
在 POST 要求中，將所有參數傳遞至 JSON 要求內文或標頭。例如：
curl -X POST -d '{
"input": "pizza",
"locationBias": {
"circle": {
"center": {
"latitude": 37.7937,
"longitude": -122.3965
},
"radius": 500.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
支援的參數
參數 |
說明 |
|---|---|
要搜尋的文字字串 (完整字詞、子字串、地點名稱、地址、Plus Codes)。 |
|
|
以半形逗號分隔的清單，指定要在回應中傳回的欄位。 |
限制結果只顯示符合最多五個指定主要類型的地點。 |
|
如果為 true，則包含沒有實體店面的商家 (區域服務商家)。預設值為 false。 |
|
如果設為 true，回應中會同時包含地點和查詢預測。預設值為 false。 |
|
最多 15 個雙字元國家/地區代碼的陣列，用於限制結果。 |
|
游標在輸入字串中的位置 (從零算起)，會影響預測結果。預設為輸入長度。 |
|
搜尋結果的偏好語言 (IETF BCP-47 代碼)。 預設值為 Accept-Language 標頭或「en」。 |
|
指定要優先顯示搜尋結果的區域 (圓形或矩形)，允許顯示區域外的結果。無法與 locationRestriction 搭配使用。 |
|
指定要限制搜尋結果的區域 (圓形或矩形)。系統會排除這個區域外的結果。 無法與 locationBias 搭配使用。 |
|
用來計算預測目的地直線距離 (distanceMeters) 的原點 (緯度、經度)。 |
|
用於格式化回應和偏誤建議的區域代碼 (例如 「uk」、「fr」)。 |
|
使用者產生的字串，可將 Autocomplete 呼叫歸入工作階段，以用於計費。 |
關於回覆
自動完成 (新版) 會以 JSON 物件的形式傳回回應。在回覆中：
suggestions陣列包含所有預測的地點和查詢，並根據感知關聯性排序。每個地點都以placePrediction欄位表示，每個查詢則以queryPrediction欄位表示。placePrediction欄位包含單一地點預測的詳細資訊，包括地點 ID 和文字說明。queryPrediction欄位包含單一查詢預測的詳細資訊。
完整的 JSON 物件格式如下：
{
"suggestions": [
{
"placePrediction": {
"place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
"placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
"text": {
"text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
"matches": [
{
"endOffset": 6
}]
},
...
},
{
"queryPrediction": {
"text": {
"text": "Amoeba Music",
"matches": [
{
"endOffset": 6
}]
},
...
}
...]
}必要參數
-
輸入
要搜尋的文字字串。指定完整字詞和子字串、地點名稱、地址和 Plus Codes。Autocomplete (New) 服務會根據這個字串傳回候選相符項目，並會依據觀察到的關聯性排序結果。
選用參數
-
FieldMask
建立回應欄位遮罩，指定要在回應中傳回的欄位清單。使用 HTTP 標頭
X-Goog-FieldMask，將回應欄位遮罩傳遞至方法。指定要傳回的建議欄位清單 (以半形逗號分隔)。舉例來說，如要擷取建議的
suggestions.placePrediction.text.text和suggestions.queryPrediction.text.text。X-Goog-FieldMask: suggestions.placePrediction.text.text,suggestions.queryPrediction.text.text
使用
*擷取所有欄位。X-Goog-FieldMask: *
-
includedPrimaryTypes
地點只能有一個主要類型，且必須是表 A 或表 B 中列出的類型。舉例來說，主要類型可能是
"mexican_restaurant"或"steak_house"。根據預設，API 會根據
input參數傳回所有地點，無論與地點相關聯的主要類型值為何。傳遞includedPrimaryTypes參數，將結果限制為特定主要類型或主要類型。使用這個參數，從表 A 或表 B 指定最多五個類型值。地點必須符合其中一個指定的主要類型值，才會納入回應。
這個參數也可以改為包含
(regions)或(cities)。(regions)類型集合會篩選區域或分區，例如社區和郵遞區號。(cities)類型集合會篩選出 Google 判斷為城市的地點。如有下列情況，要求就會遭拒，並傳回
INVALID_REQUEST錯誤：- 指定超過五個類型。
- 除了
(cities)或(regions)之外，還指定了任何型別。 - 指定任何無法辨識的類型。
-
includePureServiceAreaBusinesses
如果設為
true，回應會包含直接為顧客提供送貨或到府服務，但沒有實體店面的商家。如果設為false，API 只會傳回有實體營業場所的商家。 -
includeQueryPredictions
如果為
true，回應會同時包含地點和查詢預測。預設值為false，表示回應只會包含地點預測。 -
includedRegionCodes
只納入指定區域清單中的結果，指定方式為最多 15 個國家/地區代碼頂層網域 (ccTLD) 的兩位字元值陣列。如果省略，系統不會對回覆套用任何限制。舉例來說，如要將地區限制為德國和法國，請執行下列操作：
"includedRegionCodes": ["de", "fr"]
如果同時指定
locationRestriction和includedRegionCodes，結果會位於這兩項設定的交集區域。 -
inputOffset
以零為基準的 Unicode 字元位移值，表示
input中的游標位置。 游標位置可能會影響系統傳回的預測結果。如果為空白，預設值為input的長度。 -
languageCode
傳回結果時偏好的語言。如果
input中使用的語言與languageCode指定的值不同，或傳回的地點沒有從當地語言到languageCode的翻譯，結果可能會以混合語言顯示。- 您必須使用 IETF BCP-47 語言代碼指定偏好的語言。
-
如未提供
languageCode，API 會使用Accept-Language標頭中指定的值。如未指定，則預設值為en。如果指定無效的語言代碼，API 會傳回INVALID_ARGUMENT錯誤。 - 偏好語言對 API 選擇傳回的結果集和傳回順序影響不大。這也會影響 API 修正拼字錯誤的能力。
-
API 會嘗試提供使用者和當地居民都能解讀的街道地址，同時反映使用者輸入內容。地點預測的格式會因每個要求中的使用者輸入內容而異。
-
系統會先選擇
input參數中的相符字詞，並使用與languageCode參數所指出語言偏好設定一致的名稱 (如有)，否則會使用最符合使用者輸入內容的名稱。 -
如果可以，系統會以使用者可讀的文字，用當地語言格式化街道地址，但前提是已選取相符的字詞，與
input參數中的字詞相符。 -
選取與
input參數中的字詞相符的字詞後，系統會以偏好語言傳回所有其他地址。如果偏好語言沒有名稱，API 會使用最接近的名稱。
-
系統會先選擇
locationBias 或 locationRestriction
您可以指定
locationBias或locationRestriction(但不能同時指定兩者)，定義搜尋範圍。locationRestriction可視為指定結果必須位於的區域，而locationBias則可視為指定結果必須靠近的區域，但可位於該區域外。locationBias
指定要搜尋的區域。這個位置會做為偏誤，也就是說，系統可能會傳回指定位置附近的結果，包括指定區域外的結果。
locationRestriction
指定要搜尋的區域。系統不會傳回指定區域外的結果。
將
locationBias或locationRestriction區域指定為矩形檢視區塊或圓形。圓形是由中心點和半徑 (以公尺為單位) 定義。半徑必須介於 0.0 至 50000.0 之間 (含首尾)。預設值為 0.0。如果是
locationRestriction，半徑必須設為大於 0.0 的值。否則要求不會傳回任何結果。例如：
"locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
矩形是經緯度可視區域，以兩個對角相對的
low和高點表示。可視區域視為封閉區域，因此包含邊界。緯度範圍必須介於 -90 到 90 度之間 (含首尾)，經度範圍則必須介於 -180 到 180 度之間 (含首尾)：- 如果
low=high，可視區域就是該單一點。 - 如果
low.longitude>high.longitude，經度範圍會反轉 (可視區域會跨越 180 度經度線)。 - 如果
low.longitude= -180 度且high.longitude= 180 度，可視區域會包含所有經度。 - 如果
low.longitude= 180 度且high.longitude= -180 度，經度範圍會空白。
low和high都必須填入值，且代表的方塊不得為空。如果檢視區塊為空白，就會發生錯誤。舉例來說，這個可視區域完全涵蓋紐約市：
"locationBias": { "rectangle": { "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } } }
- 如果
-
origin
計算與目的地直線距離的起點 (以
distanceMeters形式傳回)。如果省略這個值，系統就不會傳回直線距離。必須指定為經緯度座標："origin": { "latitude": 40.477398, "longitude": -74.259087 }
-
regionCode
用來格式化回應的區域代碼，指定為 ccTLD (「頂層網域」) 的兩位字元值。大多數 ccTLD 代碼與 ISO 3166-1 代碼相同，但有一些需要注意的例外情況。舉例來說，英國的 ccTLD 是「uk」(即 .co.uk)，而 ISO 3166-1 代碼是「gb」(技術上是指「大不列顛及北愛爾蘭聯合王國」實體的代碼)。
建議也會根據區域代碼有所偏誤。Google 建議根據使用者的區域偏好設定
regionCode。如果指定無效的地區代碼，API 會傳回
INVALID_ARGUMENT錯誤。根據適用法律，這項參數可能會影響結果。 -
sessionToken
工作階段符記是使用者產生的字串，可將 Autocomplete (新版) 呼叫追蹤為「工作階段」。自動完成 (新版) 會使用工作階段符記，將使用者自動完成搜尋的查詢和選取階段歸入不同的工作階段，以用於計費。詳情請參閱「工作階段符記」。
選擇要影響結果的參數
自動完成 (新版) 參數可能會以不同方式影響搜尋結果。 下表根據預期結果，提供參數使用建議。| 參數 | 使用建議 |
|---|---|
regionCode |
根據使用者的地區偏好設定。 |
includedRegionCodes |
設為只顯示指定區域清單的結果。 |
locationBias |
如果希望結果位於特定區域內或附近，請使用這項功能。如適用，請將區域定義為使用者目前查看的地圖可視區域。 |
locationRestriction |
只有在不應傳回區域外的結果時，才使用 。 |
origin |
如果想計算每個預測結果的直線距離，請使用這項指標。 |
Autocomplete (新版) 範例
使用 locationRestriction 將搜尋範圍限制在特定區域
locationRestriction 會指定要搜尋的區域。系統不會傳回指定區域外的結果。在下列範例中，您可以使用 locationRestriction 將要求限制為以舊金山為中心，半徑 5000 公尺的圓形：
curl -X POST -d '{
"input": "Art museum",
"locationRestriction": {
"circle": {
"center": {
"latitude": 37.7749,
"longitude": -122.4194
},
"radius": 5000.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
指定區域內的所有結果都會包含在 suggestions 陣列中：
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q", "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q", "text": { "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "structuredFormat": { "mainText": { "text": "Asian Art Museum", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "secondaryText": { "text": "Larkin Street, San Francisco, CA, USA" } }, "types": [ "establishment", "museum", "point_of_interest" ] } }, { "placePrediction": { "place": "places/ChIJI7NivpmAhYARSuRPlbbn_2w", "placeId": "ChIJI7NivpmAhYARSuRPlbbn_2w", "text": { "text": "de Young Museum, Hagiwara Tea Garden Drive, San Francisco, CA, USA", "matches": [ { "endOffset": 15 } ] }, "structuredFormat": { "mainText": { "text": "de Young Museum", "matches": [ { "endOffset": 15 } ] }, "secondaryText": { "text": "Hagiwara Tea Garden Drive, San Francisco, CA, USA" } }, "types": [ "establishment", "point_of_interest", "tourist_attraction", "museum" ] } }, /.../ ] }
您也可以使用 locationRestriction，將搜尋範圍限制在矩形可視區域。下列範例會將要求限制在舊金山市區：
curl -X POST -d '{
"input": "Art museum",
"locationRestriction": {
"rectangle": {
"low": {
"latitude": 37.7751,
"longitude": -122.4219
},
"high": {
"latitude": 37.7955,
"longitude": -122.3937
}
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
結果會包含在 suggestions 陣列中：
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q", "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q", "text": { "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "structuredFormat": { "mainText": { "text": "Asian Art Museum", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "secondaryText": { "text": "Larkin Street, San Francisco, CA, USA" } }, "types": [ "point_of_interest", "museum", "establishment" ] } }, { "placePrediction": { "place": "places/ChIJyQNK-4SAhYARO2DZaJleWRc", "placeId": "ChIJyQNK-4SAhYARO2DZaJleWRc", "text": { "text": "International Art Museum of America, Market Street, San Francisco, CA, USA", "matches": [ { "startOffset": 14, "endOffset": 24 } ] }, "structuredFormat": { "mainText": { "text": "International Art Museum of America", "matches": [ { "startOffset": 14, "endOffset": 24 } ] }, "secondaryText": { "text": "Market Street, San Francisco, CA, USA" } }, "types": [ "museum", "point_of_interest", "tourist_attraction", "art_gallery", "establishment" ] } } ] }
使用 locationBias 將搜尋結果自訂調整為僅限某個區域
使用 locationBias 時，位置資訊會做為自訂調整，也就是說，系統可能會傳回指定位置附近的結果，包括指定區域外的結果。在下列範例中，您會將要求偏向舊金山市區：
curl -X POST -d '{
"input": "Amoeba",
"locationBias": {
"circle": {
"center": {
"latitude": 37.7749,
"longitude": -122.4194
},
"radius": 5000.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
現在的結果包含更多項目，包括 5000 公尺半徑以外的結果：
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "electronics_store", "point_of_interest", "store", "establishment", "home_goods_store" ] } }, { "placePrediction": { "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw", "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw", "text": { "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Telegraph Avenue, Berkeley, CA, USA" } }, "types": [ "electronics_store", "point_of_interest", "establishment", "home_goods_store", "store" ] } }, ... ] }
您也可以使用 locationBias，將搜尋結果偏向矩形檢視區塊。下列範例會將要求限制在舊金山市區：
curl -X POST -d '{
"input": "Amoeba",
"locationBias": {
"rectangle": {
"low": {
"latitude": 37.7751,
"longitude": -122.4219
},
"high": {
"latitude": 37.7955,
"longitude": -122.3937
}
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
雖然回應中會顯示矩形可視區域內的搜尋結果，但由於偏誤，部分結果會超出定義的邊界。結果也會包含在 suggestions 陣列中：
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "point_of_interest", "store", "establishment" ] } }, { "placePrediction": { "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw", "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw", "text": { "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Telegraph Avenue, Berkeley, CA, USA" } }, "types": [ "point_of_interest", "store", "establishment" ] } }, { "placePrediction": { "place": "places/ChIJRdmfADq_woARYaVhnfQSUTI", "placeId": "ChIJRdmfADq_woARYaVhnfQSUTI", "text": { "text": "Amoeba Music, Hollywood Boulevard, Los Angeles, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Hollywood Boulevard, Los Angeles, CA, USA" } }, "types": [ "point_of_interest", "store", "establishment" ] } }, /.../ ] }
使用 includedPrimaryTypes
使用 includedPrimaryTypes 參數，從表 A、表 B、(regions) 或 (cities) 指定最多五個類型值。地點必須符合其中一個指定的主要類型值，才會納入回應。
在下列範例中，您指定「Soccer」的 input 字串，並使用 includedPrimaryTypes 參數將結果限制為 "sporting_goods_store" 類型的場所：
curl -X POST -d '{
"input": "Soccer",
"includedPrimaryTypes": ["sporting_goods_store"],
"locationBias": {
"circle": {
"center": {
"latitude": 37.7749,
"longitude": -122.4194
},
"radius": 500.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
如果省略 includedPrimaryTypes 參數，結果可能會包含您不想要的類型的場所，例如 "athletic_field"。
要求查詢預測
系統預設不會傳回查詢預測。使用 includeQueryPredictions 要求參數，在回應中加入查詢預測。例如：
curl -X POST -d '{
"input": "Amoeba",
"includeQueryPredictions": true,
"locationBias": {
"circle": {
"center": {
"latitude": 37.7749,
"longitude": -122.4194
},
"radius": 5000.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
如「關於回應」一節所示，suggestions 陣列現在同時包含地點預測和查詢預測。每項查詢預測都包含 text 欄位，內含建議的文字搜尋字串。您可以提出 Text Search (New) 要求，進一步瞭解傳回的任何查詢預測。
使用來源
在本範例中，請在要求中加入 origin 做為經緯度座標。加入 origin 後，Autocomplete (New) 會在回應中加入 distanceMeters 欄位，其中包含從 origin 到目的地的直線距離。這個範例將原點設為舊金山中心：
curl -X POST -d '{
"input": "Amoeba",
"origin": {
"latitude": 37.7749,
"longitude": -122.4194
},
"locationRestriction": {
"circle": {
"center": {
"latitude": 37.7749,
"longitude": -122.4194
},
"radius": 5000.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
回應現在包含 distanceMeters：
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "home_goods_store", "establishment", "point_of_interest", "store", "electronics_store" ], "distanceMeters": 3012 } } ] }
回覆中缺少距離
在某些情況下，即使要求中包含 origin，回應主體仍會缺少 distanceMeters。可能發生這種情況的原因如下：
distanceMeters不會納入route預測。- 如果值為
0，系統就不會納入distanceMeters。如果預測位置與提供的origin位置相距不到 1 公尺，就會發生這種情況。
用戶端程式庫嘗試從剖析的物件讀取 distanceMeters 欄位時，會傳回值為 0 的欄位。為避免誤導使用者，請不要向使用者顯示零距離。
Autocomplete (新版) 最佳化
本節將說明最佳做法，協助您充分運用 Autocomplete (New) 服務。
以下列出幾項一般準則：
- 如要開發有效的使用者介面，最快的方法就是使用 Maps JavaScript API Autocomplete (New) 小工具、 Places SDK for Android Autocomplete (New) 小工具， 或 Places SDK for iOS Autocomplete (New) 小工具。
- 從一開始就瞭解 Autocomplete (新版) 的必要資料欄位。
- 「位置自訂調整」和「位置限制」為自選欄位，但可能會對自動完成效能產生重大影響。
- 使用錯誤處理機制，可以減輕 API 傳回錯誤時對應用程式效能造成的影響。
- 確保應用程式能處理未選取任何項目的情況，以便使用者繼續操作。
費用最佳化最佳做法
基本費用最佳化
為了讓 Autocomplete (New) 服務費用發揮最大效益，請使用 Place Details (New) 和 Autocomplete (New) 小工具中的欄位遮罩，只傳回所需的 Autocomplete (New) 資料欄位。
進階費用最佳化
建議您透過程式輔助方式導入 Autocomplete (New)，採用SKU：Autocomplete Request 計價，並要求已選地點 (而非 Place Details (New)) 的相關 Geocoding API 結果。如果同時符合以下兩項條件，搭配 Geocoding API 使用「按要求」計價會比使用「按工作階段」(以工作階段為準) 計價更具成本效益：
- 如果您只需要針對使用者選取的地點取得經緯度或地址，透過 Geocoding API 擷取這項資訊，支付的費用會比使用 Place Details (New) 呼叫更低。
- 如果使用者在平均四次以內的自動預測結果要求選取了自動預測結果，則「按要求」計價可能會比「按工作階段」計價更符合成本效益。
除了所選預測結果的地址和經緯度，應用程式是否需要任何其他資訊？
是，需要更多詳細資料
搭配 Place Details (新版) 使用以工作階段為準的 Autocomplete (新版)。
由於應用程式需要地點詳細資料 (新版)，例如地點名稱、商家狀態或營業時間，因此實作 Autocomplete (新版) 時，應使用JavaScript、Android 或 iOS 小工具中內建的每個工作階段工作階段符記，以及適用的 Places SKU，具體取決於您要求哪些地點資料欄位。1
透過小工具導入
JavaScript、Android 或 iOS 小工具自動內建工作階段管理功能，其中包含對已選取的預測結果提出的 Autocomplete (新版) 要求和 Place Details (新版) 要求。請務必指定 fields 參數，確保只要求所需的
Autocomplete (New) 資料欄位
。
透過程式輔助方式導入
搭配 Autocomplete (New) 要求使用工作階段符記。要求所選預測結果的相關 Place Details (新版) 時，請加入下列參數：
- Autocomplete (新版) 回應中的地點 ID
- Autocomplete (New) 要求中使用的工作階段符記
- 指定所需 Autocomplete (新版) 資料欄位的
fields參數
否，只需要地址和位置資訊
對您的應用程式而言，Geocoding API 可能比 Place Details (New) 更符合成本效益，視 Autocomplete (New) 使用效能而定。每個應用程式的自動完成 (新版) 效率各不相同，可能取決於使用者輸入的內容、使用應用程式的位置，以及是否採用效能最佳化最佳做法。
為了找出以下問題的解答，請分析使用者在應用程式中選取 Autocomplete (New) 預測結果前，平均輸入的字元數量。
使用者是否會在平均四次以內的要求中選取 Autocomplete (New) 預測結果？
是
透過程式輔助方式導入 Autocomplete (New)，但不使用工作階段符記，並針對已選取的地點預測結果呼叫 Geocoding API。
Geocoding API 提供地址和經緯度座標。
提出四次自動完成要求，加上所選地點預測結果的相關 Geocoding API 呼叫，總費用會低於自動完成 (新版) 功能「按工作階段」計價的每個工作階段費用1。
建議您採用效能最佳做法，讓使用者以更少的字元找到需要的預測結果。
否
搭配 Place Details (新版) 使用以工作階段為準的 Autocomplete (新版)。
由於您預期在使用者選取 Autocomplete (新版) 預測結果前，平均會發出超過「按工作階段」計價費用的要求，因此 Autocomplete (新版) 的實作應針對 Autocomplete (新版) 要求和相關聯的 Place Details (新版) 要求，使用按工作階段計價的工作階段符記。
1
透過小工具導入
JavaScript、Android 或 iOS 小工具自動內建工作階段管理功能，其中包含對已選取的預測結果提出的 Autocomplete (新版) 要求和 Place Details (新版) 要求。請務必指定 fields 參數，確保只要求所需的欄位。
透過程式輔助方式導入
搭配 Autocomplete (New) 要求使用工作階段符記。要求所選預測結果的相關 Place Details (新版) 時，請加入下列參數：
- Autocomplete (新版) 回應中的地點 ID
- Autocomplete (New) 要求中使用的工作階段符記
- 指定地址和幾何圖形等欄位的
fields參數
考慮延後 Autocomplete (New) 要求
您可以運用一些策略，例如將 Autocomplete (New) 要求延後到使用者輸入三或四個字元時再開始，藉此減少應用程式提出要求數量。舉例來說，如果使用者輸入第三個字元後，您為每個字元提出自動完成 (新版) 要求，則使用者輸入七個字元並選取預測結果後，您提出一次 Geocoding API 要求，總費用會是 4 次自動完成 (新版) 要求 + Geocoding。1
如果延後要求可以讓平均程式輔助要求少於四次，您可以按照使用 Geocoding API 提高 Autocomplete (New) 效能的指南操作。請注意，如果使用者希望每輸入一個字就能看到預測結果，可能就會將延後要求視為時間上的延遲。
建議您採用效能最佳做法，讓使用者以更少的字元找到需要的預測結果。
-
如要瞭解費用，請參閱 Google 地圖平台價目表。
效能最佳做法
以下準則說明如何將 Autocomplete (新版) 效能最佳化：
- 針對導入的 Autocomplete (New) 加入國家/地區限制、位置自訂調整和 (適用於程式輔助導入) 語言偏好設定。小工具會從使用者的瀏覽器或行動裝置選擇語言偏好設定，因此不需要設定語言偏好。
- 如果 Autocomplete (New) 附帶地圖，您就可以根據地圖可視區域進行位置自訂調整。
- 如果使用者沒有選擇任何自動完成 (新版) 預測結果 (通常是因為這些預測結果並非他們想要的地址)，您可以重複使用原始使用者輸入內容，嘗試取得更相關的結果：
- 如果您預期使用者只會輸入地址資訊，請在 Geocoding API 呼叫中重複使用原始使用者輸入內容。
- 如果您預期使用者會依名稱或地址查詢某個地點，請使用 Place Details (New) 要求。如果希望將結果範圍限制在特定區域，請使用位置自訂調整。
- 使用者輸入子處所地址，例如建築物內特定單位或公寓的地址。例如，捷克地址「Stroupežnického 3191/17, Praha」在 Autocomplete (新版) 中會產生不完整的預測結果。
- 使用者輸入的地址含有路段前置字元，例如紐約的「23-30 29th St, Queens」或夏威夷考艾島的「47-380 Kamehameha Hwy, Kaneohe」。
位置偏誤
傳遞 location 參數和 radius 參數，針對特定區域調整結果。這會指示 Autocomplete (New) 優先顯示定義區域內的結果。不過，系統還是有可能會顯示定義區域外的結果。您可以使用 components 參數篩選結果，只顯示特定國家/地區內的地點。
限制位置
傳送 locationRestriction 參數，將結果限制在特定區域。
您也可以新增 locationRestriction 參數，將結果限制在 location 和 radius 參數定義的區域內。這會指示 Autocomplete (New) 只傳回該區域內的結果。
試試看！
您可以使用 APIs Explorer 提出範例要求，熟悉 API 和 API 選項。
選取頁面右側的 API 圖示 api。
視需要編輯要求參數。
選取「Execute」按鈕。在對話方塊中，選擇要用來提出要求的帳戶。
在 APIs Explorer 面板中，選取全螢幕圖示 fullscreen 即可展開 APIs Explorer 視窗。