Geocoding API quick reference

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

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.
  • 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.
  • 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.
  • 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.
  • 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.

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.

What you can do with Geocoding API

See the guides linked below for each task, or compare across products in the Capabilities Explorer.