本頁面由 Cloud Translation API 翻譯而成。

自動完成 (新推出)

選取平台： Android iOS JavaScript 網頁服務

歐洲經濟區 (EEA) 開發人員

簡介

Autocomplete (新版) 是一項網路服務，可根據 HTTP 要求傳回地點預測和查詢預測結果。在要求中，指定文字搜尋字串和控制搜尋區域的地理範圍。

「自動完成 (新版)」可比對完整字詞和輸入內容的子字串，解析地點名稱、地址和 Plus Codes。因此，應用程式可在使用者輸入內容時傳送查詢，即時提供地點和查詢預測結果。

Autocomplete (新版) 的回應可能包含兩種預測結果：

地點預測：根據指定的輸入文字字串和搜尋區域，預測地點，例如商家、地址和搜尋點。系統預設會傳回地點預測結果。
查詢預測：與輸入文字字串和搜尋區域相符的查詢字串。系統預設不會傳回查詢預測。使用 includeQueryPredictions 要求參數，將查詢預測加入回應。

舉例來說，您可以使用含有部分使用者輸入內容「Sicilian piz」的字串做為輸入內容，呼叫 Autocomplete (New)，並將搜尋範圍限制在加州舊金山。接著，回應會包含符合搜尋字串和搜尋區域的地點預測清單，例如名為「Sicilian Pizza Kitchen」的餐廳，以及該地點的詳細資料。

傳回的地點預測結果會顯示給使用者，協助他們選取所需地點。您可以提出 Place Details (New) 要求，取得任何傳回地點預測結果的詳細資訊。

回應也可能包含符合搜尋字串和搜尋區域的查詢預測清單，例如「西西里披薩和義大利麵」。回應中的每個查詢預測結果都包含 text 欄位，內含建議的文字搜尋字串。將該字串做為Text Search (新版) 的輸入內容，執行更詳細的搜尋。

您可以使用 APIs Explorer 提出即時要求，熟悉 API 和 API 選項：

試試看！

自動完成 (新版) 要求

自動完成 (新版) 要求是傳送至網址的 HTTP POST 要求，格式如下：

https://places.googleapis.com/v1/places:autocomplete

在 POST 要求中，將所有參數傳遞至 JSON 要求內文或標頭。例如：

curl -X POST -d '{
  "input": "pizza",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

支援的參數

參數	說明
`input`*	要搜尋的文字字串 (完整字詞、子字串、地點名稱、地址、Plus Codes)。
`FieldMask` (HTTP 標頭)	以逗號分隔的清單，指定要在回應中傳回的欄位。
`includedPrimaryTypes`	限制結果，只顯示符合最多五個指定主要類型的地點。
`includePureServiceAreaBusinesses`	如果為 true，則包含沒有實體店面的商家 (區域服務商家)。預設值為 false。
`includeQueryPredictions`	如果設為 true，回應中會同時包含地點和查詢預測。預設值為 false。
`includedRegionCodes`	最多 15 個雙字元國家/地區代碼的陣列，用於限制結果。
`inputOffset`	游標在輸入字串中的位置 (從零算起)，會影響預測結果。預設為輸入長度。
`languageCode`	搜尋結果的偏好語言 (IETF BCP-47 代碼)。預設值為 Accept-Language 標頭或「en」。
`locationBias`	指定要優先顯示搜尋結果的區域 (圓形或矩形)，允許顯示區域外的結果。無法與 locationRestriction 搭配使用。
`locationRestriction`	指定要限制搜尋結果的區域 (圓形或矩形)。系統會排除這個區域外的結果。無法與 locationBias 搭配使用。
`origin`	用來計算預測目的地直線距離 (distanceMeters) 的原點 (緯度、經度)。
`regionCode`	用於格式化回應和偏誤建議的地區代碼 (例如 'uk'、'fr')。
`sessionToken`	使用者產生的字串，可將 Autocomplete 呼叫歸入工作階段，以用於計費。

* 代表必填欄位。

關於回覆

自動完成 (新版) 會以 JSON 物件的形式傳回回應。在回應中：

suggestions 陣列包含所有預測的地點和查詢，並根據感知關聯性排序。每個地點都以 placePrediction 欄位表示，每個查詢則以 queryPrediction 欄位表示。
placePrediction 欄位包含單一地點預測的詳細資訊，包括地點 ID 和文字說明。
queryPrediction 欄位包含單一查詢預測的詳細資訊。

注意：自動完成 (新版) 會傳回最多五項預測結果，視要求而定，可能是 placePredictions、queryPredictions 或兩者兼具。如果要求未設定 includeQueryPredictions，回應最多會包含五個 placePredictions。如果要求設定 includeQueryPredictions，回應最多會包含五項預測，組合為 placePredictions 和 queryPredictions。

完整的 JSON 物件格式如下：

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }]
        },
      ...
    },
    {
      "queryPrediction": {
        "text": {
          "text": "Amoeba Music",
          "matches": [
            {
              "endOffset": 6
            }]
        },
        ...
    }
  ...]
}

必要參數

輸入

要搜尋的文字字串。指定完整字詞和子字串、地點名稱、地址和 Plus Codes。Autocomplete (New) 服務會根據這個字串傳回候選相符項目，並依據觀察到的關聯性排序結果。

選用參數

FieldMask

建立回應欄位遮罩，指定要在回應中傳回的欄位清單。使用 HTTP 標頭 X-Goog-FieldMask，將回應欄位遮罩傳遞至方法。

指定要傳回的建議欄位清單 (以半形逗號分隔)。舉例來說，如要擷取建議的 suggestions.placePrediction.text.text 和 suggestions.queryPrediction.text.text。
```
  X-Goog-FieldMask: suggestions.placePrediction.text.text,suggestions.queryPrediction.text.text
```
注意： 欄位清單中不得有任何空格。

使用 * 擷取所有欄位。
```
  X-Goog-FieldMask: *
```
includedPrimaryTypes

一個地點只能有一個主要類型，且必須是表 A 或表 B 中列出的類型。舉例來說，主要類型可能是 "mexican_restaurant" 或 "steak_house"。

根據預設，API 會根據 input 參數傳回所有地點，無論與地點相關聯的主要類型值為何。傳遞 includedPrimaryTypes 參數，將結果限制為特定主要類型。

使用這個參數，從表 A 或表 B 指定最多五個類型值。地點必須符合其中一個指定的主要類型值，才會納入回應。

這個參數也可以改為包含 (regions) 或 (cities)。(regions) 類型集合會篩選區域或分區，例如鄰里和郵遞區號。(cities) 類型集合會篩選出 Google 判斷為城市的地點。

如有下列情況，要求就會遭拒，並傳回 INVALID_REQUEST 錯誤：
- 指定超過五個類型。
- 除了 (cities) 或 (regions) 之外，還指定了任何型別。
- 指定任何無法辨識的類型。
注意：includedPrimaryTypes 參數僅適用於地點的主要類型，不適用於與地點相關聯的所有類型。雖然每個地點都有主要類型，但 Places API (新版) 並非支援所有主要類型。支援的類型包括表 A 或表 B 中列出的類型。
includePureServiceAreaBusinesses

如果設為 true，回應會包含直接為顧客提供送貨或到府服務，但沒有實體店面的商家。如果設為 false，API 只會傳回有實體營業場所的商家。
includeQueryPredictions

如果是 true，回應會同時包含地點和查詢預測。預設值為 false，表示回應只會包含地點預測結果。
includedRegionCodes

只納入指定區域清單的結果，指定方式為最多 15 個國家/地區代碼頂層網域 (ccTLD) 的兩位字元值陣列。如果省略，系統不會對回覆套用任何限制。舉例來說，如要將地區限制為德國和法國，請執行下列操作：
```
    "includedRegionCodes": ["de", "fr"]
```
如果同時指定 locationRestriction 和 includedRegionCodes，結果會位於這兩項設定的交集區域。

注意：如果使用國家/地區代碼時收到非預期的結果，請確認您使用的代碼是否包含所需的國家/地區、附屬領土和特殊地理區域。如要取得代碼相關資訊，您可以查看維基百科的 ISO 3166 國家/地區代碼清單或 ISO 線上瀏覽平台。
inputOffset

以零為基準的 Unicode 字元位移值，表示 input 中的游標位置。游標位置可能會影響系統傳回的預測結果。如果為空白，預設值為 input 的長度。

注意： 在初始的受限預覽版中，這項屬性稱為 predictionTermOffset。
languageCode

傳回結果時偏好的語言。如果 input 中使用的語言與 languageCode 指定的值不同，或者傳回的地點沒有從當地語言到 languageCode 的翻譯，結果可能會以混合語言顯示。
- 您必須使用 IETF BCP-47 語言代碼指定偏好的語言。
- 如未提供 languageCode，API 會使用 Accept-Language 標頭中指定的值。如未指定，則預設值為 en。如果指定無效的語言代碼，API 會傳回 INVALID_ARGUMENT 錯誤。
- 偏好語言對 API 選擇傳回的結果集和傳回順序影響不大。這也會影響 API 修正拼字錯誤的能力。
- API 會嘗試提供使用者和當地居民都能解讀的街道地址，同時反映使用者輸入內容。地點預測的格式會因每個要求中的使用者輸入內容而異。
  - 系統會先選擇 input 參數中的相符字詞，並使用與 languageCode 參數所指出語言偏好設定一致的名稱 (如有)，否則會使用最符合使用者輸入內容的名稱。
  - 如果可以，系統會以使用者可讀的文字，用當地語言格式化街道地址，但前提是必須先選取相符的字詞，與 input 參數中的字詞相符。
  - 選取與 input 參數中的字詞相符的字詞後，系統會以偏好語言傳回所有其他地址。如果偏好語言沒有名稱，API 會使用最接近的名稱。
locationBias 或 locationRestriction

您可以指定 locationBias 或 locationRestriction (但不能同時指定兩者)，定義搜尋範圍。locationRestriction 可視為指定結果必須位於的區域，locationBias 則可視為指定結果必須位於的區域附近，但可超出該區域。

注意： 如果您同時省略 locationBias 和 locationRestriction，系統預設會使用 IP 偏誤。使用 IP 偏誤時，自動完成 (新版) 會根據裝置的 IP 位址調整結果。
- locationBias
  
  指定要搜尋的區域。這個位置會做為偏誤，也就是說，系統可能會傳回指定位置附近的結果，包括指定區域外的結果。
- locationRestriction
  
  指定要搜尋的區域。系統不會傳回指定區域外的結果。
將 locationBias 或 locationRestriction 區域指定為矩形檢視區塊或圓形。
- 圓形是由中心點和半徑 (以公尺為單位) 定義。半徑必須介於 0.0 至 50000.0 之間 (含首尾)。預設值為 0.0。如果是 locationRestriction，半徑必須設為大於 0.0 的值。否則要求不會傳回任何結果。
  
  例如：
```
"locationBias": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}
```
- 矩形是經緯度可視區域，以兩個對角線相對的 low 和高點表示。可視區域視為封閉區域，因此包含邊界。緯度範圍必須介於 -90 到 90 度之間 (含首尾)，經度範圍則必須介於 -180 到 180 度之間 (含首尾)：
  - 如果 low = high，可視區域就是該單一點。
  - 如果 low.longitude > high.longitude，經度範圍會反轉 (可視區域會跨越 180 度經度線)。
  - 如果 low.longitude = -180 度且 high.longitude = 180 度，可視區域會包含所有經度。
  - 如果 low.longitude = 180 度且 high.longitude = -180 度，經度範圍會是空白。
  low 和 high 都必須填入值，且代表的方塊不得為空。如果檢視區塊空白，就會發生錯誤。
  
  舉例來說，這個檢視區塊完全包圍紐約市：
```
"locationBias": {
  "rectangle": {
    "low": {
      "latitude": 40.477398,
      "longitude": -74.259087
    },
    "high": {
      "latitude": 40.91618,
      "longitude": -73.70018
    }
  }
}
```
起源

計算與目的地直線距離的起點 (以 distanceMeters 形式傳回)。如果省略這個值，系統就不會傳回直線距離。必須指定為經緯度座標：
```
"origin": {
    "latitude": 40.477398,
    "longitude": -74.259087
}
```
regionCode

用來格式化回應的區域代碼，指定為 ccTLD (「頂層網域」) 的雙字元值。大多數 ccTLD 代碼與 ISO 3166-1 代碼相同，但有一些需要注意的例外情況。舉例來說，英國的 ccTLD 是「uk」(co.uk)，而 ISO 3166-1 代碼是「gb」(技術上是指「大不列顛及北愛爾蘭聯合王國」實體)。

建議也會根據區域代碼有所偏誤。Google 建議根據使用者的區域偏好設定 regionCode。

如果指定無效的地區代碼，API 會傳回 INVALID_ARGUMENT 錯誤。視適用法律而定，這項參數可能會影響結果。
sessionToken

工作階段符記是使用者產生的字串，可將 Autocomplete (New) 呼叫追蹤為「工作階段」。自動完成 (新版) 會使用工作階段符記，將使用者自動完成搜尋的查詢和選取階段歸入不同的工作階段，以用於計費。詳情請參閱「工作階段符記」。

選擇參數來調整結果

自動完成 (新版) 參數可能會以不同方式影響搜尋結果。下表根據預期結果，提供參數使用建議。

參數	使用建議
`regionCode`	根據使用者的地區偏好設定。
`includedRegionCodes`	設定為將結果限制在指定區域清單中。
`locationBias`	如果希望結果位於特定區域或附近，請使用這項功能。如適用，請將區域定義為使用者查看的地圖可視區域。
`locationRestriction`	只有在不應傳回區域外的結果時，才使用。
`origin`	如要計算每個預測結果的直線距離，請使用這個函式。注意：並非所有預測結果都會顯示距離。請參閱回應缺少距離。

Autocomplete (新版) 範例

使用 locationRestriction 將搜尋範圍限制在特定區域

注意：自動完成 (新版) 預設會使用 IP 調整設定來控管搜尋區域。啟用 IP 偏誤後，自動完成 (新版) 會使用裝置的 IP 位址來偏誤結果。您可以選擇使用 locationRestriction 或 locationBias (但不能同時使用)，指定要搜尋的區域。

locationRestriction 會指定要搜尋的區域。系統不會傳回指定區域外的結果。在下列範例中，您可以使用 locationRestriction 將要求限制為以舊金山為中心，半徑 5000 公尺的圓形：

curl -X POST -d '{
  "input": "Art museum",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

指定區域內的所有結果都會包含在 suggestions 陣列中：

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "museum",
            "point_of_interest"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJI7NivpmAhYARSuRPlbbn_2w",
          "placeId": "ChIJI7NivpmAhYARSuRPlbbn_2w",
          "text": {
            "text": "de Young Museum, Hagiwara Tea Garden Drive, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 15
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "de Young Museum",
              "matches": [
                {
                  "endOffset": 15
                }
              ]
            },
            "secondaryText": {
              "text": "Hagiwara Tea Garden Drive, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "point_of_interest",
            "tourist_attraction",
            "museum"
          ]
        }
      },
      /.../
    ]
  }

您也可以使用 locationRestriction，將搜尋範圍限制在矩形可視區域。以下範例會將要求限制在舊金山市區：

  curl -X POST -d '{
    "input": "Art museum",
    "locationRestriction": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

結果會包含在 suggestions 陣列中：

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "museum",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJyQNK-4SAhYARO2DZaJleWRc",
          "placeId": "ChIJyQNK-4SAhYARO2DZaJleWRc",
          "text": {
            "text": "International Art Museum of America, Market Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 14,
                "endOffset": 24
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "International Art Museum of America",
              "matches": [
                {
                  "startOffset": 14,
                  "endOffset": 24
                }
              ]
            },
            "secondaryText": {
              "text": "Market Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "museum",
            "point_of_interest",
            "tourist_attraction",
            "art_gallery",
            "establishment"
          ]
        }
      }
    ]
  }

使用 locationBias 將搜尋結果自訂調整為僅限某個區域

使用 locationBias 時，位置資訊會做為自訂調整，也就是說，系統可能會傳回指定位置附近的結果，包括指定區域外的結果。在下列範例中，您會將要求偏向舊金山市區：

curl -X POST -d '{
  "input": "Amoeba",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

現在的結果包含更多項目，包括 5000 公尺半徑以外的結果：

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "store",
          "establishment",
          "home_goods_store"
        ]
      }
    },
    {
      "placePrediction": {
        "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
        "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
        "text": {
          "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Telegraph Avenue, Berkeley, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "establishment",
          "home_goods_store",
          "store"
        ]
      }
    },
    ...
  ]
}

您也可以使用 locationBias，將搜尋範圍限制在矩形可視區域。以下範例會將要求限制在舊金山市區：

  curl -X POST -d '{
    "input": "Amoeba",
    "locationBias": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

雖然回應中會顯示矩形可視區域內的搜尋結果，但由於偏誤，部分結果會超出定義的邊界。結果也會包含在 suggestions 陣列中：

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "text": {
            "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Haight Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
          "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
          "text": {
            "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Telegraph Avenue, Berkeley, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJRdmfADq_woARYaVhnfQSUTI",
          "placeId": "ChIJRdmfADq_woARYaVhnfQSUTI",
          "text": {
            "text": "Amoeba Music, Hollywood Boulevard, Los Angeles, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Hollywood Boulevard, Los Angeles, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
    /.../
    ]
  }

使用 includedPrimaryTypes

使用 includedPrimaryTypes 參數，從表 A、表 B 或僅 (regions) 或僅 (cities) 指定最多五個類型值。地點必須符合其中一個指定的主要類型值，才會納入回應。

在下列範例中，您指定「Soccer」的 input 字串，並使用 includedPrimaryTypes 參數將結果限制為 "sporting_goods_store" 類型的場所：

curl -X POST -d '{
  "input": "Soccer",
  "includedPrimaryTypes": ["sporting_goods_store"],
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

如果省略 includedPrimaryTypes 參數，結果可能會包含您不想要的類型的場所，例如 "athletic_field"。

要求查詢預測

系統預設不會傳回查詢預測。使用 includeQueryPredictions 要求參數，在回應中加入查詢預測。例如：

curl -X POST -d '{
  "input": "Amoeba",
  "includeQueryPredictions": true,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

如「關於回應」一節所示，suggestions 陣列現在同時包含地點預測和查詢預測。每項查詢預測都包含 text 欄位，內含建議的文字搜尋字串。您可以提出 Text Search (New) 要求，進一步瞭解傳回的任何查詢預測。

注意：設定 includedRegionCodes 參數時，系統不會傳回查詢預測。

使用來源

在本例中，請在要求中加入 origin 做為經緯度座標。加入 origin 時，Autocomplete (New) 會在回應中加入 distanceMeters 欄位，其中包含從 origin 到目的地的直線距離。這個範例將原點設為舊金山中心：

curl -X POST -d '{
  "input": "Amoeba",
  "origin": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

回應現在包含 distanceMeters：

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "home_goods_store",
          "establishment",
          "point_of_interest",
          "store",
          "electronics_store"
        ],
        "distanceMeters": 3012
      }
    }
  ]
}

回覆缺少距離資訊

在某些情況下，即使要求中包含 origin，回應主體中仍會缺少 distanceMeters。可能發生這種情況的情境如下：

distanceMeters不會納入route預測。
如果值為 0，系統就不會納入 distanceMeters。如果預測位置與提供的 origin 位置相距不到 1 公尺，就會發生這種情況。

用戶端程式庫嘗試從剖析的物件讀取 distanceMeters 欄位時，會傳回值為 0 的欄位。為避免誤導使用者，請不要向使用者顯示零距離。

試試看！

您可以使用 APIs Explorer 提出範例要求，熟悉 API 和 API 選項。

選取頁面右側的 API 圖示 api。
視需要編輯要求參數。
選取「Execute」按鈕。在對話方塊中，選擇要用來提出要求的帳戶。
在 APIs Explorer 面板中，選取全螢幕圖示 fullscreen 即可展開 APIs Explorer 視窗。

自動完成 (新推出) 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

簡介

自動完成 (新版) 要求

支援的參數

關於回覆

必要參數

輸入

選用參數

FieldMask

includedPrimaryTypes

includePureServiceAreaBusinesses

includeQueryPredictions

includedRegionCodes

inputOffset

languageCode

locationBias 或 locationRestriction

locationBias

locationRestriction

起源

regionCode

sessionToken

選擇參數來調整結果

Autocomplete (新版) 範例

使用 locationRestriction 將搜尋範圍限制在特定區域

使用 locationBias 將搜尋結果自訂調整為僅限某個區域

使用 includedPrimaryTypes

要求查詢預測

使用來源

回覆缺少距離資訊

試試看！

自動完成 (新推出)