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
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 instead.
- You need to calculate a route or ETA to the geocoded destination. Use Routes API instead.
- You need turn-by-turn guidance to a navigation point token in an Android app. Use Navigation SDK for Android instead.
- You need turn-by-turn guidance to a navigation point token in an iOS app. Use Navigation SDK for iOS 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
- Reference: Geocoding API reference
- Pricing: Geocoding API usage and billing
- Policies: Geocoding API policies
- Release notes: Geocoding API release notes
Geocoding API: related products
- Often used with: Routes API, Navigation SDK for Android, Navigation SDK for iOS
Geocoding API: common mistakes
- Problem:
SearchDestinationsrequests without a field mask fail with an error; unlikeGeocodeAddress,GeocodeLocation, andGeocodePlace, the field mask is required. Fix: Set theX-Goog-FieldMaskheader or the$fieldsparameter on everySearchDestinationsrequest. See /maps/documentation/geocoding/choose-fields. - Problem: v4
GeocodeAddresshas no hard component filter (v3components=country:US). Structuredaddress.*parameters are combined into one address and don't filter results;regionCodealso has no default in v4 (v3 defaulted tous). Fix: Filterresultsclient-side: match uppercasedregionCodetopostalAddress.regionCode; match uppercased 2-letter admin areas topostalAddress.administrativeAreaandadministrative_area_level_naddressComponents(shortText); normalize both input andpostalAddress.postalCode(strip spaces/hyphens and apply region rules). See /maps/documentation/geocoding/geocoding-v4-migrate. - Problem: Calling Geocoding API v4 directly from browser JavaScript exposes the API key; HTTP referrer restrictions can be bypassed by forging the
Refererheader. 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. - Problem:
SearchDestinationscan return results that don't have a precise primary address, unlike v3 and the other v4 methods. Fix: SetplaceFilter.addressabilitytoPRIMARYwhen you need only results with precise primary addresses. See /maps/documentation/geocoding/geocoding-v4-migrate. - Problem: Code written for Geocoding API v3 breaks on v4 REST responses: v4 uses lowerCamelCase field names (
addressComponents, notaddress_components), removesstatusanderror_message, and returns a single root object fromGeocodePlaceinstead of aresultsarray. 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.
Geocoding API: legacy and deprecated features
- Geocoding API v3 hyperlocal data (
extra_computations:BUILDING_AND_ENTRANCES,NAVIGATION_POINTS,GROUNDS; response fieldsbuildings.entrances,navigation_points,buildings.building_outlines,grounds): Deprecated since 2025-08-13. Replacement: Geocoding API v4SearchDestinationsmethod (POST /v4/geocode/destinations). See the migration guide.
What you can do with Geocoding API
See the guides linked below for each task, or compare across products in the Capabilities Explorer.
- Return the latitude/longitude coordinates of an address (geocoding).
- Return the address for a set of latitude/longitude coordinates (reverse geocoding).
- Restrict a geocoding request to return results withing a specific viewport. 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. 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. 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.
- Return information about proximity to landmarks or areas for a set of latitude/longitude coordinates.
- Return information about proximity to landmarks or areas for a Google place identifier.
- Return the address for a Google place identifier.
- Return the latitude/longitude coordinates of a building outline for an address.
- Return the latitude/longitude coordinates of a building outline for a set of latitude/longitude coordinates.
- Return the latitude/longitude coordinates of a building outline for a Google Place identifier.
- Return the latitude/longitude coordinates of a building entrance for an address.
- Return the latitude/longitude coordinates of a building entrance for a set of latitude/longitude coordinates.
- Return the latitude/longitude coordinates of a building entrance for a Google Place identifier.