Geocoding is the process of converting addresses (like a street address) into geographic coordinates (latitude and longitude), which 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 when geocoding complete addresses (for example, “48 Pirrama Rd, Pyrmont, NSW, Australia”). Use the Places API Place Autocomplete service 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 | |
---|---|
Respond, in real time, to 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 the Geocoding API to geocode the place ID into a latlng. |
Automated systems processing complete, unambiguous, postal addresses (for example, “48 Pirrama Rd, Pyrmont, NSW, Australia”) | Use the Geocoding API web service. |
Automated systems processing ambiguous queries (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 using the Directions API or Distance Matrix API, 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 or Distance Matrix API. |
Responding to user input
Applications that respond in real-time to user input have two major considerations that affect the choice of API:
- 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.
- Applications that respond to user input are highly latency-sensitive.
These two considerations make the Place Autocomplete service in the Places API 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 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 and Distance Matrix API (see below).
Address geocoding in the Geocoding API has much higher latency, and also produces less accurate results for incomplete or ambiguous queries, so it is not recommended for applications that have to respond in real-time to user input.
Get more information on the Place Autocomplete service for Android, iOS, JavaScript, and the Places API.
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. 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. However, the Geocoding API is not designed to cope with ambiguous queries and may 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 may benefit from adding an interactive element to your app using the Place Autocomplete service in the Places API, since it is designed to return multiple possible options and to allow a user to choose between them. The Places API returns a place ID 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, iOS, JavaScript, and the Places API.
Reducing latency for Directions API and Distance Matrix API
When origins, destinations, or waypoints are specified as address strings, the Directions API and Distance Matrix API 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.
If your application uses the Directions API or Distance Matrix API 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 or Distance Matrix API. Get more information on the Place Autocomplete service for Android, iOS, JavaScript, and the Places API. See also a JavaScript example of place autocomplete and directions.
Conclusion
Depending on your use case, when geocoding addresses, using the Geocoding API or using the Place Autocomplete service in combination with the Geocoding API allows you to create applications that offer users accurate geocoding results as well as reduced latency.
Managing 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 which include retry logic and support Google Maps Platform Premium Plan
authentication.
The Java Client,
Python Client,
Go Client,
and Node.js Client
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 for the API. We recommend
you try these
usage optimization strategies.