A geocodificação é o processo de converter endereços (como um endereço) em coordenadas geográficas (latitude e longitude) que você pode usar para colocar marcadores em um mapa ou posicionar o mapa. O objetivo deste documento é esclarecer as considerações sobre a geocodificação de endereços. Ele 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 aplicativos sensíveis à latência, como ao responder a uma entrada do usuário.
Casos de uso e recomendações de API
| Casos de uso e recomendações de API | |
|---|---|
| Responder, em tempo real, aos comandos do usuário (inclui 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, em seguida, a API Geocoding para geocodificar o ID em um valor do tipo "latlng". |
| Sistemas automatizados que processam endereços postais completos, não ambíguos (por exemplo, "Avenida Paulista, 123, São Paulo, SP, Brasil" | Usar 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 ortográficos) | Os sistemas automatizados usam o serviço da Web da API Geocoding. No entanto, os 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 evitem erros de ortografia de um endereço. |
| Problemas de latência usando a API Directions ou a API Distance Matrix, com origens, destinos ou waypoints especificados como strings de endereço. | Reduzir a latência da geocodificação usando o serviço Place Autocomplete da API Places para conseguir os IDs de lugar e transmiti-los 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 principais que afetam a escolha da API:
- A entrada do usuário geralmente envolve inserir um endereço progressivamente (como "123 Main Street"). Portanto, poder geocodificar endereços incompletos e ambíguos é benéfico 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 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 à pesquisa apenas por códigos geográficos ou endereços, excluindo empresas. Além disso, essa função pode ser direcionada para retornar resultados específicos de um local. A API Places retorna um ID de lugar que pode ser transmitido ao serviço da Web da API Geocoding como um local totalmente desambiguado, que retorna os detalhes completos do endereço e geocodifica o endereço em latitude/longitude. Os IDs de lugares também podem ser transmitidos para outras APIs, como a API Directions e a API Distance Matrix (confira abaixo).
A geocodificação de endereço na API Geocoding tem uma latência muito maior e também 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 a API Places.
Sistemas automatizados
Processamento de sistemas automatizados de endereços postais completos, não ambíguos: consultas não ambíguas, como strings completas de endereços postais (por exemplo, "Avenida Paulista, 123, São Paulo, SP, SP, Brasil") são mais bem tratadas pelo serviço da Web da API Geocoding. O back-end de geocodificação de endereço oferece maior cobertura de endereços globalmente e é otimizado para resultados de alta qualidade com esses tipos de consultas completas e não ambíguas.
Consultas ambíguas de processamento automatizado do sistema: consultas ambíguas são aquelas que contêm endereços formatados incorretamente, 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, adicione um elemento interativo ao app usando o serviço Place Autocomplete na API Places, que 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 ao serviço da Web da API Geocoding como um local totalmente desambiguado, que retorna os detalhes completos do endereço e geocodifica o endereço em latitude/longitude. Saiba mais sobre o serviço Place Autocomplete para Android, iOS, JavaScript e a API Places.
Reduzir a latência das APIs Directions e 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 lugares.
Se o seu 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, destinos ou 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 lugares e transmitir esses IDs 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. Veja também um exemplo em JavaScript de preenchimento automático de lugar e rotas.
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, é provável que isso seja causado por erros transitórios.
Para resolver o problema, tente novamente após um pequeno atraso. Recomendamos que você use as
bibliotecas de cliente dos serviços da Web da Plataforma Google Maps, que incluem a lógica de repetição e são compatíveis com a autenticação do Plano Premium da Plataforma Google Maps.
O cliente Java, cliente Python, cliente Go e cliente Node.js para 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 exemplos 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.