遷移至 Nearby Search (新功能)

Places API 支援現有的搜尋附近地點功能。如果您熟悉現有的 Nearby Search，新版 Nearby Search 會進行以下變更：

  • 新的附近搜尋功能會使用 HTTP POST 要求。在要求主體或標頭中，將參數傳遞為 HTTP POST 要求的一部分。相較之下，您可以使用 HTTP GET 要求傳遞現有的附近搜尋網址參數。
  • 必須使用欄位遮蓋功能。您必須指定要回傳哪些欄位。系統不會提供傳回欄位的預設清單。如果您省略這個清單，方法會傳回錯誤。詳情請參閱 FieldMask。
  • 新的鄰近搜尋功能支援使用 API 金鑰和 OAuth 權杖做為驗證機制。
  • 新版附近搜尋功能僅支援 JSON 回應格式。
  • 由於 Nearby Search (新版) 不支援文字輸入，因此現在所有包含文字查詢的請求都應使用 Text Search (新版)。
  • 搜尋附近地點 (新版) API 的 JSON 回應格式已與現有 API 的格式有所不同。詳情請參閱「遷移 Places API 回應」。

下表列出現有附近搜尋功能中，已為新版附近搜尋功能重新命名或修改的參數，或不再支援的參數。

目前的參數 新增參數 附註
keyword 不支援。請改用「文字搜尋 (新版)」。
language languageCode
location locationRestriction 必填。
maxprice/minprice 不支援。
maxResultCount 新參數。
opennow 不支援。
pagetoken 不支援。
radius 立即使用 locationRestriction。
rankby rankPreference
regionCode 新參數。
type includedTypes
excludedTypes
includedPrimaryTypes
excludedPrimaryTypes 		新的參數也接受多種類型值。現有的 API 只接受單一值。

要求範例

下列範例 GET 要求會使用現有的附近搜尋功能。在這個範例中，您會要求 JSON 回應，其中包含 restaurant 類型地點的相關資訊，並將所有參數設為網址參數：

curl -L -X GET \
'https://maps.googleapis.com/maps/api/place/nearbysearch/json?location=37.7937%2C-122.3965&radius=500&type=restaurant&key=API_KEY'

使用附近搜尋 (新版) 時，您可以建立 POST 要求，並在 JSON 要求主體或標頭中傳遞所有參數，做為 POST 要求的一部分。這個範例也會使用欄位遮罩，因此回應只會包含地點的顯示名稱和格式化地址：

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.formattedAddress" \
https://places.googleapis.com/v1/places:searchNearby