Choose fields to return

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.

When you make a geocoding request, you can use afield mask to specify thelist of fields to return in the response. For theGeocode an address,Geocode a location, andPlace geocoding endpoints, allfields in the response object are returned by default. For theSearch for destinationsendpoint, you must specify a field mask in the API request.

Use a field mask to ensure that you don't request unnecessary data, which inturn helps with response latency.

Define a response field mask

The response field mask is a comma-separated list of paths with no spaces, whereeach path specifies a unique field in the response object. The path starts fromthe top-level response field and uses a dot-separated path to a specifiedfield.

Note: Don't use spaces anywhere in the list of field paths.

Pass the response field mask to a request by using the URL parameter$fieldsorfields, or by using the HTTP or gRPC headerX-Goog-FieldMask.

Example field masks

Shown below is the complete response from a forward geocoding request:

{"results":[{"place":"//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE","placeId":"ChIJF4Yf2Ry7j4AR__1AkytDyAE","location":{"latitude":37.422010799999995,"longitude":-122.08474779999999},"granularity":"ROOFTOP","viewport":{"low":{"latitude":37.420656719708511,"longitude":-122.08547523029148},"high":{"latitude":37.4233546802915,"longitude":-122.0827772697085}},"formattedAddress":"1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",...}

Construct your field masks using the hierarchy of the response fields, in theform:

topLevelField[.secondLevelField][.thirdLevelField][...]
Note: By default, the request returns all fields in the response object which isequivalent to specifying a field mask of *.

For example, to return only theplaceId field in the response, use a fieldmask of:

curl -X GET -H 'Content-Type: application/json' \-H 'X-Goog-FieldMask: results.placeId' \-H "X-Goog-Api-Key:API_KEY" \"https://"geocode.googleapis.com/v4beta/"geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

The response is now:

{"results":[{"placeId":"ChIJF4Yf2Ry7j4AR__1AkytDyAE"}]}

To return theviewport field, your field mask is:

-H 'X-Goog-FieldMask: results.viewport'

The response is now:

{"results":[{"viewport":{"low":{"latitude":37.420654569708496,"longitude":-122.08547618029148},"high":{"latitude":37.423352530291496,"longitude":-122.0827782197085}}}]}

To return both:

-H 'X-Goog-FieldMask: results.placeId,results.viewport'

The response is now:

{"results":[{"placeId":"ChIJF4Yf2Ry7j4AR__1AkytDyAE","viewport":{"low":{"latitude":37.420654569708496,"longitude":-122.08547618029148},"high":{"latitude":37.423352530291496,"longitude":-122.0827782197085}}}]}

gRPC field masks

For gRPC, set a variable containing the response field mask. You can then passthat variable to the request.

const(fieldMask="results.placeId,results.viewport")

Field path considerations

Include only the fields that you require in the response to return just thefields that you need:

  • Decreases processing times, so your results are returned with a lowerlatency.
  • Ensures stable latency performance. If you select all fields, or if youselect all fields at the top level, you might experience performancedegradation when new fields are added and then are automatically included inyour response.
  • Results in a smaller response size, which translates into higher networkthroughput.

For more details on constructing a field mask, see thefield_mask.proto.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-11-21 UTC.