- HTTP 要求
- 要求主體
- 回應主體
- LocationBias
- LocationRestriction
- 建議
- PlacePrediction
- FormattableText
- StringRange
- StructuredFormat
- QueryPrediction
傳回指定輸入內容的預測結果。
HTTP 要求
POST https://places.googleapis.com/v1/places:autocomplete
這個網址使用 gRPC 轉碼語法。
要求主體
要求主體的資料會採用以下結構:
JSON 表示法 |
---|
{ "input": string, "locationBias": { object ( |
欄位 | |
---|---|
input |
必要欄位。要搜尋的文字字串。 |
locationBias |
選用設定。將結果自訂調整至指定位置。 最多只能設定 |
locationRestriction |
選用設定。限制系統只傳回指定位置的結果。 最多只能設定 |
includedPrimaryTypes[] |
選用設定。納入 https://developers.google.com/maps/documentation/places/web-service/place-types 的主要地點類型 (例如「餐廳」或「gas_station」)。只有在其主要類型列於此清單中時,才會傳回「地點」。最多可以指定 5 個值。如果沒有指定類型,則會傳回所有「地點」類型。 |
includedRegionCodes[] |
選用設定。只納入指定區域的結果,最多指定為 15 個 CLDR 雙字元區碼。如果組合為空白,則不會限制結果。如果同時設定 |
languageCode |
選用設定。傳回結果時使用的語言。預設值為 en-US。如果用於 |
regionCode |
選用設定。區碼,指定為 CLDR 雙字元區碼。這會影響地址格式和結果排名,也會影響系統傳回的結果。這不會限制系統只在指定指定區域顯示結果。如要將結果範圍限制在特定區域,請使用 |
origin |
選用設定。計算測地線距離至目的地的起點 (以 |
inputOffset |
選用設定。 如果留空,預設值為 |
includeQueryPredictions |
選用設定。如果為 true,回應會同時包含 Place 和查詢預測。否則,回應只會傳回 Place 預測結果。 |
sessionToken |
選用設定。用於識別計費 Autocomplete 工作階段的字串。必須是網址和檔案名稱安全 Base64 字串,長度上限為 36 個 ASCII 字元。否則系統會傳回 INVALID_UNIT 錯誤。 工作階段是從使用者輸入查詢時開始,到使用者選取地點,並呼叫 Place Details 或地址驗證時結束。每個工作階段可以有多個查詢,後面接著一個 Place Details 或 Address 驗證要求。工作階段內每個要求使用的憑證,必須隸屬於同一個 Google Cloud 控制台專案。工作階段結束後,符記就會失效;應用程式必須為每個工作階段產生新的符記。如果省略 我們建議遵循下列規範:
|
回應主體
Places.autocomplete 的回應通訊協定。
如果成功,回應主體即會包含具有以下結構的資料:
JSON 表示法 |
---|
{
"suggestions": [
{
object ( |
欄位 | |
---|---|
suggestions[] |
內含建議清單,並依關聯性遞減排序。 |
LocationBias
要搜尋的區域。結果可能會針對指定區域周圍而調整。
JSON 表示法 |
---|
{ // Union field |
欄位 | |
---|---|
聯集欄位
|
|
rectangle |
由東北角和西南角定義的可視區域。 |
circle |
由中心點和半徑定義的圓形。 |
LocationRestriction
要搜尋的區域。系統只會顯示指定區域的搜尋結果。
JSON 表示法 |
---|
{ // Union field |
欄位 | |
---|---|
聯集欄位
|
|
rectangle |
由東北角和西南角定義的可視區域。 |
circle |
由中心點和半徑定義的圓形。 |
建議
自動完成建議結果。
JSON 表示法 |
---|
{ // Union field |
欄位 | |
---|---|
聯集欄位
|
|
placePrediction |
地點的預測結果。 |
queryPrediction |
查詢的預測結果。 |
PlacePrediction
Place Autocomplete 預測結果的預測結果。
JSON 表示法 |
---|
{ "place": string, "placeId": string, "text": { object ( |
欄位 | |
---|---|
place |
建議地點的資源名稱。這個名稱可用於其他接受「地點」名稱的 API。 |
placeId |
建議地點的專屬 ID。這個 ID 可用於其他接受地點 ID 的 API。 |
text |
包含傳回結果中人類可讀的名稱。對建築物結果而言,這通常都是商家名稱和地址。 如果開發人員想顯示單一 UI 元素,則建議使用 此文字可能與 place.get 傳回的 如果要求 |
structuredFormat |
「地點」預測結果細分為主要文字,其中包含「地點」的名稱和次要文字,其中包含其他能夠釐清的地圖項目 (例如城市或區域)。 如果開發人員想顯示兩個獨立但相關的 UI 元素,則建議使用 |
types[] |
適用於此地點的類型清單,請見 https://developers.google.com/maps/documentation/places/web-service/place-types。 類型是地點的分類,含有共用類型的地點會具備類似的特性。 |
distanceMeters |
指定 |
FormattableText
代表地點或查詢預測結果的文字。文字可依格式或格式使用。
JSON 表示法 |
---|
{
"text": string,
"matches": [
{
object ( |
欄位 | |
---|---|
text |
可以是 |
matches[] |
字串範圍清單,可識別在 這些值是 |
StringRange
識別特定文字中的子字串。
JSON 表示法 |
---|
{ "startOffset": integer, "endOffset": integer } |
欄位 | |
---|---|
startOffset |
字串第一個 Unicode 字元 (含首尾) 從零開始計算。 |
endOffset |
最後 Unicode 字元的零開始偏移 (不含)。 |
StructuredFormat
包含主要文字和次要文字中地點或查詢預測的細目。
對於「地點」預測,主要文字包含該地點的特定名稱。如要進行查詢預測,主要文字包含查詢。
次要文字包含額外的區分功能 (例如城市或區域),以進一步識別地點或修正查詢。
JSON 表示法 |
---|
{ "mainText": { object ( |
欄位 | |
---|---|
mainText |
代表地點或查詢的名稱。 |
secondaryText |
代表其他明確的功能 (例如城市或區域),以進一步識別地點或修正查詢。 |
QueryPrediction
Query Autocomplete 預測結果的預測結果。
JSON 表示法 |
---|
{ "text": { object ( |
欄位 | |
---|---|
text |
預測的文字。此文字不是代表「地點」,而是可在搜尋端點 (例如「Text Search」) 中使用的文字查詢。 如果開發人員想顯示單一 UI 元素,則建議使用 如果 |
structuredFormat |
將查詢預測結果細分為主要文字,其中包含查詢內容和次要文字,其中包含其他清楚明確的特徵 (例如城市或區域)。 如果開發人員想顯示兩個獨立但相關的 UI 元素,則建議使用 |