Migrate from v3 features to the SearchDestinations endpoint

This product or feature is Experimental (pre-GA). Pre-GA products and features might have limited support, and changes to pre-GA products and features might not be compatible with other pre-GA versions. Pre-GA Offerings are covered by the Google Maps Platform Service Specific Terms. For more information, see the launch stage descriptions.

European Economic Area (EEA) developers

If your billing address is in the European Economic Area, effective on 8 July 2025, the Google Maps Platform EEA Terms of Service will apply to your use of the Services. Functionality varies by region. Learn more.

The following features in the Geocoding API v3 are being replaced by the SearchDestinations endpoint of the Geocoding API v4:

• Entrances
• Navigation points
• Building outlines
• Grounds

If you were using the Geocoding API v3 for the above features, use this document to help you use the SearchDestinations endpoint instead to get these features. This document explains where in the SearchDestinations API response to find these features, and differences in how these features are represented in the API responses between the Geocoding API v3 and the SearchDestinations endpoint of the Geocoding API v4.

Entrances

To get the entrances associated with a destination, use the field destination.entrances.

Note that the format of an entrance is slightly different from the entrance format in the Geocoding API v3. Each entrance in destination.entrances has the following fields:

• displayName - this is a new optional field that will have a human readable name for the entrance, for example "Gate B".
• location - this is a location of type LatLng, which is different from the format used in the Geocoding API v3.
• tags - this is the same as the tags field of the entrances from the Geocoding API v3.
• place - analogous to the buildingPlaceId field of the entrances from the Geocoding API v3. However, the Place ID in this field could be for a Place of any type, not necessarily just a building.

Navigation points

To get the navigation points associated with a destination, use the field destination.navigationPoints.

Note that the format of a navigationPoint is slightly different from the navigation point format in the Geocoding API v3. Each navigation point in destination.navigationPoints has the following fields:

• displayName - this is a new optional field that will have a human readable name for the navigation point, for example "5th Ave".
• location - this is a location of type LatLng, which is different from the format used in the Geocoding API v3.
• travelModes - this is similar to the restrictedTravelModes field of the navigation points from the Geocoding API v3. The possible enum values are the same, the only difference is that this field now represents the acceptable travel modes for the navigation point, rather than the restricted travel modes.
• usage - this is a new field which contains the use cases supported by the navigation point. Note that most navigation points will have an UNKNOWN usage, but that does not necessarily mean the navigation point's usage is restricted in any way.

Building outlines

To get the building outlines associated with a destination, you should use the displayPolygon field of the placeView objects in the destination that represent buildings. For each placeView, you can check if it is a building with the placeView.structureType field. If the structure type is BUILDING, you can get the outline from the placeView.displayPolygon field. The placeView will also have additional fields for the building that were not in the Geocoding API v3.

A destination can have a placeView object that represents a building in the following fields:

• destination.primary - this is the primary place for the destination.
• destination.containingPlaces - this is a repeated field that can hold larger places that "contain" the primary place. For example, if the primary place is a subpremise, containingPlaces will usually hold the placeView representing the building.
• destination.subDestinations - this is a repeated field that can hold sub-destinations of the primary place. For example, individual apartment units of a building. This field won't typically have a placeView representing a building.

Note that the format of placeView.displayPolygon matches the building outline format in the Geocoding API v3, which is the GeoJSON format, using the RFC 7946 format.

Grounds

Similar to building outlines, to get the grounds associated with a destination, you should use the displayPolygon field of the placeView objects in the destination that represent grounds. For each placeView, you can check if it is a grounds with the placeView.structureType field. If the structure type is GROUNDS, you can get the outline from the placeView.displayPolygon field. The placeView will also have additional fields for the grounds that were not in the Geocoding API v3.

A destination can have a placeView object that represents a grounds in the following fields:

• destination.primary
• destination.containingPlaces
• destination.subDestinations

Note that the format of placeView.displayPolygon matches the grounds outline format in the Geocoding API v3, which is the GeoJSON format, using the RFC 7946 format.

Use a field mask to request these features

The SearchDestinations endpoint requires a field mask, as explained in Choose fields to return. The field mask can be set to * in order to return all fields, or you can set it to the specific fields you want to receive. For example, the following API request sets the field mask to receive all fields required to get the entrances, navigation points, building outlines, and grounds of a destination:

curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
  -H "X-Goog-Api-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary,destinations.containingPlaces,destinations.subDestinations" \
  https://geocode.googleapis.com/v4alpha/geocode/destinations