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 地圖上沒有實體地址或地點。地點服務不會針對這些商家傳回欄位,包括 locationplusCode 和其他位置相關欄位。

回應主體

回應原型檔,用於 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

建議地點的資源名稱。這個名稱可用於接受 Place 名稱的其他 API。

placeId

string

建議地點的專屬 ID。這個 ID 可用於接受 Place 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,反之亦然。