You're all set!

To start developing, please head over to our developer documentation.

Activate the Google Maps Geocoding API

To get you started we'll guide you through the Google Developers Console to do a few things first:

  1. Create or choose a project
  2. Activate the Google Maps Geocoding API
  3. Create appropriate keys
Continue

Best Practices When Geocoding Addresses

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.

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

Ambiguous 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 interactive use-cases: If you have a use case where users may enter ambiguous or incomplete queries (such as “123 Main Street”), we recommend 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 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. Get more information on the Place Autocomplete service for Android, iOS, JavaScript, and the Places API Web Service.

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:

  1. 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.
  2. 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. 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 Web Service.

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.

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 Web Service. See also a JavaScript example of place autocomplete and directions.

Conclusion

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

Send feedback about...

Google Maps Geocoding API
Google Maps Geocoding API
Need help? Visit our support page.