Perguntas frequentes sobre geocodificação
Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Esta seção de perguntas frequentes aborda questões específicas da API Geocoding.
Consulte as Perguntas frequentes sobre a Plataforma Google Maps para tirar suas dúvidas sobre a plataforma de forma geral. Consulte também as práticas recomendadas para geocodificar endereços.
Solução de problemas
Solução de problemas
-
Estou recebendo mais consultas que retornam ZERO_RESULTS com o geocodificador. O que está acontecendo?
-
No geocodificador, consultas ambíguas, incompletas e mal formatadas, como endereços com erros ortográficos ou inexistentes, tendem a produzir ZERO_RESULTS.
Se o endereço não for encontrado, ZERO_RESULTS é preferível a um resultado parcial (por exemplo, retornando apenas o subúrbio em vez de um endereço).
Se o app lida com a entrada de endereços do usuário, o recurso Place Autocomplete na API Places pode produzir resultados de melhor qualidade.
O Place Autocomplete permite que os usuários selecionem entre um conjunto de resultados com base no que eles digitaram. Isso permite que os usuários escolham entre resultados com nomes semelhantes e ajustem a consulta se digitarem um endereço incorreto.
Se você tiver um aplicativo que lida com consultas ambíguas ou incompletas ou que possam conter erros, recomendamos usar o recurso Place Autocomplete na API Places em vez do geocodificador direto disponível na API Geocoding. Para mais detalhes, consulte as
práticas recomendadas para endereços com geocodificação e a
postagem do blog sobre a geocodificação de endereços nas APIs Google Maps.
-
Preciso de respostas rápidas, e o geocodificador é muito lento para meu app. O que posso
usar para respostas mais rápidas?
-
Recomendamos que os aplicativos que respondem à entrada do usuário e, portanto, são altamente sensíveis à latência usem o recurso Place Autocomplete na API Places (também disponível em JavaScript, Android ou iOS) em vez de geocodificação de endereço.
O Place Autocomplete foi otimizado para uso interativo e, portanto, tem muito pouca latência.
A geocodificação de endereços na API Geocoding é otimizada para uso com endereços completos, bem formatados e sem ambiguidade, como endereços de entrega inseridos em formulários on-line, e, portanto, tem latência maior que o Place Autocomplete. O geocodificador direto
tem maior cobertura e melhor qualidade de resultado, mas com latência um pouco maior.
-
Como posso reduzir a latência na API Directions (legado) e na API Distance Matrix (legado)?
-
Em vez de endereços, use IDs de lugar para especificar pontos de passagem, origem e destino. Os IDs de lugar são melhor obtidos com o recurso Place Autocomplete na API Places ou a biblioteca Places na API Maps JavaScript. Consulte também as informações sobre a opção
placeIdOnly, que pode ser usada para reduzir o custo do Place Autocomplete.
Quando a API Directions (legado) ou a API Distance Matrix (legado) é consultada com uma string de endereço em vez de um ID de lugar ou latlng, elas usam o mesmo back-end da API Geocoding para converter esse endereço em um ID de lugar antes de calcular as rotas. O Place Autocomplete é mais rápido do que a geocodificação de endereços. Para aplicativos que usam a API Directions (legado) ou a API Distance Matrix (legado) em situações altamente sensíveis à latência, como responder à entrada do usuário, recomendamos usar o Place Autocomplete para receber os IDs de local correspondentes a esses endereços e transmiti-los à API Directions (legado) ou Distance Matrix (legado).
Essa abordagem reduz a latência significativamente. Consulte nossa documentação para conferir um
exemplo de como usar o Place Autocomplete com direções.
-
Como faço para informar bugs no geocodificador?
-
Se você tiver
relatórios de bugs ou
solicitações de recursos para o serviço de geocodificador de encaminhamento, informe-nos usando nosso
Issue Tracker público.
-
O geocodificador não está produzindo bons resultados para meu caso de uso. Como consigo ajuda?
-
Informe usando nosso
rastreador de problemas público, compartilhando algumas consultas específicas. Assim, poderemos investigar se há bugs ou problemas sistêmicos que causam problemas com a qualidade dos resultados ou se há mudanças que podemos fazer no
guia de práticas recomendadas
para ajudar os desenvolvedores a ter resultados melhores.
-
Como conseguir os melhores resultados com o geocodificador usando a filtragem de componentes?
-
No geocodificador, a
filtragem de componentes aplica apenas restrições postal_code e
country. Os exemplos a seguir ilustram a melhor forma de usar a filtragem de componentes, dependendo dos resultados necessários. Nos URLs de solicitação de exemplo, substitua
"YOUR_API_KEY" pela sua chave de API real.
- Para restringir os CEPs a um país específico, especifique a restrição de país usando um código de país ISO 3166-2.
Por exemplo:
components=country:CH|postal_code:8000 retorna "8000 Zurique, Suíça".
https://maps.googleapis.com/maps/api/geocode/json?components=country:CH%7Cpostal_code:8000&key=YOUR_API_KEY
- Para restringir as consultas a um país específico, especifique a restrição de país usando um código de país ISO 3166-2. Os nomes de país e outras abreviações podem não produzir os mesmos resultados que os códigos de país.
Exemplos:
- A geocodificação para
components=country:FRA|locality:gallus retorna a sublocalidade de Gallus em Frankfurt am Main, Alemanha. Isso ocorre porque o código de três letras da França (FRA) não é aceito. Portanto, os resultados em qualquer país são permitidos, e o resultado em Frankfurt é mais adequado do que qualquer coisa na França.
https://maps.googleapis.com/maps/api/geocode/json?components=country:FRA%7Clocality:gallus&key=YOUR_API_KEY
- A API Geocoding não vai necessariamente retornar vários resultados para consultas ambíguas. Essas consultas são melhor respondidas pelo Place Autocomplete.
Exemplos:
- A geocodificação para
components=country:US|locality:madrid retorna "Madrid, NM 87010, EUA", mas nenhuma das outras cidades nos EUA com o nome "Madrid".
https://maps.googleapis.com/maps/api/geocode/json?components=country:US%7Clocality:madrid&key=YOUR_API_KEY
- Usar o Place Autocomplete para
input=madrid&components=country:us&types=(regions) e especificar uma viewport usando location e radius para
polarizar os resultados de localização gera uma resposta com várias cidades nos EUA com o nome "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
Exceto em caso de indicação contrária, o conteúdo desta página é licenciado de acordo com a Licença de atribuição 4.0 do Creative Commons, e as amostras de código são licenciadas de acordo com a Licença Apache 2.0. Para mais detalhes, consulte as políticas do site do Google Developers. Java é uma marca registrada da Oracle e/ou afiliadas.
Última atualização 2025-08-31 UTC.
[null,null,["Última atualização 2025-08-31 UTC."],[[["\u003cp\u003eThis FAQ addresses questions about the Geocoding API; for general Google Maps Platform questions, refer to the Google Maps Platform FAQ.\u003c/p\u003e\n"],["\u003cp\u003eFor applications with user input and latency sensitivity, Google recommends using Place Autocomplete instead of address geocoding for better results and speed.\u003c/p\u003e\n"],["\u003cp\u003eTo improve latency with the Directions or Distance Matrix APIs, use place IDs obtained from Place Autocomplete instead of addresses.\u003c/p\u003e\n"],["\u003cp\u003eYou can report bugs or request features for the Geocoding API through the public issue tracker.\u003c/p\u003e\n"],["\u003cp\u003eComponent filtering in the Geocoding API is primarily used to restrict results by country and postal code.\u003c/p\u003e\n"]]],[],null,["This FAQ covers questions specific to the Geocoding API.\nRefer to the [Google Maps Platform FAQ](/maps/faq) for questions\ncommon to all Google Maps Platform. See also\n[Best Practices When Geocoding Addresses](/maps/documentation/geocoding/best-practices).\n\nTroubleshooting\n\n- [I'm getting more queries that return ZERO_RESULTS with the geocoder. What's going on?](#trbl-zero-results)\n- [I need fast responses, and the geocoder is too slow for my application. What can\n I use for faster responses?](#trbl-slow)\n- [How can I mitigate the latency on the Directions API (Legacy) and\n Distance Matrix API (Legacy)?](#trbl-latency)\n- [How do I report bugs in the geocoder?](#trbl-report-bug)\n- [The geocoder isn't producing good results for my use case. What help is available?](#trbl-help)\n- [How do I get the best results with the geocoder using component filtering?](#trbl-component-filtering)\n\nTroubleshooting\n\n\nI'm getting more queries that return ZERO_RESULTS with the geocoder. What's going on?\n\n: In the geocoder, ambiguous, incomplete and badly formatted queries, such as\n misspelled or nonexistent addresses, are prone to produce ZERO_RESULTS.\n If the address cannot be found, ZERO_RESULTS is preferable to a partial\n result (for example returning only the suburb in lieu of an address).\n\n If your application deals with user input of addresses, the\n [Place Autocomplete](/maps/documentation/places/web-service/autocomplete) feature\n in the Places API may produce better quality results.\n Place Autocomplete allows users to select from a set of results based on what\n they've typed, which allows users to choose between similarly named results,\n and to adjust their query if they misspell an address.\n\n If you have an application dealing with ambiguous or incomplete queries or queries\n that may contain errors, we recommend you use the\n [Place Autocomplete](/maps/documentation/places/web-service/autocomplete) feature\n in the Places API rather than the forward geocoder\n available in the Geocoding API. For more details, see\n [Best Practices When Geocoding Addresses](/maps/documentation/geocoding/best-practices) and the\n [Address Geocoding in the Google Maps APIs blog post](https://mapsplatform.google.com/resources/blog/address-geocoding-in-google-maps-apis/).\n\n\nI need fast responses, and the geocoder is too slow for my application. What can\nI use for faster responses?\n\n: We recommend that applications that respond to user input, and therefore are highly\n latency-sensitive, use the [Place Autocomplete](/maps/documentation/places/web-service/autocomplete)\n feature in the Places API (also available in\n [JavaScript](/maps/documentation/javascript/places-autocomplete),\n [Android](/maps/documentation/places/android-sdk/autocomplete), or\n [iOS](/maps/documentation/places/ios-sdk/autocomplete)) rather than address geocoding.\n Place Autocomplete is optimized to be used interactively, and thus has very low latency.\n\n Address geocoding in the Geocoding API is optimized for use with\n complete, unambiguous, well formatted addresses, such as delivery addresses entered into\n online forms, and thus has higher latency than Place Autocomplete. The forward geocoder\n has greater coverage and better result quality, but with somewhat higher latency.\n\n\nHow can I mitigate the latency on the Directions API (Legacy) and\nDistance Matrix API (Legacy)?\n\n: Instead of addresses, use [place IDs](/maps/documentation/places/web-service/place-id) to\n specify waypoints, origin, and destination. Place IDs are best obtained from the\n [Place Autocomplete](/maps/documentation/places/web-service/autocomplete)\n feature in the Places API or the\n [Places library](/maps/documentation/javascript/places-autocomplete) in the\n Maps JavaScript API. See also the information on the\n [`placeIdOnly`](/maps/documentation/javascript/places-autocomplete#placeidonly) option, which can be used to reduce the cost of\n Place Autocomplete.\n\n When the Directions API (Legacy) or Distance Matrix API (Legacy)\n is queried with an address string rather than a place ID or latlng, they use the same\n backend as the Geocoding API to convert that address into a\n place ID prior to calculating directions. Place Autocomplete is faster than address\n geocoding. For applications that use the Directions API (Legacy) or\n Distance Matrix API (Legacy) in highly latency-sensitive situations, such as\n responding to user input, we recommended you use Place Autocomplete to get the place IDs\n corresponding to those addresses, and pass the place IDs to the\n Directions API (Legacy) or Distance Matrix API (Legacy).\n This approach reduces latency significantly. See our documentation for an\n [example of how to use Place Autocomplete with directions](/maps/documentation/javascript/examples/places-autocomplete-directions).\n\n\nHow do I report bugs in the geocoder?\n\n: If you have any\n [bug reports](https://issuetracker.google.com/savedsearches/558483) or\n [feature requests](https://issuetracker.google.com/issues/new?component=188871&template=788905) for the forward geocoder service, let us know using our public\n [issue tracker](https://issuetracker.google.com/issues/new?component=188871&template=788906).\n\n\nThe geocoder isn't producing good results for my use case. What help is available?\n\n: Let us know using our public\n [issue tracker](https://issuetracker.google.com/savedsearches/558483), sharing a few specific queries, so we can investigate to\n see if there are any bugs or systemic issues causing problems with result\n quality, or if there are any changes we can make to the\n [best practices guide](/maps/documentation/geocoding/best-practices)\n to help developers get better results.\n\n\nHow do I get the best results with the geocoder using component filtering?\n\n: In the geocoder, [component filtering](/maps/documentation/geocoding/overview#component-filtering) enforces only `postal_code` and\n `country` restrictions. The following examples illustrate how best to use component\n filtering, depending on the results you need. In the sample request URLs, be sure to\n replace \\`YOUR_API_KEY\\` with your actual API key.\n\n - 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\". \n\n ```scdoc\n https://maps.googleapis.com/maps/api/geocode/json?components=country:CH%7Cpostal_code:8000&key=YOUR_API_KEY\n ```\n - 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.\n\n Examples:\n - 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. \n\n ```scdoc\n https://maps.googleapis.com/maps/api/geocode/json?components=country:FRA%7Clocality:gallus&key=YOUR_API_KEY\n ```\n - Geocoding API won't necessarily return multiple results for ambiguous queries. Such queries are better answered by the Place Autocomplete. Examples:\n\n - Geocoding for `components=country:US|locality:madrid` returns \"Madrid, NM 87010, USA\" but none of the other cities in the USA named \"Madrid\". \n\n ```scdoc\n https://maps.googleapis.com/maps/api/geocode/json?components=country:US%7Clocality:madrid&key=YOUR_API_KEY\n ```\n - 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](/maps/documentation/places/web-service/autocomplete#location_biasing), generates a response with several cities in the USA named \"Madrid\". \n\n ```carbon\n 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\n ```"]]
