- HTTP 要求
- 要求主體
- 回應主體
- LocationBias
- LocationRestriction
- 建議
- PlacePrediction
- FormattableText
- StringRange
- StructuredFormat
- QueryPrediction
傳回指定輸入內容的預測結果。
HTTP 要求
POST https://places.googleapis.com/v1/places:autocomplete
這個網址使用 gRPC 轉碼語法。
要求主體
要求主體的資料會採用以下結構:
JSON 表示法 |
---|
{ "input": string, "locationBias": { object ( |
欄位 | |
---|---|
input |
必要欄位。要搜尋的文字字串。 |
location |
選用設定。針對指定位置調整結果。 最多應設定 |
location |
選用設定。將結果限制在指定地點。 最多應設定 |
included |
選用設定。包含主要地點類型 (例如「餐廳」或「加油站」) 在內 (https://developers.google.com/maps/documentation/places/web-service/place-types),或僅包含 |
included |
選用設定。只納入指定區域的結果,最多可以指定 15 個 CLDR 雙字元區碼。空集不會限制結果。如果同時設定 |
language |
選用設定。傳回結果時使用的語言。預設值為 en-US。如果 |
region |
選用設定。區碼,指定為 CLDR 雙字元區碼。這會影響地址格式、結果排名,並可能影響傳回的結果。這不會限制結果只顯示指定區域。如要將結果限制在特定地區,請使用 |
origin |
選用設定。計算到目的地的大地測距所用的原點 (以 |
input |
選用設定。以零為基底的 如果為空白,則預設為 |
include |
選用設定。如果為 true,回應會同時包含 Place 和查詢預測結果。否則回應只會傳回 Place 預測結果。 |
session |
選用設定。用來識別結算用 Autocomplete 工作階段的字串。必須是安全的 base64 字串,且長度不得超過 36 個 ASCII 字元。否則會傳回 INVALID_ARGUMENT 錯誤。 工作階段是從使用者輸入查詢時開始,到使用者選取地點並發出 PlaceDetails 或 AddressValidation 呼叫時結束。每個工作階段可以包含多個查詢,並且後續提出一項 PlaceDetails 或 AddressValidation 要求。工作階段中每個要求使用的憑證都必須屬於同一個 Google Cloud 控制台專案。工作階段結束後,符記就會失效;您的應用程式必須為每個工作階段產生新的符記。如果省略 建議您遵循下列準則:
|
include |
選用設定。如果欄位設為 true,則加入純區域服務商家。純區域服務商家會造訪或直接送貨給顧客,但不在商家地址為顧客提供服務。例如清潔服務或水電工等商家。這些商家在 Google 地圖上沒有實體地址或地點。地點不會傳回包括「 |
回應主體
回應原型檔,用於 places.autocomplete。
如果成功,回應主體會含有以下結構的資料:
JSON 表示法 |
---|
{
"suggestions": [
{
object ( |
欄位 | |
---|---|
suggestions[] |
包含建議清單,並按關聯性遞減排序。 |
LocationBias
要搜尋的區域。結果可能會偏向指定區域。
JSON 表示法 |
---|
{ // Union field |
欄位 | |
---|---|
聯集欄位
|
|
rectangle |
由東北角和西南角定義的視區範圍。 |
circle |
以圓心和半徑定義的圓形。 |
LocationRestriction
要搜尋的區域。結果會限制在指定的區域。
JSON 表示法 |
---|
{ // Union field |
欄位 | |
---|---|
聯集欄位
|
|
rectangle |
由東北角和西南角定義的視區範圍。 |
circle |
以圓心和半徑定義的圓形。 |
建議
自動完成建議結果。
JSON 表示法 |
---|
{ // Union field |
欄位 | |
---|---|
聯集欄位
|
|
place |
地點預測結果。 |
query |
查詢的預測結果。 |
PlacePrediction
Place Autocomplete 預測結果。
JSON 表示法 |
---|
{ "place": string, "placeId": string, "text": { object ( |
欄位 | |
---|---|
place |
建議地點的資源名稱。這個名稱可以在其他接受地點名稱的 API 中使用。 |
place |
建議地點的專屬 ID。這個 ID 可用於其他接受地點 ID 的 API。 |
text |
包含傳回結果的使用者可解讀名稱。對於商家結果,通常是商家名稱和地址。 如果開發人員想顯示單一 UI 元素,建議使用 這段文字可能與 places.get 傳回的 如果要求 |
structured |
提供「地點」預測的細目,當中包含地點名稱及次要文字,當中含有其他清楚易懂的地圖項目 (例如城市或區域)。 如果開發人員想顯示兩個獨立且相關的 UI 元素,建議使用 |
types[] |
請參閱 https://developers.google.com/maps/documentation/places/web-service/place-types 中的表 A 或表 B,列出適用於此地點的類型。 類型是地點的分類,共通類型的地點會有相似的特徵。 |
distance |
如果指定 |
FormattableText
代表地點或查詢預測結果的文字。文字可以採用格式化或格式化。
JSON 表示法 |
---|
{
"text": string,
"matches": [
{
object ( |
欄位 | |
---|---|
text |
可直接使用或以 |
matches[] |
字串範圍清單,用於指出輸入要求在 這些值是 |
StringRange
找出指定文字中的子字串。
JSON 表示法 |
---|
{ "startOffset": integer, "endOffset": integer } |
欄位 | |
---|---|
start |
字串第一個 Unicode 字元的位移值 (含),以零為基準。 |
end |
最後一個 Unicode 字元的偏移量 (從零開始) (不包含)。 |
StructuredFormat
包含地點或查詢預測結果的細目,當中包含主要文字和次要文字。
針對地點預測結果,主要文字會包含地點的具體名稱。查詢預測的主要文字包含查詢。
次要文字包含其他可區分功能 (例如城市或區域),可進一步識別地點或精進查詢。
JSON 表示法 |
---|
{ "mainText": { object ( |
欄位 | |
---|---|
main |
代表地點或查詢的名稱。 |
secondary |
代表其他可用於區分功能 (例如城市或區域),用於進一步識別地點或精進查詢。 |
QueryPrediction
查詢自動完成預測的預測結果。
JSON 表示法 |
---|
{ "text": { object ( |
欄位 | |
---|---|
text |
預測的文字。這段文字並非代表地點,而是可用於搜尋端點 (例如 Text Search) 的文字查詢。 如果開發人員想顯示單一 UI 元素,建議使用 如果要求 |
structured |
將查詢預測結果分成包含查詢的「主要文字」和包含其他不含歧義功能 (例如城市或區域) 的「次要文字」。 如果開發人員想顯示兩個獨立但相關的 UI 元素,建議使用 |