<br />

> [!WARNING]
> 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](https://cloud.google.com/maps-platform/terms/maps-service-terms). For more information, see the [launch stage descriptions](https://developers.google.com/maps/launch-stages.md.txt).

<br />

**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).

The [`GeocodeAddress`](https://developers.google.com/maps/documentation/geocoding/reference/rest/v4alpha/geocode.address/geocodeAddress.md.txt)
and [`SearchDestinations`](https://developers.google.com/maps/documentation/geocoding/reference/rest/v4alpha/geocode.destinations/searchDestinations.md.txt)
methods support an optional `effort` parameter that lets you control the
trade-off between response latency and address resolution accuracy.

While standard geocoding handles well-formatted postal addresses in sub-second
latency, real-world inputs are often incomplete, informal, or complex (for
example, `"Flat 4B, Sunrise Apartments, opposite Central Mall, Andheri West,
Mumbai"` or `"where the warriors play, sf"`). By configuring a higher `effort`
level, you can instruct the Geocoding API to apply extended reasoning and
disambiguation to resolve difficult addresses.

> [!IMPORTANT]
> **Important:** This feature is available in the `v4alpha` channel. [More information
> about launch stage channels](https://developers.google.com/maps/documentation/geocoding/geocoding-v4-overview#launch_stage_channels).

## Effort levels

Specify one of the following values for the `effort` parameter:

| Effort level | Description | Typical latency | Recommended use cases |
|---|---|---|---|
| `EFFORT_UNSPECIFIED` | Default value. Behaves the same as `LOW` effort. | Sub-second | Default standard geocoding. |
| `LOW` | Optimizes for the fastest response times. Does not perform extended search or disambiguation for difficult addresses. | Sub-second | Real-time interactive lookup, high-volume standard address validation. |
| `MEDIUM` | Balances speed and accuracy. Most requests return with standard low latency. For ambiguous or difficult addresses, the service applies additional processing to improve accuracy, which might take up to a few seconds. | Sub-second for standard addresses; up to a few seconds (≤ 4 seconds) for ambiguous addresses | Interactive user workflows (such as address confirmation at checkout) where users can tolerate a brief pause. |
| `HIGH` | Maximizes address resolution accuracy for incomplete, informal, or complex addresses. Response times might be significantly longer. | Up to 20 seconds for complex addresses | Background processing, batch geocoding, logistics dispatch, or asynchronous post-checkout address refinement. |

> [!NOTE]
> **Note:** The `MEDIUM` and `HIGH` effort levels use Gemini models to process and disambiguate complex addresses. Responses are resolved using AI and may make mistakes.

## Request examples

### Search for destinations (`SearchDestinations`)

Include the `effort` field in the JSON request body of your `POST` request to
`https://geocode.googleapis.com/v4alpha/geocode/destinations`. The `effort`
parameter primarily affects [`addressQuery`](https://developers.google.com/maps/documentation/geocoding/reference/rest/v4alpha/geocode.destinations/searchDestinations.md.txt#SearchDestinationsRequest.AddressQuery)
resolution:

```curl
curl -X POST -d '{
  "addressQuery": {
    "addressQuery": "Flat 4B, Sunrise Apartments, opposite Central Mall, Andheri West, Mumbai"
  },
  "effort": "HIGH"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations
```

### Geocode an address (`GeocodeAddress`)

Pass the `effort` parameter as a URL query parameter in your `GET` request to
the `/v4alpha/` endpoint:

```curl
curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4alpha/geocode/address/where+the+warriors+play,+sf?effort=MEDIUM"
```

## Mitigating latency impact

When using `MEDIUM` or `HIGH` effort in your application, sending a single-pass
request is the simplest integration, but requests in these modes can incur
higher latency, which can delay synchronous, user-facing, and latency-sensitive
workflows.

To mitigate this latency impact on interactive user flows (such as checkout or
booking), you can use a multi-pass workflow:

1. **Pass 1 (Interactive):** Send a synchronous request with `effort=LOW` (or default) to validate the address immediately with sub-second latency.
2. **Pass 2 (Background):** Send an asynchronous follow-up request with `effort=MEDIUM` or `effort=HIGH` (for example, post-checkout or before dispatch) to resolve complex addresses into high-precision coordinates, entrances, and navigation points without blocking the user.

## Usage limits

During the Experimental (`v4alpha`) launch stage, requests with `effort` set to
`MEDIUM` or `HIGH` are subject to stricter rate limits than standard (`LOW`)
requests. If your application exceeds these rate limits, the API returns a
`RESOURCE_EXHAUSTED` (`HTTP 429`) error. If you encounter `HTTP 429` errors or
require higher quota for your use case, contact us through the
[feedback channel](https://developers.google.com/maps/documentation/geocoding/geocoding-effort.md.txt#feedback).

## Feedback

This is an experimental feature of the Geocoding API. We would appreciate
feedback at
[geocoding-feedback-channel@google.com](mailto:geocoding-feedback-channel@google.com).