A geocodificação é o processo de converter endereços (como um endereço de rua) em coordenadas geográficas (latitude e longitude) que você pode usar para colocar marcadores em um mapa ou posicioná-lo. O objetivo deste documento é esclarecer as considerações envolvidas na geocodificação de endereços. Ele descreve quando é melhor usar a API Geocoding e quando é mais vantajoso usar o serviço Place Autocomplete da API Places.
Em geral, use a API Geocoding ao geocodificar endereços completos (por exemplo, "48 Pirrama Rd, Pyrmont, NSW, Austrália"). Use o serviço Place Autocomplete da API Places ao geocodificar endereços ambíguos (incompletos) ou para aplicativos sensíveis à latência, como ao responder à entrada do usuário.
Casos de uso e recomendações de API
| Casos de uso e recomendações de API | |
|---|---|
| Responder em tempo real à entrada do usuário (inclui endereços ambíguos, incompletos, mal formatados ou com erros de ortografia inseridos por um usuário) | Use o serviço Place Autocomplete da API Places para receber um ID de lugar e, em seguida, a API Geocoding para geocodificar o ID de lugar em uma latlng. |
| Sistemas automatizados processam endereços postais completos e sem ambiguidades (por exemplo, "48 Pirrama Rd, Pyrmont, NSW, Austrália") | Use o serviço da Web da API Geocoding. |
| Sistemas automatizados que processam consultas ambíguas (por exemplo, endereços incompletos, mal formatados ou com erros de ortografia) | Recomendamos que os sistemas automatizados usem o serviço da Web da API Geocoding. No entanto, sistemas automatizados com uma alta taxa de consultas ambíguas, incompletas ou com erros de ortografia derivadas da entrada do usuário podem se beneficiar da adição de um widget interativo do Place Autocomplete para permitir que os usuários selecionem um resultado e evitem erros de ortografia em um endereço. |
| Problemas de latência ao usar a API Directions (legada) ou a API Distance Matrix (legada), com origens, destinos ou waypoints especificados como strings de endereço | Reduza a latência da geocodificação usando o serviço Place Autocomplete da API Places para receber IDs de lugares e, em seguida, transmita esses IDs para a API Directions (legada) ou API Distance Matrix (legada). |
Responder à entrada do usuário
Os aplicativos que respondem em tempo real à entrada do usuário têm duas considerações principais que afetam a escolha da API:
- A entrada do usuário geralmente envolve a inserção progressiva de um endereço (como "Rua Principal, 123"). Portanto, a capacidade de geocodificar endereços incompletos e ambíguos é benéfica, já que permite que o usuário receba um resultado mais rápido.
- Aplicativos que respondem à interação do usuário dependem muito de um baixo nível de latência.
Essas duas considerações tornam o serviço Place Autocomplete na API Places ideal para o caso de uso de resposta à entrada do usuário. O Place Autocomplete foi projetado para retornar várias opções possíveis e permitir que o usuário escolha entre elas. A API Places pode ser restrita para pesquisar apenas geocódigos ou endereços, excluindo empresas. Além disso, a função de pesquisa de preenchimento automático pode ser direcionada para retornar resultados específicos de um local. A API Places retorna um ID de lugar que pode ser transmitido como um local totalmente sem ambiguidade para o serviço da Web da API Geocoding, que retorna detalhes completos do endereço e o geocodifica em uma latlng. Os IDs de lugar também podem ser transmitidos para outras APIs, como a API Directions (legada) e a API Distance Matrix (legada). Consulte Reduzir a latência.
A geocodificação de endereços na API Geocoding tem uma latência muito maior e produz resultados menos precisos para consultas incompletas ou ambíguas. Por isso, não é recomendada para aplicativos que precisam responder em tempo real à entrada do usuário.
Saiba mais sobre o serviço Place Autocomplete para Android, iOS, JavaScript e a API Places.
Sistemas automatizados
Sistemas automatizados que processam endereços postais completos e sem ambiguidade: consultas sem ambiguidade, como strings de endereços postais completos (por exemplo, "48 Pirrama Rd, Pyrmont, NSW, Australia"), são melhor processadas pelo serviço da Web da API Geocoding. O back-end de geocodificação de endereços oferece maior cobertura de endereços no mundo todo e é otimizado para resultados de alta qualidade com esses tipos de consultas completas e sem ambiguidade.
Sistema automatizado que processa consultas ambíguas: consultas ambíguas são aquelas que contêm endereços mal formatados, incompletos ou com erros de ortografia. Para sistemas automatizados, recomendamos usar o serviço da Web da API Geocoding. No entanto, a API Geocoding não foi projetada para lidar com consultas ambíguas e pode produzir resultados menos precisos ou nenhum resultado em resposta a consultas ambíguas. Se o sistema automatizado processa uma alta taxa de consultas ambíguas derivadas da entrada do usuário, pode ser útil adicionar um elemento interativo ao app usando o serviço Place Autocomplete na API Places, porque ele foi projetado para retornar várias opções possíveis e permitir que o usuário escolha entre elas. A API Places retorna um ID de lugar que pode ser transmitido como um local totalmente sem ambiguidade para o serviço da Web da API Geocoding, que retorna detalhes completos do endereço e o geocodifica em uma latlng. Saiba mais sobre o serviço Place Autocomplete para Android, iOS, JavaScript e a API Places.
Reduzir a latência da API Directions (legada) e da API Distance Matrix (legada)
Quando origens, destinos ou waypoints são especificados como strings de endereço, a API Directions (legada) e a API Distance Matrix (legada) usam o mesmo back-end da API Geocoding para geocodificar esses endereços antes de calcular as rotas. Isso aumenta significativamente a latência em comparação com a especificação dos mesmos locais como latlngs ou IDs de lugar.
Se o aplicativo usar a API Directions (legada) ou a API Distance Matrix (legada) em uma situação sensível à latência, como responder à entrada do usuário, e se as origens, os destinos ou os pontos de parada forem especificados inicialmente como strings de endereço, recomendamos minimizar a latência usando o serviço Place Autocomplete da API Places para converter strings de endereço em IDs de lugar e transmitir os IDs para a API Directions (legada) ou a API Distance Matrix (legada). Saiba mais sobre o serviço Place Autocomplete para Android, iOS, JavaScript e a API Places. Consulte também um exemplo em JavaScript de Place Autocomplete e rotas.
Conclusão
Dependendo do seu caso de uso, você pode usar a API Geocoding sozinha ou combiná-la com o serviço Place Autocomplete. Isso permite criar apps que oferecem resultados de geocodificação precisos e latência reduzida.
Gerenciar erros e novas tentativas
Se você receber respostas UNKNOWN_ERROR, elas são causadas por erros temporários
e são mais bem resolvidas com uma nova tentativa após um breve atraso. Recomendamos usar as
bibliotecas de cliente dos serviços da Web da Plataforma Google Maps, que incluem lógica de repetição e são compatíveis com a autenticação do Plano Premium da Plataforma Google Maps.
Os clientes Java,
Python,
Go
e Node.js
para serviços do Google Maps são bibliotecas de cliente com suporte da comunidade, disponíveis para download
e contribuições no GitHub, onde você também encontra instruções de instalação e
exemplo de código.
Se você receber um código de status OVER_QUERY_LIMIT como resposta, excedeu os limites de uso da API. Recomendamos
que você tente estas
estratégias de otimização de uso.