Migrate to Nearby Search (New)

Places API supports the existing Nearby Search. If you are familiar with the existing Nearby Search, the new version of Nearby Search makes the following changes:

  • The new Nearby Search uses HTTP POST requests. Pass parameters in the request body or in headers as part of an HTTP POST request. In contrast, with the existing Nearby Search, you pass URL parameters using an HTTP GET request.
  • Field masking is required. You must specify which fields you want returned in the response. There is no default list of returned fields. If you omit this list, the methods return an error. For more information, see FieldMask.
  • The new Nearby Search supports both API keys and OAuth tokens as the authentication mechanism.
  • Only JSON is supported as a response format in the new Nearby Search.
  • All requests that include a text query should now use Text Search (New) because Nearby Search (New) does not support text input.
  • The JSON response format for the Nearby Search (New) API has changed from the format of the existing APIs. For more details, see Migrate the Places API response.

The following table lists parameters in the existing Nearby Search that have been renamed or modified for the new Nearby Search, or parameters that are no longer supported.

Current parameter New parameter Notes
keyword Not supported. Use Text Search (New) instead.
language languageCode
location locationRestriction Required.
maxprice/minprice Not supported.
maxResultCount New parameter.
opennow Not supported.
pagetoken Not supported.
radius Use locationRestriction now.
rankby rankPreference
regionCode New parameter.
type includedTypes
excludedTypes
includedPrimaryTypes
excludedPrimaryTypes
The new parameters also accept multiple type values. The existing API only accepts a single value.

Example request

The following example GET request uses the existing Nearby Search. In this example, you request a JSON response containing information about places of type restaurant and pass all parameters as URL parameters:

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'

With Nearby Search (New), you make a POST request and pass all parameters in the JSON request body or in headers as part of the POST request. This example also uses a field mask so the response only includes the display name and formatted address of the place:

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