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 foco 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, 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 | |
|---|---|
| Chegada física, seleção avançada de destino, entrega de última milha, embarque/desembarque de transporte por aplicativo, entradas de edifícios ou navegação em campus | Use o método Pesquisar destinos (SearchDestinations) na API Geocoding v4 para recuperar entradas de edifícios, pontos de navegação roteáveis, contornos de edifícios e pontos de referência próximos. Consulte Escolher um método de geocodificação. |
| 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, chame SearchDestinations (para detalhes hiperlocais) ou GeocodePlace (para coordenadas básicas). |
| 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 v4 (SearchDestinations para detalhes hiperlocais ou GeocodeAddress para pesquisa de coordenadas). |
| Sistemas automatizados que processam consultas ambíguas (por exemplo, endereços incompletos, mal formatados ou com erros de ortografia) | Recomende 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, que permite aos usuários selecionar um resultado e, assim, evitar 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 de geocodificação usando o serviço Place Autocomplete da API Places para receber IDs de lugar e, em seguida, transmita esses IDs para a API Directions (legada) ou a 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 de um endereço de forma progressiva (como "Rua Principal, 123"). Por isso, poder geocodificar endereços incompletos e ambíguos é útil, 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 responder à 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 as APIs Directions (legada) e 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 também 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 inequívocos: consultas inequívocas, como strings de endereço postal completas (por exemplo, "48 Pirrama Rd, Pyrmont, NSW, Australia"), são mais bem processadas pelo 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 inequívocas.
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 elas. Se o sistema automatizado processa uma alta taxa de consultas ambíguas derivadas de entradas 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 um 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 as origens, os destinos ou os 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 usa 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 as origens, os destinos ou os waypoints são inicialmente especificados como strings de endereço, recomendamos que você minimize a latência usando o serviço Place Autocomplete da API Places para converter strings de endereço em IDs de lugar e, em seguida, transmitir os IDs de lugar 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. Confira também um exemplo em JavaScript de Place Autocomplete e rotas.
Conclusão
Dependendo do caso de uso, é possível 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 curto período. 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 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ê teste estas
estratégias de otimização de uso.