This FAQ covers questions specific to the Geocoding API.
Refer to the [Google Maps Platform FAQ](https://developers.google.com/maps/faq.md.txt) for questions
common to all Google Maps Platform. See also
[Best Practices When Geocoding Addresses](https://developers.google.com/maps/documentation/geocoding/best-practices.md.txt).

#### Troubleshooting

- [I'm getting more queries that return ZERO_RESULTS with the geocoder. What's going on?](https://developers.google.com/maps/documentation/geocoding/faq.md.txt#trbl-zero-results)
- [I need fast responses, and the geocoder is too slow for my application. What can
  I use for faster responses?](https://developers.google.com/maps/documentation/geocoding/faq#trbl-slow)
- [How can I mitigate the latency on the Directions API (Legacy) and
  Distance Matrix API (Legacy)?](https://developers.google.com/maps/documentation/geocoding/faq#trbl-latency)
- [How do I report bugs in the geocoder?](https://developers.google.com/maps/documentation/geocoding/faq.md.txt#trbl-report-bug)
- [The geocoder isn't producing good results for my use case. What help is available?](https://developers.google.com/maps/documentation/geocoding/faq.md.txt#trbl-help)
- [How do I get the best results with the geocoder using component filtering?](https://developers.google.com/maps/documentation/geocoding/faq.md.txt#trbl-component-filtering)

## Troubleshooting


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

:   In the geocoder, ambiguous, incomplete and badly formatted queries, such as
    misspelled or nonexistent addresses, are prone to produce ZERO_RESULTS.
    If the address cannot be found, ZERO_RESULTS is preferable to a partial
    result (for example returning only the suburb in lieu of an address).

    If your application deals with user input of addresses, the
    [Place Autocomplete](https://developers.google.com/maps/documentation/places/web-service/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](https://developers.google.com/maps/documentation/places/web-service/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](https://developers.google.com/maps/documentation/geocoding/best-practices.md.txt) and the
    [Address Geocoding in the Google Maps APIs blog post](https://mapsplatform.google.com/resources/blog/address-geocoding-in-google-maps-apis/).


I need fast responses, and the 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](https://developers.google.com/maps/documentation/places/web-service/autocomplete)
    feature in the Places API (also available in
    [JavaScript](https://developers.google.com/maps/documentation/javascript/places-autocomplete),
    [Android](https://developers.google.com/maps/documentation/places/android-sdk/autocomplete), or
    [iOS](https://developers.google.com/maps/documentation/places/ios-sdk/autocomplete)) 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. The forward geocoder has greater coverage and better result
    quality, but with somewhat higher latency.


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

:   Instead of addresses, use [place IDs](https://developers.google.com/maps/documentation/places/web-service/place-id.md.txt) to
    specify waypoints, origin, and destination. Place IDs are best obtained from the
    [Place Autocomplete](https://developers.google.com/maps/documentation/places/web-service/autocomplete)
    feature in the Places API or the
    [Places library](https://developers.google.com/maps/documentation/javascript/places-autocomplete) in the
    Maps JavaScript API. See also the information on the
    [`placeIdOnly`](https://developers.google.com/maps/documentation/javascript/places-autocomplete#placeidonly) option, which can be used to reduce the cost of
    Place Autocomplete.

    When the Directions API (Legacy) or Distance Matrix API (Legacy)
    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 (Legacy) or
    Distance Matrix API (Legacy) in highly latency-sensitive situations, such as
    responding to user input, we recommend you use Place Autocomplete to get
    the place IDs corresponding to those addresses, and pass the place IDs to
    the Directions API (Legacy) or Distance Matrix API (Legacy).
    This approach reduces latency significantly. See our documentation for an
    [example of how to use Place Autocomplete with directions](https://developers.google.com/maps/documentation/javascript/examples/places-autocomplete-directions.md.txt).


How do I report bugs in the geocoder?

:   If you have any
    [bug reports](https://issuetracker.google.com/savedsearches/558483) or
    [feature requests](https://issuetracker.google.com/issues/new?component=188871&template=788905) for the forward geocoder service, let us know using our public
    [issue tracker](https://issuetracker.google.com/issues/new?component=188871&template=788906).


The geocoder isn't producing good results for my use case. What help is available?

:   Let us know using our public
    [issue tracker](https://issuetracker.google.com/savedsearches/558483), sharing a few specific queries, 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](https://developers.google.com/maps/documentation/geocoding/best-practices.md.txt)
    to help developers get better results.


How do I get the best results with the geocoder using component filtering?

:   In the geocoder, [component filtering](https://developers.google.com/maps/documentation/geocoding/overview#component-filtering) enforces only `postal_code` and
    `country` restrictions. 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 postal codes to a specific country, be sure to specify the country restriction using an [ISO 3166-2 country code](https://en.wikipedia.org/wiki/ISO_3166-2). For example: `components=country:CH|postal_code:8000` returns "8000 Zürich, Switzerland".

      ```
      https://maps.googleapis.com/maps/api/geocode/json?components=country:CH%7Cpostal_code:8000&key=YOUR_API_KEY
      ```
    - To restrict queries to a specific country, be sure to specify the country restriction using an [ISO 3166-2 country code](https://en.wikipedia.org/wiki/ISO_3166-2). Country names and other abbreviations may not produce the same results as country codes.

      Examples:
      - Geocoding for `components=country:FRA|locality:gallus` returns the sublocality of Gallus in Frankfurt am Main, Germany. This is because the 3-letter country code for France (FRA) isn't supported, thus results in any country are allowed and the result in Frankfurt is a better fit than anything in France.

        ```
        https://maps.googleapis.com/maps/api/geocode/json?components=country:FRA%7Clocality:gallus&key=YOUR_API_KEY
        ```
    - Geocoding API won't necessarily return multiple results for ambiguous queries. Such queries are better answered by the Place Autocomplete. Examples:

      - Geocoding for `components=country:US|locality:madrid` returns "Madrid, NM 87010, USA" but none of the other cities in the USA named "Madrid".

        ```
        https://maps.googleapis.com/maps/api/geocode/json?components=country:US%7Clocality:madrid&key=YOUR_API_KEY
        ```
      - Using Place Autocomplete for `input=madrid&components=country:us&types=(regions)`, and also specifying a viewport using `location` and `radius` to [bias the location results](https://developers.google.com/maps/documentation/places/web-service/autocomplete#location_biasing), generates a response with several cities in the USA named "Madrid".

        ```
        https://maps.googleapis.com/maps/api/place/autocomplete/json?location=37.386052,-122.083851&radius=10000&input=madrid&components=country:us&types=(regions)&key=YOUR_API_KEY
        ```