Geocoding API is a web service that converts addresses into coordinates and Place IDs, and converts coordinates or Place IDs into addresses. Its v4 `SearchDestinations` method also returns destination details such as building entrances, navigation points, building and grounds outlines, and nearby landmarks.

## Geocoding API: key facts

- **Product:** Geocoding API
- **Category:** Places
- **Platform:** Web service (REST)
- **Runs on:** Server (backend code)
- **Launch stage:** GA
- **Lifecycle:** Active
- **Overview:** [Geocoding API overview](https://developers.google.com/maps/documentation/geocoding/geocoding-v4-overview.md.txt)

## Geocoding API: when to use it

**Use Geocoding API when:**

- You need to convert a street address into latitude/longitude coordinates and a Place ID on your backend server.
- You need a display address or administrative area (city, postal code) for GPS coordinates or a known Place ID.
- You need building entrances, routable navigation points, or building/grounds outlines to route drivers or couriers to a destination.
- You need to resolve a destination inside a large complex (airport, mall, campus) into sub-destinations or nearby landmarks.
**Don't use Geocoding API when:**

- You need geocoding from client-side browser JavaScript; calling v4 with an exposed API key is a security risk. Use [Maps JavaScript API](https://developers.google.com/maps/documentation/javascript/quick-reference.md.txt) instead.
- You need to calculate a route or ETA to the geocoded destination. Use [Routes API](https://developers.google.com/maps/documentation/routes/quick-reference.md.txt) instead.
- You need turn-by-turn guidance to a navigation point token in an Android app. Use [Navigation SDK for Android](https://developers.google.com/maps/documentation/navigation/android-sdk/quick-reference.md.txt) instead.
- You need turn-by-turn guidance to a navigation point token in an iOS app. Use [Navigation SDK for iOS](https://developers.google.com/maps/documentation/navigation/ios-sdk/quick-reference.md.txt) instead.

## Geocoding API: setup

- **Service to enable:** `geocoding-backend.googleapis.com`
- **Authentication:** API key, OAuth 2.0, Service account
- **Get started:** [Set up Geocoding API](https://developers.google.com/maps/documentation/geocoding/get-api-key-v4.md.txt)
- **Reference:** [Geocoding API reference](https://developers.google.com/maps/documentation/geocoding/reference/rest.md.txt)
- **Pricing:** [Geocoding API usage and billing](https://developers.google.com/maps/documentation/geocoding/usage-and-billing.md.txt)
- **Policies:** [Geocoding API policies](https://developers.google.com/maps/documentation/geocoding/policies.md.txt)
- **Release notes:** [Geocoding API release notes](https://developers.google.com/maps/documentation/geocoding/release-notes.md.txt)

## Geocoding API: related products

- **Often used with:** [Routes API](https://developers.google.com/maps/documentation/routes/quick-reference.md.txt), [Navigation SDK for Android](https://developers.google.com/maps/documentation/navigation/android-sdk/quick-reference.md.txt), [Navigation SDK for iOS](https://developers.google.com/maps/documentation/navigation/ios-sdk/quick-reference.md.txt)

## Geocoding API: common mistakes

- **Problem:** `SearchDestinations` requests without a field mask fail with an error; unlike `GeocodeAddress`, `GeocodeLocation`, and `GeocodePlace`, the field mask is required. **Fix:** Set the `X-Goog-FieldMask` header or the `$fields` parameter on every `SearchDestinations` request. See [/maps/documentation/geocoding/choose-fields](https://developers.google.com/maps/documentation/geocoding/choose-fields.md.txt).
- **Problem:** v4 `GeocodeAddress` has no hard component filter (v3 `components=country:US`). Structured `address.*` parameters are combined into one address and don't filter results; `regionCode` also has no default in v4 (v3 defaulted to `us`). **Fix:** Filter `results` client-side: match uppercased `regionCode` to `postalAddress.regionCode`; match uppercased 2-letter admin areas to `postalAddress.administrativeArea` and `administrative_area_level_n` `addressComponents` (`shortText`); normalize both input and `postalAddress.postalCode` (strip spaces/hyphens and apply region rules). See [/maps/documentation/geocoding/geocoding-v4-migrate](https://developers.google.com/maps/documentation/geocoding/geocoding-v4-migrate.md.txt).
- **Problem:** Calling Geocoding API v4 directly from browser JavaScript exposes the API key; HTTP referrer restrictions can be bypassed by forging the `Referer` header. **Fix:** Call v4 from your own backend with a protected key, or use the Maps JavaScript API Geocoding Service (v3 backend) for client-side needs. See [/maps/documentation/geocoding/geocoding-v4-migrate](https://developers.google.com/maps/documentation/geocoding/geocoding-v4-migrate.md.txt).
- **Problem:** `SearchDestinations` can return results that don't have a precise primary address, unlike v3 and the other v4 methods. **Fix:** Set `placeFilter.addressability` to `PRIMARY` when you need only results with precise primary addresses. See [/maps/documentation/geocoding/geocoding-v4-migrate](https://developers.google.com/maps/documentation/geocoding/geocoding-v4-migrate.md.txt).
- **Problem:** Code written for Geocoding API v3 breaks on v4 REST responses: v4 uses lowerCamelCase field names (`addressComponents`, not `address_components`), removes `status` and `error_message`, and returns a single root object from `GeocodePlace` instead of a `results` array. **Fix:** Check HTTP status codes and error bodies on v4 REST calls, read lowerCamelCase fields (`addressComponents`, `postalAddress`), and note that gRPC responses still use snake_case. See [/maps/documentation/geocoding/geocoding-v4-migrate](https://developers.google.com/maps/documentation/geocoding/geocoding-v4-migrate.md.txt).

## Geocoding API: legacy and deprecated features

- **Geocoding API v3 hyperlocal data (`extra_computations`: `BUILDING_AND_ENTRANCES`, `NAVIGATION_POINTS`, `GROUNDS`; response fields `buildings.entrances`, `navigation_points`, `buildings.building_outlines`, `grounds`):** Deprecated since 2025-08-13. **Replacement:** Geocoding API v4 `SearchDestinations` method (`POST /v4/geocode/destinations`). See the [migration guide](https://developers.google.com/maps/documentation/geocoding/geocoding-v4-migrate.md.txt).

## What you can do with Geocoding API

See the guides linked below for each task, or compare across products in the
[Capabilities Explorer](https://developers.google.com/maps/documentation/capabilities-explorer.md.txt).

- [Return the latitude/longitude coordinates of an address (geocoding).](https://developers.google.com/maps/documentation/geocoding/geocoding.md.txt)
- [Return the address for a set of latitude/longitude coordinates (reverse geocoding).](https://developers.google.com/maps/documentation/geocoding/reverse-geocoding.md.txt)
- [Restrict a geocoding request to return results withing a specific viewport.](https://developers.google.com/maps/documentation/geocoding/geocoding.md.txt#Viewports) **Note:** In Geocoding API v4, locationBias biases results toward the specified viewport rather than strictly restricting them.
- [Restrict a geocoding or reverse geocoding request to only return results within a specific region, country, or postal code.](https://developers.google.com/maps/documentation/geocoding/geocoding.md.txt#RegionCodes) **Note:** In Geocoding API v4, regionCode biases results toward a specified CLDR region rather than strictly restricting them; for legacy v3 component filtering by country or postal code, see https://developers.google.com/maps/documentation/geocoding/guides-v3/requests-geocoding#ComponentFiltering.
- [Restrict a reverse geocoding request to only return results for specified address types.](https://developers.google.com/maps/documentation/geocoding/reverse-geocoding.md.txt#types) **Note:** In Geocoding API v4, the types parameter filters returned reverse-geocoding results by address type after search rather than restricting the underlying search.
- [Return information about proximity to landmarks or areas for an address.](https://developers.google.com/maps/documentation/geocoding/search-for-destinations.md.txt)
- [Return information about proximity to landmarks or areas for a set of latitude/longitude coordinates.](https://developers.google.com/maps/documentation/geocoding/search-for-destinations.md.txt)
- [Return information about proximity to landmarks or areas for a Google place identifier.](https://developers.google.com/maps/documentation/geocoding/search-for-destinations.md.txt)
- [Return the address for a Google place identifier.](https://developers.google.com/maps/documentation/geocoding/places-geocoding.md.txt)
- [Return the latitude/longitude coordinates of a building outline for an address.](https://developers.google.com/maps/documentation/geocoding/search-for-destinations.md.txt)
- [Return the latitude/longitude coordinates of a building outline for a set of latitude/longitude coordinates.](https://developers.google.com/maps/documentation/geocoding/search-for-destinations.md.txt)
- [Return the latitude/longitude coordinates of a building outline for a Google Place identifier.](https://developers.google.com/maps/documentation/geocoding/search-for-destinations.md.txt)
- [Return the latitude/longitude coordinates of a building entrance for an address.](https://developers.google.com/maps/documentation/geocoding/search-for-destinations.md.txt)
- [Return the latitude/longitude coordinates of a building entrance for a set of latitude/longitude coordinates.](https://developers.google.com/maps/documentation/geocoding/search-for-destinations.md.txt)
- [Return the latitude/longitude coordinates of a building entrance for a Google Place identifier.](https://developers.google.com/maps/documentation/geocoding/search-for-destinations.md.txt)