**European Economic Area (EEA) developers**

> [!NOTE]
> If your billing address is in the European Economic Area, effective on 8 July 2025, the [Google Maps Platform EEA Terms of Service](https://cloud.google.com/terms/maps-platform/eea) will apply to your use of the Services. Functionality varies by region. [Learn more](https://developers.google.com/maps/comms/eea/faq.md.txt).

When you make a geocoding request, you can use a *field mask* to specify the
list of fields to return in the response. Field masks help with response latency
by ensuring you don't request unnecessary data.

For basic geocoding methods ([Geocode an
address](https://developers.google.com/maps/documentation/geocoding/geocoding), [Geocode a
location](https://developers.google.com/maps/documentation/geocoding/reverse-geocoding), and [Place
geocoding](https://developers.google.com/maps/documentation/geocoding/places-geocoding)), all fields in the
response object are returned by default, unlike [Search for
destinations](https://developers.google.com/maps/documentation/geocoding/search-for-destinations) where
specifying a field mask is required. While a field mask isn't required for basic
methods, we strongly encourage you to use one to reduce response latency.

> [!IMPORTANT]
> **Important:** You must specify a field mask when using the [Search for destinations](https://developers.google.com/maps/documentation/geocoding/search-for-destinations.md.txt) method.

## Define a response field mask

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

> [!NOTE]
> **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 `$fields`
or `fields`, or by using the HTTP or gRPC header `X-Goog-FieldMask`.

## Example field masks

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

```json
{
  "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 the
form:

```
topLevelField[.secondLevelField][.thirdLevelField][...]
```

> [!NOTE]
> **Note:** For the `GeocodeAddress`, `GeocodeLocation`, and `GeocodePlace` methods, the request returns all fields in the response object by default (equivalent to specifying a field mask of `*`). For the `SearchDestinations` method, specifying a field mask is **required**; omitting the field mask results in an error.

### Search for destinations field masks

When calling [`SearchDestinations`](https://developers.google.com/maps/documentation/geocoding/search-for-destinations.md.txt),
specify the exact destination attributes you need, such as the primary place
details, entrances, navigation points, building outlines (`displayPolygon`), and
landmarks:

```
curl -X POST -d '{"addressQuery": {"addressQuery": "1600 Amphitheatre Pkwy, Mountain View, CA"}}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: destinations.primary.displayName,destinations.primary.displayPolygon,destinations.entrances,destinations.navigationPoints,destinations.landmarks' \
-H "X-Goog-Api-Key: API_KEY" \
https://geocode.googleapis.com/v4/geocode/destinations
```

### Core geocoding field masks

For example, to return only the `placeId` field in a `GeocodeAddress`
response, use a field mask 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/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA
```

The response is now:

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

To return the `viewport` field, your field mask is:

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

The response is now:

```json
{
  "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:

```json
{
  "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 pass
that 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 the
fields that you need:

- **Decreases processing times**, so your results are returned with a lower latency.
- **Ensures stable latency performance**. If you select all fields, or if you select all fields at the top level, you might experience performance degradation when new fields are added and then are automatically included in your response.
- **Results in a smaller response size**, which translates into higher network throughput.

For more details on constructing a field mask, see the
[field_mask.proto](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/field_mask.proto).