A geocodificação é o processo de conversão de endereços (como um endereço de rua) em coordenadas geográficas (latitude e longitude) que podem ser usadas para colocar marcadores em um mapa ou posicionar o mapa. O foco deste documento é esclarecer as considerações envolvidas na geocodificação de endereços. Ele descreve quando é ideal usar a API Geocoding e quando é benéfico 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, Australia"). 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, incluindo endereços ambíguos, incompletos, com formatação incorreta ou com erros ortográficos inseridos por um usuário. | Use o serviço Place Autocomplete da API Places para receber um ID de lugar e, depois, a API Geocoding para geocodificar o ID em uma latlng. |
| Sistemas automatizados que processam endereços postais completos e inequívocos (por exemplo, "48 Pirrama Rd, Pyrmont, NSW, Australia") | Use o serviço da Web da API Geocoding. |
| Sistemas automatizados que processam consultas ambíguas, por exemplo, endereços incompletos, com formatação incorreta ou incorretos. | Recomendar 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 ortográficos 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, assim, evitem erros ortográficos em um endereço. |
| Problemas de latência ao usar a API Directions ou a API Distance Matrix com origens, destinos ou pontos de passagem 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 lugar e transmita esses IDs à API Directions ou Distance Matrix. |
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 "123 Main Street"). Portanto, a capacidade de geocodificar endereços incompletos e ambíguos é benéfica, porque 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 Autocomplete de lugar 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 tendenciosa para retornar resultados específicos de um local. A API Places retorna um ID de lugar que pode ser transmitido como um local totalmente desambiguado para o serviço da Web da API Geocoding, que, por sua vez, retorna todos os detalhes do endereço e faz a geocodificação em latlng. Os IDs de lugar também podem ser transmitidos a outras APIs, como a Directions e a Distance Matrix (consulte abaixo).
A geocodificação de endereços na API Geocoding tem uma latência muito maior e também produz resultados menos precisos para consultas incompletas ou ambíguas. Por isso, ela 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
Processamento de sistemas automatizados de endereços postais completos e inequívocos: consultas inequívocas, como strings de endereços postais completos (por exemplo, "48 Pirrama Rd, Pyrmont, NSW, Australia"), são melhor processadas pelo serviço da API Geocoding. O back-end de geocodificação de endereços oferece maior cobertura de endereços em todo o mundo e é otimizado para resultados de alta qualidade com esses tipos de consultas completas e inequívocas.
Sistema automatizado que processa consultas ambíguas: consultas ambíguas são aquelas que contêm endereços com formatação incorreta, endereços incompletos ou erros ortográficos. 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, adicione um elemento interativo ao app usando o serviço de preenchimento automático de lugares na API Places, já que 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 desambiguado para o serviço da Web da API Geocoding, que, por sua vez, retorna todos os detalhes do endereço e faz a geocodificação em latlng. Saiba mais sobre o serviço Place Autocomplete para Android, iOS, JavaScript e a API Places.
Redução da latência da API Directions e da API Distance Matrix
Quando as origens, os destinos ou os pontos intermediários são especificados como strings de endereço, a API Directions e a API Distance Matrix usam o mesmo back-end da API Geocoding para geocodificar esses endereços antes de calcular as direções. Isso aumenta significativamente a latência em comparação com a especificação dos mesmos locais como latlngs ou IDs de lugar.
Se o app usar a API Directions ou a API Distance Matrix em uma situação sensível à latência, como responder à entrada do usuário, e as origens, destinos ou pontos intermediários forem especificados inicialmente como strings de endereço, recomendamos minimizar a latência usando o serviço de preenchimento automático de lugares da API Places para converter strings de endereço em IDs de lugar e, em seguida, transmita os IDs de lugar para a API Directions ou a API Distance Matrix. Saiba mais sobre o serviço Place Autocomplete para Android, iOS, JavaScript e a API Places. Consulte também um exemplo em JavaScript de preenchimento automático de lugar e direções.
Conclusão
Dependendo do seu caso de uso, ao geocodificar endereços, usar a API Geocoding ou o serviço Place Autocomplete em combinação com a API Geocoding permite criar aplicativos que oferecem aos usuários 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 é melhor tentar novamente após um breve atraso. Recomendamos o uso das
bibliotecas de cliente dos serviços da Web da Plataforma Google Maps, que incluem a lógica de nova tentativa e oferecem suporte à autenticação do plano Premium da Plataforma Google Maps.
O cliente Java, o cliente Python, o cliente Go e o cliente Node.js para os 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 um exemplo de código.
Se você receber um código de status OVER_QUERY_LIMIT como resposta, significa que
excedeu os limites de uso da API. Recomendamos
que você tente estas
estratégias de otimização de uso.