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

New Forward Geocoder FAQ

This FAQ covers questions specific to the new forward geocoder that was announced in the blog post Address Geocoding in the Google Maps APIs. See also Best Practices When Geocoding Addresses.

Please refer to the Google Maps APIs FAQ for questions common to all Google Maps APIs.

Getting Started

Troubleshooting

Getting Started

When did the new forward geocoder become the default?
  • For unidentified requests and Standard Plan customers using the Google Maps Geocoding API and/or making requests to the geocoding service of the Google Maps JavaScript API, the new forward geocoder became the default in early December, 2016. For other APIs — the Google Maps Directions API, Google Maps Distance Matrix API, Google Static Maps API, and Google Street View Image API, and for Google Maps JavaScript API requests to the directions and distance matrix services — the new forward geocoder became the default in mid-January, 2017.
  • For Premium Plan customers using the above-named APIs, the new forward geocoder became the default on February 8, 2017.
  • The old geocoder was permanently retired on April 3, 2017.
Which APIs will be using the new forward geocoder?

The following Google Maps APIs make use of the same geocoder, for the following requests:

Note: The new forward geocoder is never used when retrieving details for a Place ID.

Why is this change happening?

The new forward geocoder is the same as the one used by the consumer Google Maps application. The old geocoder is deprecated and will be retired.

Is this change backwards compatible?

Yes, the Geocoding API retains the same request and response format. The new geocoder may produce a different set of results for many queries, but requests continue to work in their current format, and the new results return the same fields.

Will requests fail if they contain the new_forward_geocoder parameter once the old forward geocoder is retired?

No. Requests will continue to work after the old forward geocoder is permanently retired on April 3, 2017, even if the requests contain the new_forward_geocoder or newForwardGeocoder parameter. The API will ignore the parameter and will use the new forward geocoder regardless of the value of the parameter.

Troubleshooting

I’m getting more queries that return ZERO_RESULTS with the new geocoder. What’s going on?

In the new geocoder, ambiguous, incomplete and badly formatted queries, such as misspelled or nonexistent addresses, are prone to produce ZERO_RESULTS. These queries would typically produce incorrect results in the old geocoder, such as returning the suburb if the address could not be found. We believe that returning ZERO_RESULTS is actually a more correct response in such situations.

If your application deals with user input of addresses, the Place Autocomplete feature in the Places API may produce better quality results. Place Autocomplete allows users to select from a set of results based on what they’ve typed, which allows users to choose between similarly named results, and to adjust their query if they misspell an address.

If you have an application dealing with ambiguous or incomplete queries or queries that may contain errors, we recommend you use the Place Autocomplete feature in the Places API rather than the forward geocoder available in the Geocoding API. For more details, see Best Practices When Geocoding Addresses and the Address Geocoding in the Google Maps APIs blog post.

I need fast responses, and the new geocoder is too slow for my application. What can I use for faster responses?

We recommend that applications that respond to user input, and therefore are highly latency-sensitive, use the Place Autocomplete feature in the Places API (also available in JavaScript, Android, or iOS) rather than address geocoding. Place Autocomplete is optimized to be used interactively, and thus has very low latency.

Address geocoding in the Geocoding API is optimized for use with complete, unambiguous, well formatted addresses, such as delivery addresses entered into online forms, and thus has higher latency than Place Autocomplete. This is already the case with the old forward geocoder. The latency difference between Place Autocomplete and the new forward geocoder increases further, since the new geocoder has greater coverage and better result quality, but at the cost of somewhat higher latency.

How can I mitigate the latency on the Directions API and Distance Matrix API?

Instead of addresses, use place IDs to specify waypoints, origin, and destination. Place IDs are best obtained from the Place Autocomplete feature in the Places API or the Places library in the Maps JavaScript API. See also the information on the placeIdOnly option, which can be used to reduce the cost of Place Autocomplete.

When the Directions API or Distance Matrix API is queried with an address string rather than a place ID or latlng, they use the same backend as the Geocoding API to convert that address into a place ID prior to calculating directions. Place Autocomplete is faster than address geocoding. For applications that use the Directions API or Distance Matrix API in highly latency-sensitive situations, such as responding to user input, we recommended you use Place Autocomplete to get the place IDs corresponding to those addresses, and pass the place IDs to the Directions API or Distance Matrix API. This approach reduces latency significantly even compared to the old address geocoder. See our documentation for an example of how to use Place Autocomplete with directions.

I’m a Premium Plan customer, and the Places API is too expensive. What can I do to reduce costs?

We recommend using the Maps JavaScript API Place autocomplete widget. To reduce the cost of using the autocomplete widget, use the new placeIdOnly option to enable direct access to place IDs from the Place Autocomplete service. The placeIdOnly option skips Places Details requests for applications that only need an address, not full business details. To get the corresponding address, pass place IDs to the geocoding service or the Geocoding API. You may also pass place IDs to the directions or distance matrix service or the Directions API or Distance Matrix API instead of an address text string or latitude/longiture pair.

The Google Maps API Geocoder Tool and the Place Autocomplete and Directions example have been updated to illustrate how to use the new placeIdOnly option.

How do I report bugs in the new geocoder?

If you have any bug reports or feature requests for the new forward geocoder service, please let us know using our public issue tracker.

The new geocoder is not producing good results for my use case. What help is available?

Please let us know using our public issue tracker, sharing a few specific queries that produce worse results with the new geocoder, so we can investigate to see if there are any bugs or systemic issues causing problems with result quality, or if there are any changes we can make to the best practices guide to help developers get better results.

Component filtering in the new geocoder does not work the same as the old geocoder. How do I get the best results with the new geocoder using component filtering?

In the new geocoder, component filtering is only fully supported for address-level results. There is partial support for country code (for example, components=country:GB) and postal code restrictions for locality and higher-level results. The following examples illustrate how best to use component filtering, depending on the results you need. In the sample request URLs, be sure to replace ‘YOUR_API_KEY’ with your actual API key.

  • To restrict addresses (including buildings, streets, and roads) to a political area (country, locality, etc.), use component filtering in the same way as the old geocoder. This use is supported in the new geocoder. For example: address=gordon&components=locality:dublin returns "Gordon Way, Dublin, OH 43017, USA".
    https://maps.googleapis.com/maps/api/geocode/json?new_forward_geocoder=true&address=gordon&components=locality:dublin&key=YOUR_API_KEY
    
  • To restrict postal codes to a specific country, use component filtering in the same way as the old geocoder, but be sure to specify the country restriction using an ISO 3166-2 country code. This use is supported in the new geocoder. For example: components=country:CH|postal_code:2000 returns "2000 Neuchâtel, Switzerland".
    https://maps.googleapis.com/maps/api/geocode/json?new_forward_geocoder=true&components=country:CH%7Cpostal_code:2000&key=YOUR_API_KEY
    
  • To restrict other non-address queries (cities or neighborhoods, for example) to a specific country, use component filtering in the same way as the old geocoder, but be sure to specify the country restriction using an ISO 3166-2 country code. In the new geocoder, this is no longer guaranteed to find the same results as the old geocoder. Use Place Autocomplete to obtain better results restricted to the desired country.

    Examples:

    • Using the old geocoder, geocoding for components=country:US%7Clocality:paris returns several cities in the USA named "Paris".
      https://maps.googleapis.com/maps/api/geocode/json?new_forward_geocoder=false&components=country:US%7Clocality:paris&key=YOUR_API_KEY
      
    • Using the new geocoder, geocoding for components=country:US%7Clocality:paris returns "Paris, TX, USA" but none of the other cities in the USA named "Paris".
      https://maps.googleapis.com/maps/api/geocode/json?new_forward_geocoder=true&components=country:US%7Clocality:paris&key=YOUR_API_KEY
      
    • Using Place Autocomplete for input=paris&components=country:us&types=(regions), and also specifying a viewport using location and radius to bias the location results, generates a response with several cities in the USA named "Paris".
      https://maps.googleapis.com/maps/api/place/autocomplete/json?location=37.386052,-122.083851&radius=10000&input=paris&components=country:us&types=(regions)&key=YOUR_API_KEY
      
  • To restrict other non-address queries (cities or neighborhoods, for example) to an area other than a specific country, using component filtering in the new geocoder is not guaranteed to find the same results as the old geocoder. Use Place Autocomplete to obtain better results biased to the specified area (location and radius). You may also use the new strictbounds parameter to restrict the results to the specified area.

    Examples:

    • Using the old geocoder, geocoding for administrative_area:Anaga|locality:Santa+Cruz returns the locality of Santa Cruz de Tenerife as well as the administrative area of Anaga.
      https://maps.googleapis.com/maps/api/geocode/json?new_forward_geocoder=false&components=administrative_area:Anaga%7Clocality:Santa%20Cruz&key=YOUR_API_KEY
      
    • Using the new geocoder, geocoding for administrative_area:Anaga|locality:Santa+Cruz returns only the administrative area of Anaga, not the desired locality of Santa Cruz de Tenerife.
      https://maps.googleapis.com/maps/api/geocode/json?new_forward_geocoder=true&components=administrative_area:Anaga%7Clocality:Santa%20Cruz&key=YOUR_API_KEY
      
    • Using Place Autocomplete for input=santa+cruz&location=28.494168,-16.275751&radius=20000&types=geocode returns "Santa Cruz de Tenerife, Spain" first, as well as other cities like "Santa Cruz de La Palma" (on a different island) and "Santa Cruz, CA, United States".
      https://maps.googleapis.com/maps/api/place/autocomplete/json?input=santa+cruz&location=28.494168,-16.275751&radius=20000&types=geocode&key=YOUR_API_KEY
      
    • Add strictbounds to the above Place Autocomplete request to return results restricted to the specified region ("Anaga").
      https://maps.googleapis.com/maps/api/place/autocomplete/json?input=santa+cruz&location=28.494168,-16.275751&radius=20000&types=geocode&strictbounds&key=YOUR_API_KEY
      

Send feedback about...

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