Places API 支援現有的 Nearby Search。如果您熟悉現有的 Nearby Search,新版的 Nearby Search 會產生下列變更:
- 新的 Nearby Search 會使用 HTTP POST 要求。將參數傳入要求主體或標頭,做為 HTTP POST 要求的一部分。相較之下,針對現有的 Nearby Search,您可以使用 HTTP GET 要求傳送網址參數。
- 必須指定欄位遮罩。您必須指定要在回應中傳回的欄位。沒有預設的傳回欄位清單。如果省略這份清單,這些方法就會傳回錯誤。詳情請參閱 FieldMask。
- 全新的 Nearby Search 支援以 API 金鑰和 OAuth 權杖做為驗證機制。
- 新版「附近搜尋」功能僅支援 JSON 做為回應格式。
- 包含文字查詢的所有要求現在都應使用 Text Search (New),因為 Nearby Search (新版) 不支援文字輸入內容。
- Nearby Search (新版) API 的 JSON 回應格式與現有 API 的格式已變更。詳情請參閱「遷移 Places API 回應」。
下表列出在現有 Nearby Search 中,為新的 Nearby Search 重新命名或修改的參數,以及不再支援的參數。
目前的參數 | 新增參數 | 附註 |
---|---|---|
keyword |
不支援。請改用文字搜尋 (新推出)。 | |
language |
languageCode |
|
location |
locationRestriction |
這是必填欄位。 |
maxprice/minprice |
|
不支援。 |
maxResultCount |
新參數。 | |
opennow |
|
不支援。 |
pagetoken |
不支援。 | |
radius |
|
立即使用 locationRestriction 。 |
rankby |
rankPreference |
|
regionCode |
新參數。 | |
type |
includedTypes excludedTypes includedPrimaryTypes excludedPrimaryTypes
|
新參數也接受多種類型值。現有的 API 只接受單一值。 |
要求範例
以下 GET 要求範例會使用現有的 Nearby Search。在這個範例中,您會要求 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'
使用 Nearby Search (新) 時,可以發出 POST 要求,並做為 POST 要求的一部分傳遞 JSON 要求主體或標頭中的所有參數。本例也會使用欄位遮罩,因此回應只會包含地點的顯示名稱和格式化地址:
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