Autocomplete (新版) 服務是一種網路服務,可依據 HTTP 要求傳回地點預測和查詢預測結果。在要求中,指定用來控制搜尋區域的文字搜尋字串和地理邊界。
自動完成 (新版) 服務可比對輸入內容的完整字詞和子字串,解析地點名稱、地址和 Plus Codes。因此,應用程式可在使用者輸入內容時傳送查詢,即時提供地點和查詢預測結果。
Autocomplete (New) API 的回應可包含兩種預測結果:
- 地點預測:地點 (例如商家、地址和搜尋點),根據指定的輸入文字字串和搜尋區域。根據預設,系統會傳回地點預測結果。
- 查詢預測:符合輸入文字字串和搜尋區域的查詢字串。根據預設,系統不會傳回查詢預測。使用
includeQueryPredictions
要求參數,將查詢預測新增至回應。
舉例來說,您可以使用做為輸入字串來呼叫 API,該字串內含部分的使用者輸入內容「Sicilian piz」,且搜尋區域僅限於加州舊金山。回應隨後會包含一份與搜尋字串和搜尋區域相符的地點預測結果清單 (例如名為「西西里披薩廚房」的餐廳),以及該地點的詳細資料。
傳回的地點預測結果旨在協助使用者選取所需地點。您可以提出 Place Details (新版) 要求,取得任何傳回地點預測結果的詳細資訊。
回應也可以包含與搜尋字串和搜尋區域相符的查詢預測清單,例如「Sicilian Pizza & Pasta」。回應中的每項查詢預測結果都會包含 text
欄位,其中包含建議的文字搜尋字串。使用該字串做為 Text Search (New) 的輸入內容,執行更詳細的搜尋作業。
API Explorer 可讓您發出即時要求,以便熟悉這個 API 和 API 選項:
試試看!自動完成 (新版) 要求
Autocomplete (新版) 要求是對網址的 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
關於回覆
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 (新版) 服務會根據這個字串傳回候選相符項目,並會依據觀察到的關聯性排序結果。
自選參數
-
includedPrimaryTypes
一個地點只能從表 A 或表 B 所列的類型中擁有單一主要類型。舉例來說,主要類型可能是
"mexican_restaurant"
或"steak_house"
。根據預設,API 會根據
input
參數傳回所有地點,無論地點的主要類型值為何。傳遞includedPrimaryTypes
參數,將結果限制為特定主要類型或主要類型。使用這個參數從表 A 或表 B 指定最多五個類型值。地點必須符合其中一個指定的主要類型值,才能納入回應。
這個參數也可能包括
(regions)
或(cities)
其中之一。區域或部門 (例如社區和郵遞區號) 的(regions)
類型集合篩選器。(cities)
類型集合篩選器可用於篩選 Google 識別為城市的地點。如有下列情況,要求遭到拒絕,並顯示
INVALID_REQUEST
錯誤:- 指定超過五個類型。
- 除了
(cities)
或(regions)
以外,還指定任何類型。 - 指定了任何無法辨識的類型。
-
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 } } }
- 如果
-
發跡地
計算與目的地之間的直線距離的起點 (傳回
distanceMeters
)。如果省略這個值,系統就不會傳回直線距離。必須以經緯度座標指定:"origin": { "latitude": 40.477398, "longitude": -74.259087 }
-
regionCode
用於設定回應格式的區碼,以 ccTLD (「頂層網域」) 的兩位字元值指定。大多數 ccTLD 代碼與 ISO 3166-1 代碼相同,只有少數例外。舉例來說,英國的 ccTLD 是「uk」(.co.uk),而其 ISO 3166-1 代碼卻是「gb」(正式的國名是「大不列顛暨北愛爾蘭聯合王國」)。
如果指定的區碼無效,API 會傳回
INVALID_ARGUMENT
錯誤。這個參數會根據適用法律影響結果。 -
sessionToken
工作階段符記是使用者產生的字串,可將 Autocomplete (新) 呼叫視為「工作階段」來追蹤。Autocomplete (新版) 會使用工作階段符記,將使用者自動完成搜尋的查詢和選取階段歸入不同的工作階段,以用於計費。詳情請參閱工作階段符記。
自動完成 (新版) 範例
使用 locationRestriction 和 locationBias
根據預設,API 會使用 IP 自訂調整來控制搜尋區域。透過 IP 自訂調整,API 會使用裝置的 IP 位址來自訂調整結果。您可以選擇使用 locationRestriction
或 locationBias
,但不能同時使用兩者,指定要搜尋的區域。
locationRestriction
會指定要搜尋的區域。但不會傳回指定區域以外的結果。在以下範例中,您會使用 locationRestriction
將要求限制為以舊金山為中心、半徑為 5000 公尺的圓形:
curl -X POST -d '{ "input": "Amoeba", "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/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", "store", "point_of_interest", "electronics_store" ] } } ] }
使用 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" ] } }, ... ] }
使用 includePrimaryTypes
使用 includedPrimaryTypes
參數可指定最多五個類型值,來源為表 A、表 B、只指定 (regions)
,或只指定 (cities)
。地點必須符合其中一個指定的主要類型值,才能納入回應。
在以下範例中,您會指定「足球」的 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 (新版) 要求以取得任何傳回查詢預測的詳細資訊。
使用來源
在這個範例中,請將 origin
做為經緯度座標在要求中加入。加入 origin
後,API 會在回應中加入 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 } } ] }
試試看!
API Explorer 可讓您提出要求範例,以便熟悉 API 和 API 選項。
- 選取頁面右側的 API 圖示 。
- 視需要展開「Show Standard parameters」,然後將
fields
參數設為欄位遮罩。 - 視需要編輯「要求主體」。
- 選取「執行」按鈕。在彈出式視窗中,選擇要用來提出請求的帳戶。
在「API Explorer」面板中選取展開圖示 ,展開「API Explorer」視窗。