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 Google Maps Geocoding API and when it’s beneficial to use the Places API Place Autocomplete service or the Places API Text Search service.
In general, use the Google Maps 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 high-latency scenarios, like when responding to user input. When geocoding ambiguous addresses in automated systems when there is no user to select an item from the autocomplete suggestions, use the Places API Text Search service instead of Place Autocomplete.
Use cases and API recommendations
|Use case||API recommendation|
|Complete, unambiguous, postal addresses||Google Maps Geocoding API web service|
|Ambiguous queries entered by a user (for example, incomplete or poorly formatted addresses)||Places API Place Autocomplete service to obtain a place ID, then the Geocoding API to geocode the place ID into a latlng.|
|Ambiguous queries in an automated system (for example, incomplete or poorly formatted addresses)||Places API Text Search service.|
|Respond, in real time, to user input||Places API Place Autocomplete service to obtain a place ID, then the Geocoding API to geocode the place ID into a latlng.|
|Latency issues using the Google Maps 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.|
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.
Ambiguous queries are those that contain poorly formatted addresses, incomplete addresses, or superfluous address components. The Geocoding API web service geocoder is not designed to cope with ambiguous queries and may produce less accurate results or zero results in response to ambiguous queries, particularly in the case of queries containing multiple spelling mistakes or extraneous non-address terms.
For automated use-cases: If you need to use address geocoding in an automated system where there is no user to select from multiple possible results, but queries might be ambiguous, incomplete, or contain extraneous non-address components such as business names, we recommend using the Places API Text Search service instead of the Place Autocomplete service. The Place Autocomplete service is designed to match every single term in the query, and ultimately will return no suggestions if there is a term that cannot be matched. The Place Text Search service is better at dealing with extraneous terms, partly because these are often additional details about a business listing, which Text Search can match to the right result. Place Search lets you restrict your search to a specified area, or rank results by distance, allowing more precise filtering and ranking of results for ambiguous or incomplete queries.
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, 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.
Reducing latency for Directions API and Distance Matrix API
When origins, destinations, or waypoints are specified as address strings, the Google Maps 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.
Depending on your use case, when geocoding addresses, using the Geocoding API or the Places API, or using the Place Autocomplete service or Place Search 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 APIs web services
client libraries which include retry logic and support Google Maps APIs Premium Plan
The Java 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