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,
  "includePureServiceAreaBusinesses": boolean
}
欄位
input

string

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

locationBias

object (LocationBias)

選用設定。針對指定位置調整結果。

最多應設定 locationBiaslocationRestriction 其中一個。如果未設定這兩者,結果會受到 IP 位址偏差影響,也就是說 IP 位址會對應至不精確的位置,並用作偏差信號。

locationRestriction

object (LocationRestriction)

選用設定。將結果限制在指定地點。

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

includedPrimaryTypes[]

string

選用設定。包含主要地點類型 (例如「餐廳」或「加油站」) 在內 (https://developers.google.com/maps/documentation/places/web-service/place-types),或僅包含 (regions),或僅包含 (cities)。只有當「地點」的主要類型列於這個清單中時,才會傳回「地點」。最多可指定 5 個值。如果未指定類型,系統會傳回所有地點類型。

includedRegionCodes[]

string

選用設定。只納入指定區域的結果,最多可以指定 15 個 CLDR 雙字元區碼。空集不會限制結果。如果同時設定 locationRestrictionincludedRegionCodes,結果會位於交集區域。

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_ARGUMENT 錯誤。

工作階段是從使用者輸入查詢時開始,到使用者選取地點並發出 PlaceDetails 或 AddressValidation 呼叫時結束。每個工作階段可以包含多個查詢,並且後續提出一項 PlaceDetails 或 AddressValidation 要求。工作階段中每個要求使用的憑證都必須屬於同一個 Google Cloud 控制台專案。工作階段結束後,符記就會失效;您的應用程式必須為每個工作階段產生新的符記。如果省略 sessionToken 參數或重複使用工作階段符記,系統會視為未提供工作階段符記,並針對工作階段收費 (每個要求分別收費)。

建議您遵循下列準則:

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

boolean

選用設定。如果欄位設為 true,則加入純區域服務商家。純區域服務商家會造訪或直接送貨給顧客,但不在商家地址為顧客提供服務。例如清潔服務或水電工等商家。這些商家在 Google 地圖上沒有實體地址或地點。地點不會傳回包括「location」、「plusCode」和這些商家的位置相關欄位。

回應主體

回應原型檔,用於 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。這兩種方法是表示 Place 預測結果的兩種方式。使用者不應嘗試將 structuredFormat 剖析為 text,反之亦然。

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

如果要求 inputlanguageCode 使用不同語言,或是地點沒有從當地語言翻譯成 languageCode 的譯文,則可能會混用多種語言。

structuredFormat

object (StructuredFormat)

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

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

types[]

string

請參閱 https://developers.google.com/maps/documentation/places/web-service/place-types 中的表 A 或表 B,列出適用於此地點的類型。

類型是地點的分類,共通類型的地點會有相似的特徵。

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

查詢自動完成預測的預測結果。

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

object (FormattableText)

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

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

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

structuredFormat

object (StructuredFormat)

將查詢預測結果分成包含查詢的「主要文字」和包含其他不含歧義功能 (例如城市或區域) 的「次要文字」。

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