自動完成 (新版) 服務 來回應 HTTP 要求在要求中指定 搜尋字串和控制搜尋區域的地理邊界。
「自動完成 (新版)」服務可比對完整字詞, 所輸入的子字串,解析地點名稱、地址和 plus code。因此應用程式會傳送 以便即時提供地點和查詢預測結果。
Autocomplete (New) API 的回應可包含兩種類型 預測結果 -
- 地點預測:地點,例如商家、地址和搜尋點 興趣 (以指定輸入文字字串和搜尋區域為準)。地點預測結果 預設會傳回 。
- 查詢預測:與輸入文字字串相符的查詢字串,
搜尋區域根據預設,系統不會傳回查詢預測。使用
includeQueryPredictions
要求參數,用來將查詢預測新增至 回應。
舉例來說,您可以使用 做為輸入字串來呼叫 API,而該字串包含部分使用者輸入內容。 「西西里貓」,搜尋區域僅限於加州舊金山。回應會包含 與搜尋字串和搜尋區域相符的地點預測清單,例如 名為「西西里披薩餐廳」的餐廳,以及該地點的詳細資訊。
傳回的地點預測結果旨在協助使用者, 讓他們選擇您想要的地點你可以 Place Details (新功能) 要求,取得任何傳回地點預測結果的詳細資訊。
回應中也可包含與查詢預測相符的
搜尋字串和搜尋區域,例如「西里西亞披薩和義大利麵」。顯示查詢的
回應中的 text
欄位含有建議的文字搜尋字串。使用
做為輸入內容
Text Search (新版)
執行更詳細的搜尋
API Explorer 可讓您發出即時要求,以便熟悉 API 以及 API 選項:
試試看!自動完成 (新版) 要求
Autocomplete (新版) 請求是對 表單:
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
關於回覆
自動完成 (新版) 會傳回 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 code。 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 到 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
個錯誤。 - 偏好的語言對於 Google 提供的 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
工作階段符記是使用者產生的字串,可追蹤自動完成功能 (新) 呼叫做為「工作階段」。自動完成 (新版) 會使用工作階段符記 將使用者自動完成搜尋的查詢和選取階段歸入不同的工作階段 帳單用途若需更多資訊,請參閲 工作階段符記。
自動完成 (新版) 範例
使用 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 圖示
。 網頁右側。
- 視需要展開「顯示標準參數」並進行設定
fields
參數 欄位遮罩。 - 視需要編輯「要求主體」。
- 選取「執行」按鈕。在彈出式視窗中,選擇要用來提出請求的帳戶。
在 API Explorer 面板中,選取展開圖示
,展開「API Explorer」視窗。