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 的主要地點類型 (例如「餐廳」或「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

選用設定。input 的 Unicode 字元偏移值，表示 input 中的遊標位置。遊標位置可能會影響傳回的預測結果。

如果留空，預設值為 input。
includeQueryPredictions

boolean

選用設定。如果為 true，回應會同時包含 Place 和查詢預測。否則，回應只會傳回 Place 預測結果。
sessionToken

string

選用設定。用於識別計費 Autocomplete 工作階段的字串。必須是網址和檔案名稱安全 Base64 字串，長度上限為 36 個 ASCII 字元。否則系統會傳回 INVALID_UNIT 錯誤。

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

我們建議遵循下列規範：

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

回應主體

Places.autocomplete 的回應通訊協定。

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

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，反之亦然。