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,
  "includeFutureOpeningBusinesses": boolean
}
欄位
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) 中包含的主要地點類型 (例如「restaurant」或「gas_station」)，或僅 (regions)，或僅 (cities)。只有當地點的主要類型包含在這份清單中時，系統才會傳回該地點。最多可指定 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_ARGUMENT 錯誤。

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

建議遵循下列準則：

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

boolean

(選用步驟) 如果欄位設為 true，則包含純區域服務商家。純區域服務商家是指提供到府服務或直接送貨給顧客的商家，不在商家地址服務顧客。例如清潔或水電服務。這些商家在 Google 地圖上沒有實體地址或位置。Places 不會傳回這些商家包含 location、plusCode 和其他位置相關欄位的資料。
includeFutureOpeningBusinesses

boolean

(選用步驟) 如果設為 true，則包含尚未開幕但未來會開幕的商家。

回應主體

places.autocomplete 的回應 proto。

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

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

object (Suggestion)

內含建議清單，依關聯性遞減排序。

授權範圍

需要下列 OAuth 範圍：

  • https://www.googleapis.com/auth/cloud-platform

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

這段文字可能與 places.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 的表 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，反之亦然。

如果要求 input 和 languageCode 使用不同語言，或查詢的部分內容沒有從當地語言到 languageCode 的翻譯，則可能以混合語言顯示。
structuredFormat

object (StructuredFormat)

查詢預測的細目，包括含有查詢內容的主要文字，以及含有其他消歧特徵 (例如城市或區域) 的次要文字。

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