A geocodificação é o processo de conversão de endereços (como um endereço) em coordenadas geográficas (latitude e longitude), que podem ser usadas para colocar marcadores em um mapa ou posicioná-lo. O objetivo deste documento é esclarecer as considerações envolvidas ao geocodificar endereços. Descreve quando é ideal usar a API Geocoding e quando é 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 (incluindo endereços ambíguos, incompletos, com formatação incorreta ou incorretos) inseridos pelo usuário | Use o serviço Place Autocomplete da API Places para ver um ID de lugar e, depois, a API Geocoding para geocodificar o ID de lugar em uma latitude/longitude. |
| Processamento automatizado de sistemas completos e não ambíguos (por exemplo, "48 Pirrama Rd, Pyrmont, NSW, Austrália") | Usar o serviço da Web da API Geocoding. |
| Sistemas automatizados que processam consultas ambíguas (por exemplo, endereços incompletos, mal formatados ou incorretos) | Os sistemas automatizados recomendados usam o serviço da Web da API Geocoding. No entanto, sistemas automatizados com uma alta taxa de consultas ambíguas, incompletas ou incorretas provenientes da entrada do usuário podem se beneficiar da adição de um widget interativo do Place Autocomplete para que os usuários possam selecionar um resultado e, assim, evitar erros de ortografia de um endereço. |
| Problemas de latência que usam a API Directions ou a API Distance Matrix, 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 ver os IDs de lugar e transmita esses IDs para a API Directions ou a API Distance Matrix. |
Resposta à interação do usuário
Os aplicativos que respondem em tempo real à entrada do usuário têm duas considerações importantes que afetam a escolha da API:
- A entrada do usuário geralmente envolve inserir um endereço progressivamente (como "123 Main Street"). Portanto, a possibilidade de geocodificar endereços incompletos e ambíguos é vantajosa, porque permite que o usuário receba um resultado mais rapidamente.
- 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 da API Places ideal para responder à entrada do usuário. O Place Autocomplete foi projetado para retornar várias opções possíveis e permitir que um usuário escolha entre elas. A API Places pode ser restrita para pesquisar apenas geocódigos ou endereços, além de excluir empresas. Além disso, a função de busca de preenchimento automático pode ser enviesada 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 retorna detalhes completos do endereço e geocodifica o endereço em latlng. Os IDs de lugar também podem ser transmitidos para outras APIs, como a API Directions e a API Distance Matrix (veja abaixo).
A geocodificação de endereços na API Geocoding tem latência muito maior e produz resultados menos precisos para consultas incompletas ou ambíguas. Portanto, 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 API Places.
Sistemas automatizados
Processamento automático de sistemas completos e não ambíguos: consultas não ambíguas, como strings de endereços postais completos (por exemplo, "48 Pirrama Rd, Pyrmont, NSW, Austrália"), são mais adequadas para o serviço da Web 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 não ambíguas.
Consultas ambíguas de processamento automatizado de sistema: consultas ambíguas são aquelas que contêm endereços com formatação incorreta, endereços incompletos ou erros de ortografia. Para sistemas automatizados, recomendamos o uso do 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, você pode se beneficiar da adição de um elemento interativo ao app usando o serviço Place Autocomplete na API Places, já que ele foi projetado para retornar várias opções possíveis e permitir que um 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, em seguida, retorna os detalhes de endereço completos e geocodifica o endereço em uma latitude/longitude. Saiba mais sobre o serviço Place Autocomplete para Android, iOS, JavaScript e API Places.
Reduzir a latência da API Directions e da API Distance Matrix
Quando origens, destinos ou waypoints são especificados como strings de endereço, a API Directions e a API Distance Matrix usam o mesmo back-end que a API Geocoding para geocodificar esses endereços antes de calcular 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 usa 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, os destinos ou os waypoints são 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 transmiti-los para a API Directions ou a API Distance Matrix. Saiba mais sobre o serviço Place Autocomplete para Android, iOS, JavaScript e API Places. Veja também um exemplo em JavaScript de preenchimento automático de rotas e rotas.
Conclusão
Dependendo do 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, bem como latência reduzida.
Gerenciar erros e novas tentativas
Se você receber respostas de UNKNOWN_ERROR, elas são causadas por erros transitórios
e são mais recomendadas ao tentar novamente após um pequeno atraso. Recomendamos o uso das bibliotecas de cliente dos serviços da Web da Plataforma Google Maps que incluem nova lógica e são compatíveis com a 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 apoiadas pela comunidade, disponíveis para download e contribuições no GitHub, onde você também encontrará instruções de instalação e amostra de código.
Se você receber um código de status OVER_QUERY_LIMIT como resposta, isso significa que excedeu os limites de uso da API. Recomendamos que você teste estas estratégias de otimização de uso.