Geocoding is the process of converting addresses (like a street address) into geographic
coordinates (latitude and longitude) that you can use to place markers on a map, or
position the map. The focus of this document is to clarify considerations involved when
geocoding addresses. It describes when it's optimal to use the Geocoding API
and when it's beneficial to use the Places API Place Autocomplete
service.

In general, use the [Geocoding API](https://developers.google.com/maps/documentation/geocoding/geocoding-v4-overview.md.txt)
when geocoding complete addresses (for example, "48 Pirrama Rd, Pyrmont, NSW, Australia").
Use the [Places API
Place Autocomplete service](https://developers.google.com/maps/documentation/places/web-service/autocomplete) when geocoding ambiguous (incomplete) addresses or for
latency-sensitive applications, like when responding to user input.

## Use cases and API recommendations

| Use cases and API recommendations ||
|---|---|
| Physical arrival, advanced destination selection, last-mile delivery, rideshare pickup/dropoff, building entrances, or campus navigation | Use the [**Search for destinations**](https://developers.google.com/maps/documentation/geocoding/search-for-destinations.md.txt) (`SearchDestinations`) method in the Geocoding API v4 to retrieve building entrances, routable navigation points, building outlines, and nearby landmarks. See [Choose a geocoding method](https://developers.google.com/maps/documentation/geocoding/choose-a-method.md.txt). |
| [Respond, in real time, to user input](https://developers.google.com/maps/documentation/geocoding/best-practices.md.txt#user-input) (includes ambiguous, incomplete, poorly formatted, or misspelled addresses entered by a user) | Use the Places API Place Autocomplete service to obtain a place ID, then call [`SearchDestinations`](https://developers.google.com/maps/documentation/geocoding/search-for-destinations.md.txt) (for hyperlocal details) or [`GeocodePlace`](https://developers.google.com/maps/documentation/geocoding/places-geocoding.md.txt) (for basic coordinates). |
| [Automated systems processing complete, unambiguous, postal addresses](https://developers.google.com/maps/documentation/geocoding/best-practices.md.txt#automated-system) (for example, "48 Pirrama Rd, Pyrmont, NSW, Australia") | Use the Geocoding API v4 web service ([`SearchDestinations`](https://developers.google.com/maps/documentation/geocoding/search-for-destinations.md.txt) for hyperlocal details or [`GeocodeAddress`](https://developers.google.com/maps/documentation/geocoding/geocoding.md.txt) for coordinate lookup). |
| [Automated systems processing ambiguous queries](https://developers.google.com/maps/documentation/geocoding/best-practices.md.txt#automated-ambiguous) (for example, incomplete, poorly formatted, or misspelled addresses) | Recommend automated systems use the Geocoding API web service. However, automated systems with a high rate of ambiguous, incomplete or misspelled queries derived from user input may benefit from adding an interactive Place Autocomplete widget to allow users to select a result and thus avoid misspelling an address. |
| [Latency issues](https://developers.google.com/maps/documentation/geocoding/best-practices.md.txt#reduce-latency) using the Directions API (Legacy) or Distance Matrix API (Legacy), with origins, destinations, or waypoints specified as address strings | Reduce geocoding latency by using the Places API Place Autocomplete service to obtain place IDs, then pass the Place IDs to the Directions API (Legacy) or Distance Matrix API (Legacy). |

### Respond to user input

Applications that respond in real-time to user input have two major considerations
that affect the choice of API:

1. User input generally involves entering an address progressively (such as "123 Main Street"), so being able to geocode incomplete, ambiguous addresses is beneficial as it lets the user get a result faster.
2. Applications that respond to user input are highly latency-sensitive.

These two considerations make the [Place Autocomplete service in the Places API](https://developers.google.com/maps/documentation/places/web-service/autocomplete) ideal for
the use case of responding to user input. Place Autocomplete is designed to return
multiple possible options and to allow a user to choose between them. The
Places API can be restricted to search only geocodes or addresses
while excluding businesses. Further, the autocomplete lookup function can be biased
to return results specific to a location. The Places API
returns a [place ID](https://developers.google.com/maps/documentation/places/web-service/place-id.md.txt) which can be passed as a fully
disambiguated location to the Geocoding API web service,
which then returns full address details, and geocodes the address into a
latlng. Place IDs can also be passed to other APIs, such as the
Directions API (Legacy) and Distance Matrix API (Legacy) (see
[Reduce latency](https://developers.google.com/maps/documentation/geocoding/best-practices.md.txt#reduce-latency)).

Address geocoding in the Geocoding API has much higher
latency, and also produces less accurate results for incomplete or
ambiguous queries, so it isn't recommended for applications that have
to respond in real time to user input.

Get more information on the Place Autocomplete service for
[Android](https://developers.google.com/maps/documentation/places/android-sdk/autocomplete),
[iOS](https://developers.google.com/maps/documentation/places/ios-sdk/autocomplete),
[JavaScript](https://developers.google.com/maps/documentation/javascript/places-autocomplete),
and the [Places API](https://developers.google.com/maps/documentation/places/web-service/autocomplete).

### Automated systems

**Automated systems processing complete, unambiguous,
postal addresses** : Unambiguous queries such as complete postal address
strings (for example, "48 Pirrama Rd, Pyrmont, NSW, Australia") are best handled by the
[Geocoding API web
service](https://developers.google.com/maps/documentation/geocoding/start-v4). The address geocoding backend provides greater coverage of addresses globally,
and is optimized for high quality results with these types of complete, unambiguous
queries.

**Automated system processing ambiguous queries** :
Ambiguous queries are those that contain poorly formatted addresses, incomplete
addresses, or spelling mistakes. For automated systems, we recommend using the
[Geocoding API web service](https://developers.google.com/maps/documentation/geocoding/start-v4.md.txt). However, the
Geocoding API isn't designed to cope with ambiguous
queries and might produce less accurate results or zero results in
response to ambiguous queries. If your automated system processes a high
rate of ambiguous queries that are derived from user input, you might
benefit from adding an interactive element to your app using the
[Place Autocomplete service in the Places API](https://developers.google.com/maps/documentation/places/web-service/autocomplete), because
it's designed to return multiple possible options and to allow a user to
choose between them. The Places API returns a
[place ID](https://developers.google.com/maps/documentation/places/web-service/place-id.md.txt) which can be passed as a fully
disambiguated location to the Geocoding API web service, which
then returns full address details, and geocodes the address into a latlng.
Get more information on the Place Autocomplete service for
[Android](https://developers.google.com/maps/documentation/places/android-sdk/autocomplete),
[iOS](https://developers.google.com/maps/documentation/places/ios-sdk/autocomplete),
[JavaScript](https://developers.google.com/maps/documentation/javascript/places-autocomplete),
and the [Places API](https://developers.google.com/maps/documentation/places/web-service/autocomplete).

### Reduce latency for Directions API (Legacy) and
Distance Matrix API (Legacy)

When origins, destinations, or waypoints are specified as address strings, the
[Directions API (Legacy)](https://developers.google.com/maps/documentation/directions/start.md.txt) and
[Distance Matrix API (Legacy)](https://developers.google.com/maps/documentation/distance-matrix/start.md.txt)
use the same backend as the Geocoding API to geocode these addresses
before calculating directions. This significantly increases latency compared to specifying
the same locations as latlngs or [place IDs](https://developers.google.com/maps/documentation/places/web-service/place-id.md.txt).

If your application uses the Directions API (Legacy) or
Distance Matrix API (Legacy) in a latency-sensitive situation such as
responding to user input, and your origins, destinations, or waypoints are initially
specified as address strings, we recommend that you minimize latency by using the Place
Autocomplete service of the Places API to convert address strings to
place IDs, then pass the place IDs to the Directions API (Legacy) or
Distance Matrix API (Legacy). Get more information on the Place Autocomplete
service for [Android](https://developers.google.com/maps/documentation/places/android-sdk/autocomplete),
[iOS](https://developers.google.com/maps/documentation/places/ios-sdk/autocomplete),
[JavaScript](https://developers.google.com/maps/documentation/javascript/places-autocomplete),
and the [Places API](https://developers.google.com/maps/documentation/places/web-service/autocomplete).
See also a [JavaScript example of place autocomplete and directions](https://developers.google.com/maps/documentation/javascript/examples/places-autocomplete-directions.md.txt).

### Conclusion

Depending on your use case, you can use the
Geocoding API alone or combine it with the Place
Autocomplete service. This lets you build apps that offer accurate
geocoding results and reduced latency.

## Manage errors and retries

If you receive `UNKNOWN_ERROR` responses, these are caused by transient errors
and are best dealt with by re-trying after a short delay. We recommend making use of the
Google Maps Platform web services [client libraries](https://developers.google.com/maps/documentation/geocoding/client-library.md.txt) which include retry logic and support Google Maps Platform Premium Plan
authentication.
The [Java Client](https://github.com/googlemaps/google-maps-services-java),
[Python Client](https://github.com/googlemaps/google-maps-services-python),
[Go Client](https://github.com/googlemaps/google-maps-services-go),
and [Node.js Client](https://github.com/googlemaps/google-maps-services-js)
for Google Maps Services are community supported client libraries, available for download
and contributions on GitHub, where you will also find installation instructions and
sample code.

If you get an `OVER_QUERY_LIMIT` status code as a response, you have
[exceeded the usage limits](https://developers.google.com/maps/faq.md.txt#usage-exceed) for the API. We recommend
you try these [usage optimization strategies](https://developers.google.com/maps/documentation/geocoding/geocoding-strategies.md.txt).