簡介
Autocomplete (新版) 是一項網路服務，可根據 HTTP 要求傳回地點預測和查詢預測結果。在要求中，指定 Text Search 字串和控制搜尋區域的地理邊界。
Autocomplete (新版) 可比對輸入內容的完整字詞和子字串，解析地點名稱、地址和 Plus Code。因此，應用程式可在使用者輸入內容時傳送查詢，即時提供地點和查詢預測結果。
Autocomplete (新版) 的回應可能包含兩種類型的預測結果：
- 地點預測：根據指定的輸入文字字串和搜尋區域，預測商家、地址和搜尋點等地點。根據預設，系統會傳回地點預測結果。
- 查詢預測：與輸入文字字串和搜尋區域相符的查詢字串。根據預設，系統不會傳回查詢預測。使用
includeQueryPredictions要求參數，在回應中加入查詢預測。
舉例來說，您呼叫 Autocomplete (新版) 時，輸入包含部分使用者輸入內容的字串「Sicilian piz」，並將搜尋區域限制在加州舊金山。接著，回應會包含與搜尋字串和搜尋區域相符的地點預測清單 (例如名為「Sicilian Pizza Kitchen」的餐廳)，以及該地點的詳細資料。
系統會向使用者顯示傳回的地點預測結果，協助他們選取所需地點。您可以提出 Place Details (新版) 要求，取得任何傳回地點預測結果的詳細資訊。
回應也可能包含與搜尋字串和搜尋區域相符的查詢預測清單，例如「Sicilian Pizza & Pasta」。回應中的每項查詢預測都包含 text 欄位，其中含有建議的 Text Search 字串。將該字串輸入 Text Search (新版)，即可執行更詳細的搜尋。
APIs Explorer 可讓您傳送即時要求，熟悉 API 和 API 選項：
Autocomplete (新版) 要求
Autocomplete (New) 要求是向網址發出的 HTTP POST 要求，格式如下：
https://places.googleapis.com/v1/places:autocomplete
在 JSON 要求主體或標頭中，傳遞所有參數做為 POST 要求的一部分。例如：
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 Code)。 |
|
|
以半形逗號分隔的清單，指定要在回應中傳回哪些欄位。 |
限制結果只顯示符合指定主要類型的地點 (最多五個)。 |
|
如果設為 true，則會納入沒有實體店面的商家 (無店面區域商家)。預設值為 false。 |
|
如果設為 true，回應會同時包含地點和查詢預測。預設值為 false。 |
|
最多 15 個雙字元國家/地區代碼的陣列，用於限制結果。 |
|
輸入字串中游標位置的 Unicode 字元偏移量 (從零開始)，會影響預測結果。預設為輸入長度。 |
|
搜尋結果的偏好語言 (IETF BCP-47 代碼)。預設值為 Accept-Language 標頭或「en」。 |
|
指定要優先顯示搜尋結果的區域 (圓形或矩形)，但允許顯示該區域外的結果。無法與 locationRestriction 搭配使用。 |
|
指定區域 (圓形或矩形)，將搜尋結果限制在該區域內。系統會排除這個區域以外的結果。 無法與 locationBias 搭配使用。 |
|
用於計算與預測目的地直線距離 (distanceMeters) 的起點 (緯度、經度)。 |
|
用於設定回應格式和偏好建議的區域代碼 (例如「uk」、「fr」)。 |
|
使用者產生的字串，用於將 Autocomplete 呼叫分組至工作階段，以便計費。 |
關於回覆
Autocomplete (新版) 會傳回 JSON 物件做為回應。在回應中：
suggestions陣列包含所有預測的地點和查詢，並依據感知關聯性排序。每個地點都以placePrediction欄位表示，每項查詢則以queryPrediction欄位表示。placePrediction欄位包含單一地點預測結果的詳細資訊，包括地點 ID 和文字說明。- 為了更貼近
input參數中提供的使用者輸入內容，地點預測結果的文字說明可能包含地點、街道和其他地址元件的替代名稱。這些替代名稱可能與相同地點 ID 的 Place Details 結果中，displayName和地址欄位傳回的名稱不同。 - 在這種情況下，某些地點的替代名稱可能會與
languageCode參數預期的語言不同，具體取決於哪些名稱與使用者輸入內容更相符。
- 為了更貼近
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: *
includeFutureOpeningBusinesses
如果為 true，則傳回預計在未來開業的商家。預設為 false。
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 修正拼字錯誤的能力。
-
地點預測結果的格式會因每項要求中的使用者輸入內容而異。
-
系統會先選擇
input參數中的相符字詞，並盡可能使用與languageCode參數指定的語言偏好設定一致的名稱，否則會使用與使用者輸入內容最相符的名稱。 -
地點名稱可能會使用替代名稱，以符合
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 錯誤。這項參數可能會根據適用法律影響結果。
設定 regionCode 後，該區域內的預測結果可能會省略建議文字中的國家/地區名稱，也就是說，structuredFormat.secondaryText 可能不會出現。因此，請確保應用程式會處理 secondaryText 未定義或遺漏的情況。
sessionToken
工作階段符記是使用者產生的字串，可將 Autocomplete (New) 呼叫追蹤為「工作階段」。Autocomplete (新版) 會使用工作階段符記，將使用者自動完成搜尋的查詢和選取階段歸入不同的工作階段，以用於計費。詳情請參閱「工作階段符記」。
選擇參數來調整結果
Autocomplete (New) 參數對搜尋結果的影響不盡相同。下表根據預期結果提供參數使用建議。| 參數 | 使用建議 |
|---|---|
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)。地點必須符合其中一個指定的主要類型值，才會納入回應。
在以下範例中，您將 input 字串指定為「Soccer」，並使用 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 (新版) 要求，取得傳回的查詢預測結果詳細資訊。
使用來源
在這個範例中，請在要求中加入 origin 做為經緯度座標。如果加入 origin，Autocomplete (新版) 會在回應中加入 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 } } ] }
尋找日後營業的商家
以下範例顯示 Autocomplete (新版) 要求，查詢愛達荷州新梅多斯未來即將開幕的商家：
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
"input": "Roberts Greenhouse and Tree Farm",
"includeFutureOpeningBusinesses": true,
"locationBias": {
"circle": {
"center": {"latitude": 44.9755100, "longitude": -116.2842180},
"radius": 20
}
}
}' \
"https://places.googleapis.com/v1/places:autocomplete"
回覆包含該地點的詳細資料，但不含開幕日期。
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJp1-VoKWJplQRMz8g-7Wa3Do", "placeId": "ChIJp1-VoKWJplQRMz8g-7Wa3Do", "text": { "text": "Roberts Greenhouse and Tree Farm, McLain Street, New Meadows, ID, USA", "matches": [ { "endOffset": 32 } ] }, "structuredFormat": { "mainText": { "text": "Roberts Greenhouse and Tree Farm", "matches": [ { "endOffset": 32 } ] }, "secondaryText": { "text": "McLain Street, New Meadows, ID, USA" } }, "types": [ "garden_center", "establishment", "service", "store", "point_of_interest" ] } } ] }
回應中缺少距離
在某些情況下，即使要求中包含 origin，回應主體中仍會缺少 distanceMeters。這可能發生在以下情況：
distanceMeters不會用於route預測。- 如果
distanceMeters的值為0，則不會包含該值，這適用於與提供的origin位置相距不到 1 公尺的預測結果。
如果用戶端程式庫嘗試從剖析物件中讀取 distanceMeters 欄位，則會傳回值為 0 的欄位。為避免誤導使用者，請不要向使用者顯示零距離。
Autocomplete (新版) 最佳化
本節將說明最佳做法，協助您充分運用 Autocomplete (New) 服務。
以下列出幾項一般準則：
- 如要開發有效的使用者介面，最快的方法就是使用 Maps JavaScript API Autocomplete (新版) 小工具、Places SDK for Android Autocomplete (新版) 小工具，或 Places SDK for iOS Autocomplete (新版) 小工具。
- 從一開始就嘗試瞭解 Autocomplete (新版) 的必要資料欄位。
- 「位置自訂調整」和「位置限制」為自選欄位，但可能會對自動完成效能產生重大影響。
- 使用錯誤處理機制，可以減輕 API 傳回錯誤時對應用程式效能造成的影響。
- 確保應用程式能處理未選取任何項目的情況，以便使用者繼續操作。
費用最佳化最佳做法
基本費用最佳化
為了讓 Autocomplete (新版) 服務費用發揮最大效益，請使用 Place Details (新版) 和 Autocomplete (新版) 小工具中的欄位遮罩，只傳回所需的 Autocomplete (新版) 資料欄位。
進階費用最佳化
建議您透過程式輔助方式導入 Autocomplete (新版)，採用 SKU：Autocomplete Request 定價，並要求已選地點 (而非 Place Details (新版)) 的相關 Geocoding API 結果。如果同時符合以下兩項條件，搭配 Geocoding API 使用「按要求」計價會比使用「按工作階段」(以工作階段為準) 計價更具成本效益：
- 如果您只需要針對使用者選取的地點取得經緯度或地址，透過 Geocoding API 擷取這項資訊，支付的費用會比使用 Place Details (New) 呼叫更低。
- 如果使用者在平均四次以內的 Autocomplete (New) 預測結果要求選取了自動預測結果，則「按要求」計價可能會比「按工作階段」計價更符合成本效益。
| 應用程式需求 | 使用者選取預測結果前，平均發出的 Autocomplete (新版) 要求數 | 建議實作方式 |
|---|---|---|
| 地址和位置以外的 Place Details，例如地點名稱、營業狀態或營業時間 | 不限人數 | 以工作階段為準的 Autocomplete (新版) 搭配 Place Details (新版) |
| 僅限所選預測結果的地址和經緯度 | 四條以下 | 搭配 Geocoding API 使用 Autocomplete (New) (依要求計費) |
| 僅限所選預測結果的地址和經緯度 | 超過四個 | 僅限地址的應用程式，使用以工作階段為準的 Autocomplete (新版) |
對您的應用程式而言，Geocoding API 可能比 Place Details (新版) 更符合成本效益，視 Autocomplete (新版) 使用效能而定。每個應用程式的 Autocomplete (New) 效率各不相同，可能取決於使用者輸入的內容、使用應用程式的位置，以及是否採用效能最佳化最佳做法。
如要找出表格的平均要求數，請分析使用者在應用程式中選取 Autocomplete (新版) 預測結果前，平均輸入的字元數量。
以工作階段為準的 Autocomplete (新版) 搭配 Place Details (新版)
搭配 Place Details (新版) 使用以工作階段為準的 Autocomplete (新版)。
由於應用程式需要 Place Details (新版) 資訊 (例如地點名稱、商家狀態或營業時間)，因此 Autocomplete (新版) 實作項目應使用工作階段符記 (透過程式輔助或內建於 JavaScript、Android 或 iOS 小工具)，並依據您要求的地點資料欄位，按工作階段和適用的 Places SKU 付費1。
透過小工具導入
JavaScript、Android 或 iOS 小工具自動內建工作階段管理功能，其中包含對已選取的預測結果提出的 Autocomplete (新版) 要求和 Place Details (新版) 要求。請務必指定 fields 參數，確保只要求所需的 Autocomplete (新版) 資料欄位。
透過程式輔助方式導入
搭配 Autocomplete (新版) 要求使用工作階段符記。要求所選預測結果的相關 Place Details (新版) 時，請加入下列參數：
- Autocomplete (新版) 回應中的地點 ID
- Autocomplete (新版) 要求中使用的工作階段符記
- 指定所需 Autocomplete (新版) 資料欄位的
fields參數
搭配 Geocoding API 使用 Autocomplete (New) (依要求計費)
透過程式輔助方式導入 Autocomplete (新版)，但不使用工作階段符記，並針對已選取的地點預測結果呼叫 Geocoding API。
Geocoding API 提供地址和經緯度座標。
提出四次自動完成要求，加上所選地點預測結果的相關 Geocoding API 呼叫，費用低於自動完成 (新版) 的單次工作階段費用1。
建議您採用效能最佳做法，讓使用者以更少的字元找到需要的預測結果。
僅限地址的應用程式使用以工作階段為準的 Autocomplete (新版)
搭配 Place Details (新版) 使用以工作階段為準的 Autocomplete (新版)。
在使用者選取 Autocomplete (新版) 預測結果前，您預期提出的平均要求數超過按工作階段計價的費用，因此 Autocomplete (新版) 導入作業應針對 Autocomplete (新版) 要求和相關聯的 Place Details (新版) 要求，使用按工作階段的工作階段符記。
1
透過小工具導入
JavaScript、Android 或 iOS 小工具自動內建工作階段管理功能，其中包含對已選取的預測結果提出的 Autocomplete (新版) 要求和 Place Details (新版) 要求。請務必指定 fields 參數，確保只要求需要的欄位。
透過程式輔助方式導入
搭配 Autocomplete (新版) 要求使用工作階段符記。
要求所選預測結果的 Place Details (新版) 時，請加入下列參數：
- Autocomplete (新版) 回應中的地點 ID
- Autocomplete (新版) 要求中使用的工作階段符記
- 指定地址和幾何圖形等欄位的
fields參數
考慮延後 Autocomplete (New) 要求
您可以運用一些策略，例如將 Autocomplete (New) 要求延後到使用者輸入三或四個字元時再開始，藉此減少應用程式提出要求數量。舉例來說，如果使用者輸入第三個字元後，系統才開始針對每個字元提出 Autocomplete (New) 要求，那麼當使用者輸入七個字元，然後選取預測結果，您提出一項 Geocoding API 要求時，總費用就會是 4 次 Autocomplete (New) Per Request + Geocoding 的費用1。
如果延後要求可以讓平均程式輔助要求少於四次，您可以按照使用 Geocoding API 提高 Autocomplete (新版) 效能的指南操作。請注意，如果使用者希望每輸入一個字就能看到預測結果，可能就會將延後要求視為時間上的延遲。
建議您採用效能最佳做法，讓使用者以更少的字元找到需要的預測結果。
-
如要瞭解費用，請參閱 Google 地圖平台價目表。
效能最佳做法
以下準則說明如何將 Autocomplete (新版) 效能最佳化：
- 針對導入的 Autocomplete (新版) 加入國家/地區限制、位置自訂調整和 (適用於程式輔助導入) 語言偏好設定。小工具會從使用者的瀏覽器或行動裝置選擇語言偏好設定，因此不需要設定語言偏好。
- 如果 Autocomplete (新版) 附帶地圖，您就可以根據地圖可視區域進行位置自訂調整。
- 如果使用者沒有選擇任何自動完成 (新版) 預測結果 (通常是因為這些預測結果並非他們想要的地址)，您可以重複使用原始使用者輸入內容，嘗試取得更相關的結果：
- 如果您預期使用者只會輸入地址資訊，請在 Geocoding API 呼叫中重複使用原始使用者輸入內容。
- 如果您預期使用者會依名稱或地址查詢某個地點，請使用 Place Details (新版) 要求。如果希望將結果範圍限制在特定區域，請使用位置自訂調整。
- 使用者輸入子處所地址，例如建築物內特定單位或公寓的地址。例如，捷克地址「Stroupežnického 3191/17, Praha」在 Autocomplete (新版) 中會產生不完整的預測結果。
- 使用者輸入的地址含有路段前置字元，例如紐約的「23-30 29th St, Queens」或夏威夷考艾島的「47-380 Kamehameha Hwy, Kaneohe」。
位置偏誤
傳送 location 參數和 radius 參數，針對特定區域調整結果。這會指示 Autocomplete (新版) 優先顯示指定區域內的結果。不過，系統還是有可能會顯示定義區域外的結果。您可以使用 includedRegionCodes 參數篩選結果，只顯示指定國家/地區內的地點。
位置限制
傳送 locationRestriction 參數，將結果限制在指定區域。
您也可以加入 locationRestriction 參數，將結果限制在 location 和 radius 參數定義的區域內。這會指示 Autocomplete (新版)「只」傳回該區域內的結果。
試試看！
APIs Explorer 可讓您提出範例要求，熟悉 API 和 API 選項。
選取頁面右側的 API 圖示 api。
視需要編輯要求參數。
選取「Execute」按鈕。在對話方塊中，選擇要用來提出要求的帳戶。
在 APIs Explorer 面板中，選取全螢幕圖示 fullscreen，展開 APIs Explorer 視窗。