Method: places.autocomplete

傳回指定輸入內容的預測結果。

HTTP 要求

POST https://places.googleapis.com/v1/places:autocomplete

這個網址使用 gRPC 轉碼語法。

要求主體

要求主體的資料會採用以下結構：

JSON 表示法 
{
  "input": string,
  "locationBias": {
    object (LocationBias)
  },
  "locationRestriction": {
    object (LocationRestriction)
  },
  "includedPrimaryTypes": [
    string
  ],
  "includedRegionCodes": [
    string
  ],
  "languageCode": string,
  "regionCode": string,
  "origin": {
    object (LatLng)
  },
  "inputOffset": integer,
  "includeQueryPredictions": boolean,
  "sessionToken": string
}
欄位
input

string

必要欄位。要搜尋的文字字串。
locationBias

object (LocationBias)

選用設定。將結果自訂調整至指定位置。

最多只能設定 locationBias 或 locationRestriction 其中之一。如果兩者皆未設定，系統就會按 IP 位址調整結果，也就是說，這個 IP 位址會對應至不精確的位置，並做為自訂調整信號使用。
locationRestriction

object (LocationRestriction)

選用設定。限制只顯示指定位置的結果。

最多只能設定 locationBias 或 locationRestriction 其中之一。如果兩者皆未設定，系統就會按 IP 位址調整結果，也就是說，這個 IP 位址會對應至不精確的位置，並做為自訂調整信號使用。
includedPrimaryTypes[]

string

選用設定。包括地點類型 (https://developers.google.com/maps/documentation/places/web-service/place-types)，或僅限 (區域) 中，來自表 A 或表 B 表 B 的「餐廳」或「gas_station」。只有當「地點」的主要類型列於這個清單中時，才會傳回「地點」。最多可以指定 5 個值。如未指定類型，系統會傳回所有「地點」類型。
includedRegionCodes[]

string

選用設定。只納入指定區域的結果，最多可以指定 15 個 CLDR 雙字元區碼。空白集合不會限制結果。如果同時設定 locationRestriction 和 includedRegionCodes，結果會在十字路口的區域內。
languageCode

string

選用設定。傳回結果時使用的語言。預設值為 en-US。如果 input 使用的語言與 languageCode 不同，或是傳回的地點沒有當地語言翻譯成 languageCode 的版本，則結果可能會出現混合語言。
regionCode

string

選用設定。區碼，以 CLDR 雙字元區碼的形式指定。這會影響地址格式和結果排名，並可能會影響傳回的結果。這項操作不會限制只傳回指定區域的結果。如要將結果範圍限制在特定區域，請使用 region_code_restriction。
origin

object (LatLng)

選用設定。計算到目的地測地距離的起點 (傳回為 distanceMeters)。如果省略這個值，則不會傳回測地距離。
inputOffset

integer

選用設定。以零為基礎的 Unicode 字元位移 input，指出遊標位置input。遊標位置可能會影響傳回的預測結果。

如果留空，系統會使用 input 的長度。
includeQueryPredictions

boolean

選用設定。如果為 true，回應會包含地點和查詢預測結果。否則，回應將只會傳回「地點」預測結果。
sessionToken

string

選用設定。用來識別結算用 Autocomplete 工作階段的字串。必須是網址和檔案名稱安全 Base64 字串，且長度不得超過 36 個 ASCII 字元。否則會傳回 INVALID_src 錯誤。

工作階段是從使用者輸入查詢時開始，直到使用者選取地點，並呼叫 Place Details 或地址驗證時結束。每個工作階段都可以有多筆查詢，後面接著一筆地點詳細資料或地址驗證要求。工作階段中每個要求使用的憑證都必須屬於同一個 Google Cloud 控制台專案。工作階段結束後，符記就會失效；應用程式必須為每個工作階段產生新的符記。如果省略 sessionToken 參數或重複使用工作階段符記，系統會視為未提供工作階段符記，並針對工作階段收費 (每個要求分別收費)。

建議您遵循下列規範：

  • 對所有 Place Autocomplete 呼叫使用工作階段符記。
  • 為每個工作階段產生新的權杖。建議使用第 4 版 UUID。
  • 確認工作階段中所有 Place Autocomplete、Place Details 和 Address Validation 使用的憑證，均屬於同一個 Cloud 控制台專案。
  • 請務必針對每個新的工作階段傳遞不重複的工作階段符記。如果多個工作階段使用同一個符記，則每個要求會分別計費。

回應主體

places.autocomplete 的回應 proto。

如果成功，回應主體即會包含具有以下結構的資料：

JSON 表示法 
{
  "suggestions": [
    {
      object (Suggestion)
    }
  ]
}
欄位
suggestions[]

object (Suggestion)

包含建議清單，並按關聯性遞減排序。

LocationBias

要搜尋的區域。結果可能會根據指定區域進行自訂調整。

JSON 表示法 
{

  // Union field type can be only one of the following:
  "rectangle": {
    object (Viewport)
  },
  "circle": {
    object (Circle)
  }
  // End of list of possible types for union field type.
}
欄位

聯集欄位 type。

type 只能採用下列其中一種設定：
rectangle

object (Viewport)

以東北角和西南角定義的可視區域。
circle

object (Circle)

由中心點和半徑定義的圓形。

LocationRestriction

要搜尋的區域。結果只會在指定區域顯示。

JSON 表示法 
{

  // Union field type can be only one of the following:
  "rectangle": {
    object (Viewport)
  },
  "circle": {
    object (Circle)
  }
  // End of list of possible types for union field type.
}
欄位

聯集欄位 type。

type 只能採用下列其中一種設定：
rectangle

object (Viewport)

以東北角和西南角定義的可視區域。
circle

object (Circle)

由中心點和半徑定義的圓形。

建議

自動完成建議結果。

JSON 表示法 
{

  // Union field kind can be only one of the following:
  "placePrediction": {
    object (PlacePrediction)
  },
  "queryPrediction": {
    object (QueryPrediction)
  }
  // End of list of possible types for union field kind.
}
欄位

聯集欄位 kind。

kind 只能採用下列其中一種設定：
placePrediction

object (PlacePrediction)

地點的預測結果。
queryPrediction

object (QueryPrediction)

查詢的預測結果。

PlacePrediction

Place Autocomplete 預測結果的預測結果。

JSON 表示法 
{
  "place": string,
  "placeId": string,
  "text": {
    object (FormattableText)
  },
  "structuredFormat": {
    object (StructuredFormat)
  },
  "types": [
    string
  ],
  "distanceMeters": integer
}
欄位
place

string

建議地點的資源名稱。這個名稱可以在其他接受地點名稱的 API 中使用。
placeId

string

建議地點的專屬 ID。這個 ID 可用於其他接受地點 ID 的 API。
text

object (FormattableText)

包含傳回結果中使用者可理解的名稱。對建築物結果而言，這通常是商家名稱和地址。

如果開發人員想顯示單一 UI 元素，建議使用 text。如果開發人員想顯示兩個獨立但相關的 UI 元素，可以改用 structuredFormat。這兩種代表地點預測結果的不同方式。使用者不應該嘗試將 structuredFormat 剖析為 text，反之亦然。

這段文字可能與 place.get 傳回的 displayName 不同。

如果 input 和 languageCode 要求是使用不同語言，或者地點沒有從當地語言翻譯成languageCode，則可能以混合語言呈現。
structuredFormat

object (StructuredFormat)

提供「地點」預測的細目，當中包含地點名稱及次要文字，當中含有其他清楚易懂的地圖項目 (例如城市或區域)。

如果開發人員想顯示兩個獨立且相關的 UI 元素，建議使用 structuredFormat。如果開發人員想要顯示單一 UI 元素，可以改用 text。這兩種代表地點預測結果的不同方式。使用者不應該嘗試將 structuredFormat 剖析為 text，反之亦然。
types[]

string

可套用至此地點的類型清單 (網址為 https://developers.google.com/maps/documentation/places/web-service/place-types)。

型別是指「地點」的分類。共通類型的地點會有相似的特徵。
distanceMeters

integer

如果指定 origin，距離 origin 的測地線長度 (以公尺為單位)。這個欄位可能不會填入某些特定預測資訊，例如路線。

FormattableText

代表地點或查詢預測結果的文字。文字可以採用格式化或格式化。

JSON 表示法 
{
  "text": string,
  "matches": [
    {
      object (StringRange)
    }
  ]
}
欄位
text

string

可以原樣使用或採用 matches 格式的文字。
matches[]

object (StringRange)

字串範圍清單，用於識別 text 中與輸入要求相符的位置。範圍可用來設定 text 的特定部分格式。如果比對時是基於字串比對以外的條件 (例如拼字更正或音譯)，則子字串可能不會與 input 完全相符。

這些值是 text 的萬國碼 (Unicode) 字元偏移。範圍保證會依照遞增的偏移值排序。

StringRange

識別指定文字內的子字串。

JSON 表示法 
{
  "startOffset": integer,
  "endOffset": integer
}
欄位
startOffset

integer

字串第一個 Unicode 字元的零基偏移 (含)。
endOffset

integer

最後一個 Unicode 字元的零點偏移 (不含)。

StructuredFormat

包含地點或查詢預測結果的細目，當中包含主要文字和次要文字。

如果是「地點」預測，主要文字包含「地點」的特定名稱。查詢預測的主要文字包含查詢。

次要文字包含其他消歧功能 (例如城市或區域)，方便使用者進一步辨識地點或修正查詢。

JSON 表示法 
{
  "mainText": {
    object (FormattableText)
  },
  "secondaryText": {
    object (FormattableText)
  }
}
欄位
mainText

object (FormattableText)

代表地點或查詢的名稱。
secondaryText

object (FormattableText)

代表其他可清楚辨識的地圖項目 (例如城市或區域)，以便進一步識別地點或修正查詢。

QueryPrediction

Query Autocomplete 預測結果的預測結果。

JSON 表示法 
{
  "text": {
    object (FormattableText)
  },
  "structuredFormat": {
    object (StructuredFormat)
  }
}
欄位
text

object (FormattableText)

預測文字。這段文字並非代表地點，而是可用於搜尋端點 (例如 Text Search) 的文字查詢。

如果開發人員想顯示單一 UI 元素，建議使用 text。如果開發人員想顯示兩個獨立但相關的 UI 元素，可以改用 structuredFormat。這兩種預測方式都代表查詢預測結果。使用者不應該嘗試將 structuredFormat 剖析為 text，反之亦然。

如果要求 input 和 languageCode 使用不同的語言，或是有部分查詢沒有從當地語言翻譯成 languageCode 時，則可使用混合語言。
structuredFormat

object (StructuredFormat)

查詢預測的主要文字，內含查詢，次要文字則含有其他容易辨識的特徵 (例如城市或區域)。

如果開發人員想顯示兩個獨立且相關的 UI 元素，建議使用 structuredFormat。如果開發人員想要顯示單一 UI 元素，可以改用 text。這兩種預測方式都代表查詢預測結果。使用者不應該嘗試將 structuredFormat 剖析為 text，反之亦然。