Pronto!

Para começar a desenvolver, acesse nossa documentação do desenvolvedor.

Ativar a Google Maps Geocoding API

Para começar, orientaremos você pelo Google Developers Console para realizar algumas atividades:

  1. Criar ou selecionar um projeto
  2. Ativar a Google Maps Geocoding API
  3. Criar chaves apropriadas
Continuar

Práticas recomendadas para geocodificar endereços

A geocodificação é o processo de converter endereços (como nome da rua e número) em coordenadas geográficas (latitude e longitude) para se inserir marcadores de local nos pontos corretos de um mapa ou posicionar o mapa. O objetivo deste documento é explicar os fatores envolvidos na geocodificação de endereços. Ele descreve o melhor momento para se usar a Google Maps Geocoding API e quando é vantajoso usar o serviço Place Autocomplete da Places API ou o serviço Text Search da Places API.

Em geral, é recomendável usar a Google Maps Geocoding API para geocodificar endereços completos (por exemplo, “48 Pirrama Rd, Pyrmont, NSW, Austrália”). Use o serviço Place Autocomplete da Places API para geocodificar endereços ambíguos (incompletos) ou para cenários de muita latência, como ao responder à interação do usuário. Para geocodificar endereços ambíguos em sistemas automatizados quando não há usuário para selecionar um item dentre as sugestões de preenchimento automático, use o serviço Text Search da Places API no lugar do Place Autocomplete.

Casos de uso e recomendações de API

Caso de uso Recomendação de API
Endereços postais, completos e não ambíguos Google Maps Geocoding API Web Service
Consultas ambíguas inseridas pelo usuário (por exemplo, endereços incompletos ou mal formatados) Serviço Place Autocomplete da Places API para obter um ID de local e, em seguida, a Geocoding API para geocodificar o ID de local em latitude/longitude.
Consultas ambíguas em um sistema automatizado (por exemplo, endereços incompletos ou mal formatados) Serviço Text Search da Places API para obter IDs de local e, em seguida, a Geocoding API para geocodificar os IDs de local em latitude/longitude.
Responder, em tempo real, à interação do usuário Serviço Place Autocomplete da Places API para obter um ID de local e, em seguida, a Geocoding API para geocodificar o ID de local em latitude/longitude.
Problemas de latência usando a Google Maps Directions API ou a Distance Matrix API, com origens, destinos ou pontos de referência especificados como strings de endereço Reduzir latência de geocodificação usando o serviço Place Autocomplete da Places API para obter IDs de local e, em seguida, passar esses IDs à Directions API ou à Distance Matrix API.

Endereços completos

Consultas não ambíguas, como strings de endereço postal completo (por exemplo, “48 Pirrama Rd, Pyrmont, NSW, Austrália”) são melhor gerenciadas pelo Geocoding API Web Service. O back-end de geocodificação de endereços fornece maior cobertura de endereços no mundo e foi otimizada para oferecer resultados de alta qualidade para consultas não ambíguas e completas.

Consultas ambíguas

Consultas ambíguas são as que contêm endereços mal formatados, incompletos ou com componentes desnecessários. O geocodificador do Geocoding API Web Service não foi desenvolvido para lidar com consultas ambíguas e pode produzir resultados menos precisos, ou nenhum resultado, em resposta a consultas ambíguas, especialmente no caso de consultas que contêm muitos erros de grafia ou termos irrelevantes para endereços.

Se você tem um caso de uso em que os usuários podem fazer consultas ambíguas (como “123 Main Street”), recomendamos usar o serviço Place Autocomplete na Places API, já que ele foi projetado para retornar diversas opções possíveis e permitir que um usuário escolha uma delas. A Places API pode se limitar a pesquisar somente códigos geográficos ou endereços, excluindo os estabelecimentos. Além disso, a função de busca do recurso de preenchimento automático pode ser polarizada para retornar resultados específicos de uma localidade. A Places API retorna um ID de local que pode ser passado como um local sem nenhuma ambiguidade ao Geocoding API Web Services, que, por sua vez, retorna 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 o Places API Web Service.

Se precisar usar a geocodificação de endereços em um sistema automatizado em que não há usuário para selecionar diversos resultados possíveis, mas as consultas podem ser ambíguas ou incompletas, use o serviço Text Search da Places API no lugar do serviço Place Autocomplete. O Place Search é mais indicado para lidar com consultas ambíguas que a Geocoding API e permite restringir a pesquisa a uma área específica ou até classificar os resultados por distância, oferecendo filtragem classificação de resultados mais precisas para esse tipo de consulta.

Resposta à interação do usuário

Aplicativos que respondem em tempo real à interação do usuário têm dois fatores-chave que afetam a escolha de API:

  1. A interação do usuário geralmente envolve a inserção progressiva de um endereço, por isso, poder geocodificar endereços incompletos e ambíguos é vantajoso por gerar resultados mais rápido para o usuário.
  2. Aplicativos que respondem à interação do usuário dependem muito de um baixo nível de latência.

Esses dois fatores tornam o serviço Place Autocomplete da Places API ideal para o caso de uso de resposta à interação do usuário. A geocodificação de endereço na Geocoding API tem muito mais latência, além de produzir resultados menos precisos para consultas incompletas ou ambíguas, por isso, não recomendamos usá-la para aplicativos que precisam responder à interação do usuário em tempo real. Saiba mais sobre o serviço Place Autocomplete para Android, iOS, JavaScript e o Places API Web Service.

Redução da latência para a Directions API e a Distance Matrix API

Quando origens, destinos e pontos de referência são especificados como strings de endereço, a Google Maps Directions API e a Distance Matrix API usam o mesmo back-end que a Geocoding API para geocodificar esses endereços antes de calcular rotas. Isso aumenta muito a latência se comparado com especificar os mesmos locais como latitude/longitude ou IDs de local.

Se o seu aplicativo usa a Directions API ou a Distance Matrix API em uma situação que precisa de baixa latência, como para responder à interação do usuário, e as origens, os destinos ou os pontos de referência inicialmente são especificados como strings de endereço recomendamos minimizar a latência usando o serviço Place Autocomplete da Places API para converter strings de endereço em IDs de local e passar os IDs de local para a Directions API ou a Distance Matrix API. Saiba mais sobre o serviço Place Autocomplete para Android, iOS, JavaScript e o Places API Web Service. Veja ainda um exemplo em JavaScript de preenchimento automático de local e rotas.

Conclusão

Dependendo do caso, ao geocodificar endereços usar a Geocoding API, a Places API ou o serviço Place Autocomplete ou Place Search junto com a Geocoding API permite criar aplicativos que oferecem aos usuários resultados de geocodificação precisos, além de menor latência.

Gerenciar erros e novas tentativas

Se você receber respostas como UNKNOWN_ERROR, saiba que a causa são erros transientes, que podem ser contornados mais facilmente fazendo uma nova tentativa depois de um curto espaço de tempo. Recomendamos usar as bibliotecas do cliente dos Google Maps APIs Web Services, que contêm lógica de nova tentativa e oferecem suporte à autenticação do Google Maps APIs Premium Plan. O Java Client, o Python Client, o Go Client e o Node.js Client para o Google Maps Services são bibliotecas de cliente apoiadas pela comunidade que estão disponíveis para download e contribuições no GitHub, onde você também poderá acessar instruções de instalação e códigos de exemplo.

Se você receber um código de status OVER_QUERY_LIMIT como resposta, o limite de uso da API foi excedido. Recomendamos tentar aplicar estas estratégias de otimização do uso.

Enviar comentários sobre…

Google Maps Geocoding API
Google Maps Geocoding API
Precisa de ajuda? Acesse nossa página de suporte.