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

Perguntas frequentes do novo geocodificador inverso

Essa seção de Perguntas frequentes abrange perguntas específicas do novo geocodificador inverso, anunciado na postagem Geocodificação de endereços nas Google Maps APIs do blog. Veja também Práticas recomendadas para geocodificar endereços.

Consulte as Perguntas frequentes das Google Maps APIs para acessar dúvidas comuns a todas as Google Maps APIs.

Primeiros passos

Solução de problemas

Primeiros passos

Quando o novo geocodificador inverso se tornará o padrão?
  • Quando se trata de solicitações da Google Maps Geocoding API e da Google Maps JavaScript API ao serviço de geocodificação, o novo geocodificador inverso agora é o padrão para solicitações não identificadas e clientes do plano padrão. Para clientes do Premium Plan que usam essas APIs, a mudança está marcada para 17 de janeiro de 2017.
  • Para todos os clientes (plano padrão e do Premium Plan) que usam a Google Maps Directions API, a Google Maps Distance Matrix API, a Google Static Maps API e a Google Street View Image API, e para solicitações da Google Maps JavaScript API aos serviços de rotas e matriz de distância, o novo geocodificador inverso se tornará o padrão no dia 24 de janeiro de 2017.
  • O geocodificador antigo será removido permanentemente no fim de março de 2017.

Essas datas estão sujeitas a eventuais atrasos em caso de imprevistos ou lançamento de outros recursos marcado para o mesmo momento. Se houver alguma mudança que você queira fazer no seu sistema antes do lançamento do novo geocodificador, busque fazê-la na produção antes dessas datas.

Que APIs usarão o novo geocodificador inverso?

As Google Maps APIs a seguir usam o mesmo geocodificador para as seguintes solicitações:

Observação: O novo geocodificador inverso nunca é usado para se obter detalhes de um ID de local.

Como faço para usar o novo geocodificador inverso antes de ele se tornar o padrão?

Você já pode usar o novo geocodificador inverso com a Geocoding API, a Directions API e a Distance Matrix API, além de com os serviços de geocodificação, rotas e matriz de distância, disponíveis na Maps JavaScript API.

Para a Geocoding API, a Directions API e a Distance Matrix API, adicione o parâmetro opcional new_forward_geocoder=true às solicitações.

Quanto às bibliotecas do cliente dos Google Maps APIs Web Services, para usar o novo geocodificador inverso, adicione new_forward_geocoder=true às solicitações. Esse é um parâmetro de URL personalizado recentemente adicionado às bibliotecas do cliente.

Nos serviços de geocodificação, rotas e matriz de distância, disponíveis na Maps JavaScript API, defina o novo parâmetro opcional newForwardGeocoder: true no objeto de solicitação adequado. Esse parâmetro está disponível nas versões Experimental e Release.

A Ferramenta Geocoder da Google Maps API foi atualizada com uma configuração opcional. Ao usá-la, selecione “Use the new forward geocoder” se quiser gerar resultados com base no funcionamento do novo geocodificador inverso.

Observação: O novo geocodificador inverso ainda não está disponível na Static Maps API nem na Street View Image API.

Como faço para usar o geocodificador inverso antigo depois que ele não for mais o padrão?

Você pode continuar usando o geocodificador antigo até a data de remoção permanente: 29 de março de 2017.

Para a Geocoding API, a Directions API e a Distance Matrix API, adicione o parâmetro opcional new_forward_geocoder=false às solicitações.

Quanto às bibliotecas do cliente dos Google Maps APIs Web Services, para usar o novo geocodificador inverso, adicione new_forward_geocoder=false às solicitações. Esse é um parâmetro de URL personalizado recentemente adicionado às bibliotecas do cliente.

Nos serviços de geocodificação, rotas e matriz de distância, disponíveis na Maps JavaScript API, defina o novo parâmetro opcional newForwardGeocoder: false no objeto de solicitação adequado. Esse parâmetro está disponível nas versões Experimental e Release.

Observação: Para a Static Maps API e a Street View Image API, o novo geocodificador inverso ainda não está disponível, por isso, não é preciso definir essa opção como “false”. Por enquanto, a Static Maps API e a Street View Image API continuam usando o geocodificador inverso antigo.

Qual é o motivo dessa mudança?

O novo geocodificador inverso é igual ao usado pelo aplicativo Google Maps para o usuário final. O geocodificador antigo se tornou obsoleto e será removido.

Essa mudança oferece retrocompatibilidade?

Sim, a Geocoding API continuará com o mesmo formato de solicitação e resposta. O novo geocodificador pode produzir um conjunto diferente de resultados para muitas consultas, mas as respostas continuarão operando no formato atual e os novos resultados retornarão os mesmos campos.

Solução de problemas

Recebo mais consultas que retornam ZERO_RESULTS com o novo geocodificador. O que está acontecendo?

No novo geocodificador, consultas mal formatadas, incompletas e ambíguas estão propensas a produzir ZERO_RESULTS. Essas consultas normalmente produziriam resultados incorretos com o geocodificador antigo, como retornar a periferia se o endereço não fosse encontrado. Acreditamos que retornar ZERO_RESULTS é uma resposta mais correta nesse tipo de situação.

Se o aplicativo lida com a inserção de endereços do usuário, o recurso Place Autocomplete da Places API pode produzir resultados de melhor qualidade. O Place Autocomplete permite que os usuários selecionem resultados de um conjunto baseado no que digitaram, o que permite que eles escolham resultados com nome parecido e ajustem a consulta caso tenham escrito um endereço errado.

Se as informações do aplicativo vêm de um sistema automatizado em que o usuário não seleciona uma opção de um conjunto de sugestões de preenchimento automático — e possivelmente lida com consultas ambíguas ou incompletas — ou de consultas que possam ter componentes que não fazem parte do endereço, como nome de estabelecimentos, o Text Search da Places API pode ser uma melhor opção. O Text Search tem mais chance de retornar um resultado para consultas ambíguas, já que esses tipos de consulta podem conter nomes de estabelecimentos, que a Geocoding API não leva em consideração.

Se você tem um aplicativo que lida com consultas ambíguas ou incompletas, ou com outras que possam ter componentes que não fazem parte do endereço, recomendamos usar a Places API em vez de o geocodificador inverso disponível na Geocoding API. Para ver mais detalhes, consulte as Práticas recomendadas para geocodificar endereços e a postagem Geocodificação de endereços nas Google Maps Google Maps APIs do blog.

Preciso de respostas rápidas, e o novo geocodificador é muito lento para o meu aplicativo. O que posso usar para acelerar o retorno das respostas?

Recomendamos que os aplicativos que respondem à interação do usuário e, portanto, são muito dependentes de uma baixa latência, usem o recurso Place Autocomplete da Places API (também disponível em JavaScript, Android ou iOS) em vez de a geocodificação de endereço. O Place Autocomplete foi otimizado para uso interativo e, portanto, tem muito pouca latência.

A geocodificação de endereço da Geocoding API foi otimizada para endereços completos, não ambíguos e bem formatados, como endereços de entrega inseridos em formulários eletrônicos e, por isso, tem maior latência que o Place Autocomplete. Esse é o caso com o geocodificador inverso antigo. A diferença de latência entre o Place Autocomplete e o novo geocodificador inverso é ainda maior, já que o novo geocodificador tem maior cobertura e oferece melhores resultados, mas a custo de um pouco mais de latência.

Como reduzo a latência da Directions API e da Distance Matrix API?

Em vez de endereços, use IDs de local para especificar pontos de referência, origem e destino. IDs de local são melhor obtidos com o recurso Place Autocomplete da Places API ou a biblioteca Places da Maps JavaScript API. Veja também as informações sobre a opção placeIdOnly, que pode ser usada para reduzir o custo do Place Autocomplete.

Quando a Directions API ou a Distance Matrix API é consultada com uma string de endereço em vez de um ID de local ou latitude/longitude, elas usam o mesmo back-end que a Geocoding API para converter o endereço em um ID de local antes de calcular rotas. O Place Autocomplete é mais rápido que a geocodificação de endereço. Para aplicativos que usam a Directions API ou a Distance Matrix API em situações de necessidade de latência muito baixa, como ao responder à interação do usuário, recomendamos usar o Place Autocomplete para obter os IDs de local correspondentes a esses endereços e passar esses IDs à Directions API ou à Distance Matrix API. Essa abordagem reduz muito a latência, mesmo se comparada com o geocodificador de endereços antigo. Acesse a nossa documentação para ver um exemplo de como usar o Place Autocomplete com rotas.

Sou cliente do Plano premium, e a Places API é muito cara. O que posso fazer para reduzir custos?

Recomendamos usar o widget Place autocomplete da Maps JavaScript API. Para reduzir o custo do uso do widget autocomplete, use a nova opção placeIdOnly para ativar o acesso direto a IDs de local pelo serviço Place Autocomplete. A opção placeIdOnly ignora solicitações de Places Details para aplicativos que só precisam de um endereço, e não dos detalhes completos do local. Para obter o endereço correspondente, passe IDs de local ao serviço de geocodificação ou à Geocoding API. Você ainda pode passar IDs de local ao serviço de rotas ou de matriz de distância, ou à Directions API ou à Distance Matrix API, em vez de passar uma string de texto do endereço ou coordenadas em latitude/longitude.

A Ferramenta Geocoder da Google Maps API e o exemplo do Directions e do Place Autocomplete foram atualizados para ilustrar como usar a nova opção placeIdOnly.

Como relato bugs do novo geocodificador?

Se você tem algum relatório de bugs ou solicitação de recurso para o novo serviço do geocodificador inverso, fale com a gente pelo nosso Issue Tracker, que é público.

O novo geocodificador não está produzindo bons resultados para o meu caso de uso. Como consigo ajuda?

Fale com a gente pelo Issue Tracker, que é aberto ao público, e mostre algumas consultas específicas que produzem resultados piores com o novo geocodificador para podermos investigar para ver se há bugs ou problemas sistêmicos prejudicando a qualidade dos resultados, ou até se há alguma modificação que podemos fazer no guia de práticas recomendadas para ajudar os desenvolvedores a ter resultados melhores.

A filtragem de componentes do novo geocodificador não funciona como a do antigo. Como faço para receber resultados melhores com o novo geocodificador usando esse recurso?

No novo geocodificador, a filtragem de componentes só tem suporte completo para resultados de endereço. Há suporte parcial para restrições de código de país (por exemplo, components=country:GB) e código postal para localidades e resultados mais complexos. Os exemplos a seguir ilustram a melhor forma de usar a filtragem de componentes, dependendo dos resultados de que você precisa. Nos URLs da solicitação de exemplo, não deixe de substituir “YOUR_API_KEY” pela sua chave de API.

  • Para restringir endereços (incluindo construções, ruas e estradas) a uma área política (país, localidade etc.), use a filtragem de componentes da mesma forma que no geocodificador antigo. É possível operar assim no novo geocodificador. Por exemplo: address=gordon&components=locality:dublin retorna "Gordon Way, Dublin, OH 43017, USA".
    https://maps.googleapis.com/maps/api/geocode/json?new_forward_geocoder=true&address=gordon&components=locality:dublin&key=YOUR_API_KEY
    
  • Para restringir códigos postais a um país específico, use a filtragem de componentes da mesma maneira que no geocodificador antigo, mas não deixe de especificar a restrição de país usando um código de país da ISO 3166-2. É possível operar assim no novo geocodificador. Por exemplo: components=country:CH|postal_code:2000 retorna "2000 Neuchâtel, Switzerland".
    https://maps.googleapis.com/maps/api/geocode/json?new_forward_geocoder=true&components=country:CH%7Cpostal_code:2000&key=YOUR_API_KEY
    
  • Para restringir outras consultas, que não envolvem endereço (cidades e bairros, por exemplo), a um país específico, use a filtragem de componentes da mesma forma que no geocodificador antigo, mas não deixe de especificar a restrição de país usando um código de país da ISO 3166-2. No novo geocodificador, você não tem garantias de que encontrará os mesmos resultados que no antigo. Use o Place Autocomplete para obter resultados melhores restritos ao país desejado.

    Exemplos:

    • Usando o geocodificador antigo, a geocodificação de components=country:US%7Clocality:paris retorna diversas cidades dos EUA chamadas “Paris”.
      https://maps.googleapis.com/maps/api/geocode/json?new_forward_geocoder=false&components=country:US%7Clocality:paris&key=YOUR_API_KEY
      
    • Já com o novo, a geocodificação de components=country:US%7Clocality:paris retorna "Paris, TX, USA”, mas não as outras cidades dos EUA com o nome “Paris”.
      https://maps.googleapis.com/maps/api/geocode/json?new_forward_geocoder=true&components=country:US%7Clocality:paris&key=YOUR_API_KEY
      
    • Usar o Place Autocomplete para input=paris&components=country:us&types=(regions), e especificar uma janela de visualização usando location e radius para polarizar os resultados de localização, gera uma resposta com diversas cidades dos EUA chamadas “Paris”.
      https://maps.googleapis.com/maps/api/place/autocomplete/json?location=37.386052,-122.083851&radius=10000&input=paris&components=country:us&types=(regions)&key=YOUR_API_KEY
      
  • Ao restringir outras consultas, que não envolvem endereço (cidades ou bairros, por exemplo), a uma área diferente de um país, não há garantias de que a filtragem de componentes no novo geocodificador encontrará os mesmos resultados que no antigo. Use o Place Autocomplete para obter melhores resultados polarizados à área especificada (location e radius). Você ainda pode usar o parâmetro strictbounds para restringir os resultados à área especificada.

    Exemplos:

    • Usando o geocodificador antigo, a geocodificação de administrative_area:Anaga|locality:Santa+Cruz retorna a localidade de Santa Cruz de Tenerife, além da área administrativa de Anaga.
      https://maps.googleapis.com/maps/api/geocode/json?new_forward_geocoder=false&components=administrative_area:Anaga%7Clocality:Santa%20Cruz&key=YOUR_API_KEY
      
    • Usando o novo geocodificador, a geocodificação de administrative_area:Anaga|locality:Santa+Cruz retorna apenas a área administrativa de Anaga, não Santa Cruz de Tenerife, que é a localidade pretendida.
      https://maps.googleapis.com/maps/api/geocode/json?new_forward_geocoder=true&components=administrative_area:Anaga%7Clocality:Santa%20Cruz&key=YOUR_API_KEY
      
    • Usar o Place Autocomplete para input=santa+cruz&location=28.494168,-16.275751&radius=20000&types=geocode retorna “Santa Cruz de Tenerife, Espanha” primeiro, além de outras cidades como “Santa Cruz de La Palma” (em uma outra ilha) e “Santa Cruz, CA, “Estados Unidos”.
      https://maps.googleapis.com/maps/api/place/autocomplete/json?input=santa+cruz&location=28.494168,-16.275751&radius=20000&types=geocode&key=YOUR_API_KEY
      
    • Adicione strictbounds à solicitação de Place Autocomplete acima para retornar resultados restritos à região especificada (“Anaga”).
      https://maps.googleapis.com/maps/api/place/autocomplete/json?input=santa+cruz&location=28.494168,-16.275751&radius=20000&types=geocode&strictbounds&key=YOUR_API_KEY
      

Enviar comentários sobre…

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