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

Guia do desenvolvedor

Este serviço também está disponível como parte da Google Maps JavaScript API do lado do cliente ou para uso do lado do servidor com Java Client, Python Client, Go Client e Node.js Client for Google Maps Services. Observação: os mesmos limites de uso se aplicam independentemente de como você usa o serviço. As solicitações por dia são calculadas como a soma das consultas do lado do cliente e do lado do servidor.

O que é a geocodificação?

Geocodificação é o processo de conversão de endereços (como "1600 Amphitheatre Parkway, Mountain View, CA") em coordenadas geográficas (como latitude 37.423021 e longitude -122.083739) que podem ser usadas para inserir marcadores em um mapa ou posicionar o mapa.

A geocodificação inversa é o processo de conversão de coordenadas geográficas em um endereço legível. O serviço de geocodificação inversa da Google Maps Geocoding API também permite que você encontre o endereço de um determinado ID de local.

A Google Maps Geocoding API oferece uma maneira direta de acessar esses serviços por meio de uma solicitação HTTP. Os exemplos a seguir usam o serviço de geocodificação pelo Google Maps JavaScript API para demonstrar a funcionalidade básica.

Veja este exemplo em tela cheia para visualizar a funcionalidade adicional da Geocoding API, como mais opções disponíveis para personalizar a solicitação (filtragem de componente e polarização de janela de visualização) e mais detalhes sobre cada resultado.

Antes de começar

Este documento descreve o serviço da Web da Google Maps Geocoding API. Ele é destinado a desenvolvedores de sites e dispositivos móveis que desejam usar dados de geocodificação em mapas fornecidos por uma das Google Maps APIs.

Observação: esse serviço geralmente tem como objetivo geocodificar endereços estáticos (já conhecidos) para inserir conteúdo do aplicativo em um mapa. Esse serviço não foi projetado para responder a consultas do usuário em tempo real. Para geocodificação dinâmica (por exemplo, em um elemento de interface do usuário), consulte a documentação do geocodificador do cliente da Google Maps JavaScript API e/ou as Google Play Services Location APIs.

A geocodificação é uma tarefa que demanda tempo e recursos. Sempre que possível, geocodifique endereços conhecidos antecipadamente (usando a Google Maps Geocoding API aqui descrita ou outro serviço de geocodificação) e armazene os resultados em um cache temporário que tenha projetado.

Para usar a Google Maps Geocoding API, você precisa de uma chave de API. Antes de começar a desenvolver com a Geocoding API, consulte os requisitos de autenticação e os limites de uso da API.

Formato de solicitação da Google Maps Geocoding API

Uma solicitação da Google Maps Geocoding API tem o seguinte formato:

https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters

onde outputFormat pode ser qualquer um dos seguintes valores:

  • json (recomendado) indica a saída em JavaScript Object Notation (JSON) ou
  • xml indica a saída em XML

Para acessar a Google Maps Geocoding API por HTTP, use:

http://maps.googleapis.com/maps/api/geocode/outputFormat?parameters

A segurança é importante e recomenda-se o uso de HTTPS sempre que possível, principalmente para aplicativos que incluam dados confidenciais de usuários nas solicitações, como a localização. O uso da criptografia HTTPS torna o aplicativo mais seguro e mais resistente a invasões ou adulterações.

Observação: URLs devem ser codificados corretamente para serem válidos e são limitados a 8192 caracteres para todos os serviços Web. Lembre-se deste limite ao construir seus URLs. Observe que diferentes navegadores, proxies e servidores podem ter outros limites de caracteres para URLs.

Alguns parâmetros são obrigatórios, enquanto outros são opcionais. Como é padrão em URLs, os parâmetros são separados usando o caractere E comercial (&).

O restante desta página descreve a geocodificação e a geocodificação inversa separadamente, pois parâmetros diferentes são disponibilizados para cada tipo de solicitação.

Geocodificação (busca de latitude/longitude)

Parâmetros obrigatórios para uma solicitação de geocodificação:

  • address — o endereço que você deseja geocodificar no formato usado pelo serviço postal do país em questão. Evite elementos adicionais de endereço, como nomes de empresas, números de unidades, salas ou andares. Consulte as perguntas frequentes para receber mais orientações.
         ou
    components — um filtro de componentes para o qual você deseja obter um código geográfico. Consulte Filtragem de componentes para saber mais. O filtro de componentes também será aceito como parâmetro opcional se um address for fornecido.
  • key — a chave de API do aplicativo. Essa chave identifica o aplicativo para fins de gerenciamento de cotas. Saiba como obter uma chave.

    Observação: clientes Google Maps APIs Premium Plan podem usar uma chave de API ou um ID de cliente válido e uma assinatura digital nas solicitações do Geocoding. Saiba mais sobre parâmetros de autenticação para clientes Premium Plan.

Parâmetros opcionais para uma solicitação de geocodificação:

  • bounds — a caixa limitadora da porta de visualização com base na qual os resultados de código geográfico devem ser direcionados de forma mais proeminente. Esse parâmetro apenas influencia, não restringe totalmente, os resultados do geocodificador. Para saber mais, consulte a seção Direcionamento de porta de visualização abaixo.
  • language — o idioma no qual retornar os resultados.
    • Confira a lista de idiomas suportados. O Google atualiza os idiomas suportados com frequência, portanto, esta lista pode não estar completa.
    • Se language não for fornecido, o geocodificador tentará usar o idioma preferencial conforme especificado no cabeçalho Accept-Language ou o idioma nativo do domínio do qual a solicitação foi enviada.
    • O geocodificador faz o possível para fornecer um endereço residencial legível tanto para o usuário quanto para os locais. Para atingir este objetivo, ele retorna os endereços residenciais no idioma local, transliterado para um script legível pelo usuário, se necessário, observando o idioma preferencial. Todos os outros endereços são retornados no idioma preferencial. Os componentes de endereço são todos retornados no mesmo idioma, escolhido pelo primeiro componente.
    • Se um nome não estiver disponível no idioma preferencial, o geocodificador usa a correspondência mais próxima.
    • O idioma preferencial tem uma pequena influência no conjunto de resultados que a API escolhe para retornar e na ordem em que é retornado. O codificador geográfico interpreta abreviações de formas variadas dependendo do idioma, como abreviações de tipos de rua ou sinônimos que podem ser válidos em um idioma, mas não em outros. Por exemplo, utca e tér são sinônimos para ruas em húngaro.
  • region — o código de região especificado como um valor de ccTLD ("domínio de nível superior") de dois caracteres. Esse parâmetro apenas influencia, não restringe totalmente, os resultados do geocodificador. Para saber mais, consulte a seção Direcionamento de região abaixo.
  • components — os filtros de componentes, separados por uma barra vertical (|). Cada filtro de componente consiste em um par component:value e restringe totalmente os resultados do geocodificador. Para saber mais, consulte Filtragem de componentes abaixo.

Respostas de geocodificação

As respostas de geocodificação são retornadas no formato indicado pelo sinalizador output dentro do caminho da solicitação de URL.

Neste exemplo, a Google Maps Geocoding API solicita uma resposta json para a consulta "1600 Amphitheatre Parkway, Mountain View, CA".

Esta solicitação demonstra o uso do sinalizador output de JSON:

https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

Esta solicitação demonstra o uso do sinalizador output de XML:

https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

Clique nas guias abaixo para ver as respostas para os exemplos de JSON e XML.

JSON
{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "1600",
               "short_name" : "1600",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Amphitheatre Pkwy",
               "short_name" : "Amphitheatre Pkwy",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Mountain View",
               "short_name" : "Mountain View",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Santa Clara County",
               "short_name" : "Santa Clara County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "California",
               "short_name" : "CA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "94043",
               "short_name" : "94043",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "1600 Amphitheatre Parkway, Mountain View, CA 94043, USA",
         "geometry" : {
            "location" : {
               "lat" : 37.4224764,
               "lng" : -122.0842499
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 37.4238253802915,
                  "lng" : -122.0829009197085
               },
               "southwest" : {
                  "lat" : 37.4211274197085,
                  "lng" : -122.0855988802915
               }
            }
         },
         "place_id" : "ChIJ2eUgeAK6j4ARbn5u_wAGqWA",
         "types" : [ "street_address" ]
      }
   ],
   "status" : "OK"
}

Observe que a resposta JSON contém dois elementos raiz:

  • "status" contém os metadados da solicitação. Consulte Códigos de status abaixo.
  • "results" contém uma matriz de informações de endereços geocodificados e informações geométricas.

Geralmente, somente uma entrada da matriz "results" é retornada para buscas de endereço, apesar de o geocodificador poder retornar diversos resultados quando as consultas de endereço são ambíguas.

Observe que esses resultados geralmente precisam ser analisados para que você possa extrair valores dos resultados. Analisar resultados em JSON é relativamente fácil. Consulte Analisar JSON para ver alguns padrões de projeto recomendados.

XML
<GeocodeResponse>
 <status>OK</status>
 <result>
  <type>street_address</type>
  <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address>
  <address_component>
   <long_name>1600</long_name>
   <short_name>1600</short_name>
   <type>street_number</type>
  </address_component>
  <address_component>
   <long_name>Amphitheatre Pkwy</long_name>
   <short_name>Amphitheatre Pkwy</short_name>
   <type>route</type>
  </address_component>
  <address_component>
   <long_name>Mountain View</long_name>
   <short_name>Mountain View</short_name>
   <type>locality</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>San Jose</long_name>
   <short_name>San Jose</short_name>
   <type>administrative_area_level_3</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>Santa Clara</long_name>
   <short_name>Santa Clara</short_name>
   <type>administrative_area_level_2</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>California</long_name>
   <short_name>CA</short_name>
   <type>administrative_area_level_1</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>United States</long_name>
   <short_name>US</short_name>
   <type>country</type>
   <type>political</type>
  </address_component>
  <address_component>
   <long_name>94043</long_name>
   <short_name>94043</short_name>
   <type>postal_code</type>
  </address_component>
  <geometry>
   <location>
    <lat>37.4217550</lat>
    <lng>-122.0846330</lng>
   </location>
   <location_type>ROOFTOP</location_type>
   <viewport>
    <southwest>
     <lat>37.4188514</lat>
     <lng>-122.0874526</lng>
    </southwest>
    <northeast>
     <lat>37.4251466</lat>
     <lng>-122.0811574</lng>
    </northeast>
   </viewport>
  </geometry>
  <place_id>ChIJ2eUgeAK6j4ARbn5u_wAGqWA</place_id>
 </result>
</GeocodeResponse>

Observe que a resposta XML consiste em um único elemento <GeocodeResponse> e dois elementos de nível superior:

  • <status> contém os metadados da solicitação. Consulte Códigos de status abaixo.
  • Zero ou mais elementos <result>, cada um contendo um conjunto de informações de endereço geocodificado e informações geométricas.

Observe que essa resposta é consideravelmente mais longa do que a resposta JSON. Por esse motivo, recomendamos o uso de json como sinalizador de saída preferencial, a menos que seu serviço exija xml por algum motivo. Além disso, o processamento de árvores XML exige certo cuidado para referenciar os nós e elementos corretos. Consulte Analisar XML com XPath para ver alguns padrões de projeto recomendados para o processamento da saída.

O restante deste documento usará a sintaxe JSON. Na maioria dos casos, o formato de saída não importa para os fins de demonstrar conceitos ou nomes de campos na documentação. Entretanto, observe as seguintes diferenças sutis:

  • Resultados XML são contidos em um elemento raiz <GeocodeResponse>.
  • JSON denota entradas com vários elementos de matrizes plurais (types), enquanto que XML denota entradas usando vários elementos singulares (<type>).
  • Elementos em branco são indicados por matrizes em branco em JSON, mas pela falta desses elementos em XML. Por exemplo, uma resposta que não gera resultados retornará uma matriz results vazia em JSON, mas nenhum elemento <result> em XML.

Códigos de status

O campo "status" do objeto de resposta de geocodificação contém o status da solicitação e pode conter informações de depuração para ajudar a rastrear o motivo de falhas de geocodificação: O campo "status" pode conter os seguintes valores:

  • "OK" indica que nenhum erro ocorreu; o endereço foi analisado e pelo menos um código geográfico foi retornado.
  • ZERO_RESULTS indica que o código geográfico foi bem-sucedido, mas não retornou resultados. Isso poderá ocorrer se o geocodificador receber um address que não existe.
  • "OVER_QUERY_LIMIT" indica que você ultrapassou a cota.
  • "REQUEST_DENIED" indica que a solicitação foi negada.
  • "INVALID_REQUEST" geralmente indica que a consulta (address, components ou latlng) está ausente.
  • "UNKNOWN_ERROR" indica que a solicitação não foi processada devido a um erro de servidor. A solicitação poderá ser bem-sucedida se você tentar novamente.

Mensagens de erro

Quando o geocodificador retorna um código de status diferente de OK, pode haver um campo error_message adicional dentro do objeto de resposta de geocodificação. Esse campo contém informações mais detalhadas sobre os motivos por trás do código de status.

Observação: não é garantido que esse campo esteja sempre presente e o conteúdo dele está sujeito a mudanças.

Resultados

Quando o geocodificador retorna resultados, ele os insere em uma matriz results (JSON). Mesmo que o geocodificador não retorne resultados (como quando o endereço não existe), ele ainda retorna uma matriz results vazia. Respostas XML consistem em zero ou mais elementos <result>.

Um resultado típico é composto pelos seguintes campos:

  • A matriz types[] indica o tipo do resultado retornado. Essa matriz contém um conjunto de zero ou mais tags que identificam o tipo de recurso retornado no resultado. Por exemplo, um código geográfico de "Chicago" retorna "locality", que indica que "Chicago" é uma cidade, e retorna também "political", indicando que é uma entidade política.

  • formatted_address é uma string que contém o endereço legível da localização. Frequentemente esse endereço é equivalente ao "endereço postal" que, algumas vezes, difere de um país para o outro. Observe que alguns países, como o Reino Unido, não permitem a distribuição de endereços postais verdadeiros devido a restrições de licenciamento. Esse endereço é geralmente composto de um ou mais componentes de endereço. Por exemplo, o endereço "111 8th Avenue, New York, NY" contém componentes de endereço separados para "111" (o número da rua), "8th Avenue" (a rota), "New York" (a cidade) e "NY" (o estado dos EUA). Esses componentes de endereço contém as informações adicionais mencionadas abaixo.

  • address_components[] é uma matriz que contém componentes de endereço separados, conforme é explicado acima. Cada address_component normalmente contém:

    • types[] é uma matriz que indica o tipo do componente do endereço.
    • long_name é a descrição completa em texto ou o nome do componente do endereço retornado pelo geocodificador.
    • short_name é um nome textual abreviado para o componente do endereço, se disponível. Por exemplo, um componente de endereço para o estado do Alasca pode ter um long_name de "Alaska" e um short_name de "AK", usando a abreviação postal de 2 letras.

    Observe que address_components[] pode conter mais componentes de endereço do que os mencionados no formatted_address.

  • postcode_localities[] é uma matriz que denota todas as localidades contidas em um código postal. Esse elemento só está presente quando o resultado é um código postal que contém várias localidades.
  • geometry contém as seguintes informações:

    • location contém o valor de latitude e longitude geocodificado. Para buscas normais de endereço, esse campo é normalmente o mais importante.
    • location_type armazena dados adicionais sobre a localização especificada. No momento, os seguintes valores são permitidos:

      • "ROOFTOP" indica que o resultado retornado é um código geográfico preciso para o qual temos informações de localização com precisão de endereço.
      • "RANGE_INTERPOLATED" indica que o resultado retornado reflete uma aproximação (normalmente em uma estrada) interpolada entre dois pontos precisos (como interseções). Resultados interpolados geralmente são retornados quando códigos geográficos de rooftop não estão disponíveis para um endereço.
      • "GEOMETRIC_CENTER" indica que o resultado retornado é o centro geométrico de um resultado, como uma polilinha (por exemplo, uma rua) ou um polígono (região).
      • "APPROXIMATE" indica que o resultado retornado é uma aproximação.
    • viewport contém a porta de visualização recomendada para exibir o resultado retornado, especificado como valores de latitude e longitude, definindo os cantos southwest e northeast da caixa de limitação da porta de visualização. Geralmente, a porta de visualização é usada para contornar um resultado exibido ao usuário.
    • bounds (opcional) armazena a caixa de limitação que pode conter o resultado retornado por completo. Observe que esses valores podem não corresponder à porta de visualização recomendada. Por exemplo, São Francisco inclui as ilhas Farallon que, tecnicamente, fazem parte da cidade, mas provavelmente não deveriam ser retornadas na porta de visualização.
  • partial_match indica que o geocodificador não retornou uma correspondência exata para a solicitação original, mas conseguiu corresponder parte do endereço solicitado. Pode ser recomendável verificar se a solicitação original inclui erros de ortografia e/ou um endereço incompleto.

    Correspondências parciais ocorrem com mais frequência para endereços que não existem na localidade onde você passou a solicitação. Elas também podem ser retornadas quando uma solicitação corresponde a dois ou mais locais na mesma localidade. Por exemplo, "21 Henr St, Bristol, UK" retornará uma correspondência parcial para Henry Street e Henrietta Street. Observe que, se uma solicitação incluir um componente de endereço com um erro ortográfico, o serviço de geocodificação poderá sugerir um endereço alternativo. Sugestões acionadas dessa maneira também serão marcadas como correspondências parciais.

  • place_id é um identificador exclusivo que pode ser usado com outras APIs do Google. Por exemplo, você pode usar o place_id em uma solicitação da Google Places API para obter detalhes sobre um estabelecimento local, como número de telefone, horários de funcionamento, comentários de usuários e muito mais. Consulte a visão geral de IDs de local.

Como o formato exato de uma resposta individual para uma solicitação daGoogle Maps Geocoding API não é garantido, nunca presuma que os elementos estão em posições absolutas. Em particular, o número de address_components em uma resposta da Geocoding API varia de acordo com o endereço solicitado e pode mudar ao longo do tempo. Em vez disso, você deve analisar a resposta e selecionar os valores apropriados por meio de expressões. Consulte Analisar respostas do Web Service para saber mais.

Tipos de endereço e tipos de componentes de endereço

A matriz types[] no resultado indica o tipo de endereço. Exemplos de tipos de endereço incluem ruas, países ou entidades políticas. Há também uma matriz types[] em address_components[], indicando o tipo de cada parte do endereço. Exemplos incluem números de rua ou países. Veja abaixo uma lista completa de tipos. Os endereços podem ter vários tipos. Os tipos podem ser considerados "tags". Por exemplo, muitas cidades incluem as tags de tipo political e locality.

Os tipos a seguir são permitidos e retornados pelo geocodificador em matrizes de tipo de endereço e tipo de componente de endereço:

  • street_address indica um endereço preciso.
  • route indica uma rota com nome (como "US 101").
  • intersection indica uma interseção, geralmente de duas vias importantes.
  • political indica uma entidade política. Normalmente, esse tipo indica um polígono de administração civil.
  • country indica a entidade política nacional e normalmente é o tipo de ordem mais elevada retornado pelo geocodificador.
  • administrative_area_level_1 indica uma entidade civil de primeira ordem abaixo do nível do país. Nos Estados Unidos, esses níveis administrativos são estados. Nem todas as nações incluem esses níveis administrativos. Na maioria dos casos, nomes curtos para administrative_area_level_1 respeitarão quase que totalmente as subdivisões da ISO 3166-2 e outras normas amplamente divulgadas, porém isso não é garantido, já que os resultados da nossa geocodificação se baseiam em diversos sinais e dados de localização.
  • administrative_area_level_2 indica uma entidade civil de segunda ordem abaixo do nível do país. Nos Estados Unidos, esses níveis administrativos são condados. Nem todos os países incluem esses níveis administrativos.
  • administrative_area_level_3 indica uma entidade civil de terceira ordem abaixo do nível do país. Esse tipo indica uma divisão civil secundária. Nem todos os países incluem esses níveis administrativos.
  • administrative_area_level_4 indica uma entidade civil de quarta ordem abaixo do nível do país. Esse tipo indica uma divisão civil secundária. Nem todas as nações incluem esses níveis administrativos.
  • administrative_area_level_5 indica uma entidade civil de quinta ordem abaixo do nível do país. Esse tipo indica uma divisão civil secundária. Nem todos os países incluem esses níveis administrativos.
  • colloquial_area indica um nome alternativo comumente usado para a entidade.
  • locality indica uma entidade política de cidade ou município incorporada.
  • ward indica um tipo específico de localidade japonesa para facilitar a distinção entre vários componentes de localidades em um endereço no Japão.
  • sublocality indica uma entidade civil de primeira ordem abaixo da localidade. Algumas localizações podem receber um destes tipos adicionais: sublocality_level_1 a sublocality_level_5. Cada nível de sublocalidade é uma entidade civil. Números maiores indicam uma área geográfica menor.
  • neighborhood indica um bairro com nome
  • premise indica um local com nome, geralmente um prédio ou um conjunto que prédios com um nome em comum
  • premise indica uma entidade de primeira ordem abaixo de um local com nome, geralmente um prédio dentro de um conjunto que prédios com um nome em comum
  • postal_code indica um código postal usado pelo serviço postal do país.
  • natural_feature indica uma característica natural proeminente.
  • airport indica um aeroporto.
  • park indica um parque com nome.
  • point_of_interest indica um ponto de interesse com nome. Normalmente, pontos de interesse são entidades locais que não se encaixam facilmente em outra categoria, como o Empire State Building ou a Estátua da Liberdade.

Uma lista vazia indica que não há tipos conhecidos para um componente de endereço específico, por exemplo, Lieu-dit na França.

Além do indicado acima, os componentes de endereço podem incluir os tipos abaixo.

Observação: essa lista não é completa e está sujeita a mudanças.

  • floor indica o andar no endereço de um edifício.
  • establishment normalmente indica um local que ainda não foi categorizado.
  • point_of_interest indica um ponto de interesse com nome.
  • parking indica um estacionamento.
  • post_box indica uma caixa postal específica.
  • postal_town indica um agrupamento de áreas geográficas, como locality e sublocality, usadas como endereços para correspondência em alguns países.
  • room indica a sala no endereço de um edifício.
  • street_number indica o número exato do local na rua.
  • bus_station, train_station e transit_station indicam a localização de uma parada de ônibus, trem ou transporte público.

Direcionamento de porta de visualização

Em uma solicitação de geocodificação, é possível instruir o serviço da Geocoding API a dar preferência a resultados que se encaixem em uma determinada porta de visualização (expressada como uma caixa de limitação). Isso é feito no URL da solicitação, definindo o parâmetro bounds. Observe que o direcionamento somente prioriza resultados dentro dos limites. Se resultados mais relevantes existirem fora desses limites, eles poderão ser incluídos.

O parâmetro bounds define as coordenadas de latitude/longitude dos cantos sudoeste e nordeste dessa caixa de limitação usando um caractere de barra vertical (|) para separar as coordenadas.

Por exemplo, um código geográfico para "Winnetka" geralmente retorna este subúrbio de Chicago:

Solicitação:

https://maps.googleapis.com/maps/api/geocode/json?address=Winnetka&key=YOUR_API_KEY

Resposta:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Winnetka",
               "short_name" : "Winnetka",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "New Trier",
               "short_name" : "New Trier",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Cook County",
               "short_name" : "Cook County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Illinois",
               "short_name" : "IL",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Winnetka, IL, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 42.1282269,
                  "lng" : -87.7108162
               },
               "southwest" : {
                  "lat" : 42.0886089,
                  "lng" : -87.7708629
               }
            },
            "location" : {
               "lat" : 42.10808340000001,
               "lng" : -87.735895
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 42.1282269,
                  "lng" : -87.7108162
               },
               "southwest" : {
                  "lat" : 42.0886089,
                  "lng" : -87.7708629
               }
            }
         },
         "place_id" : "ChIJW8Va5TnED4gRY91Ng47qy3Q",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Entretanto, adicionar um argumento bounds que defina uma caixa de limitação para San Fernando Valley de Los Angeles resulta no retorno de um bairro chamado "Winnetka" nessa localização:

Solicitação:

https://maps.googleapis.com/maps/api/geocode/json?address=Winnetka&bounds=34.172684,-118.604794|34.236144,-118.500938&key=YOUR_API_KEY

Resposta:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Winnetka",
               "short_name" : "Winnetka",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Los Angeles",
               "short_name" : "LA",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Los Angeles County",
               "short_name" : "Los Angeles County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "California",
               "short_name" : "CA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Winnetka, Los Angeles, CA, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 34.2355209,
                  "lng" : -118.5534191
               },
               "southwest" : {
                  "lat" : 34.1854649,
                  "lng" : -118.588536
               }
            },
            "location" : {
               "lat" : 34.2048586,
               "lng" : -118.5739621
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 34.2355209,
                  "lng" : -118.5534191
               },
               "southwest" : {
                  "lat" : 34.1854649,
                  "lng" : -118.588536
               }
            }
         },
         "place_id" : "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ",
         "types" : [ "neighborhood", "political" ]
      }
   ],
   "status" : "OK"
}

Direcionamento de região

Em uma resposta de geocodificação, a Google Maps Geocoding API retorna resultados de endereço influenciados pela região (normalmente o país) do qual a solicitação foi enviada. Por exemplo, pesquisas de "San Francisco" podem retornar resultados diferentes se elas forem enviadas de um domínio nos Estados Unidos em vez de um na Espanha.

Também é possível configurar a Google Maps Geocoding API para retornar resultados direcionados a uma região específica usando o parâmetro region. Esse parâmetro aceita um argumento ccTLD (domínio de nível superior de código de país) especificando o direcionamento de região. A maioria dos códigos ccTLD é idêntica aos códigos ISO 3166-1, com algumas exceções notáveis. Por exemplo, o ccTLD do Reino Unido é "uk" (.co.uk), enquanto seu código ISO 3166-1 é "gb" (tecnicamente, para a entidade do “Reino Unido da Grã-Bretanha e da Irlanda do Norte”).

Os resultados de geocodificação podem ser direcionados para qualquer domínio no qual o aplicativo principal do Google Maps tenha sido lançado oficialmente. Observe que o direcionamento somente dá preferência a um domínio específico. Se resultados mais relevantes existirem fora desse domínio, eles poderão ser incluídos.

Por exemplo, um código geográfico para "Toledo" retorna esse resultado, já que o domínio padrão da Google Maps Geocoding API é definido como os Estados Unidos. Solicitação:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY

Resposta:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lucas County",
               "short_name" : "Lucas County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Ohio",
               "short_name" : "OH",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, OH, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.4547053
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            },
            "location" : {
               "lat" : 41.6639383,
               "lng" : -83.55521200000001
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 41.732844,
                  "lng" : -83.4547053
               },
               "southwest" : {
                  "lat" : 41.580266,
                  "lng" : -83.69423700000002
               }
            }
         },
         "place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
         "types" : [ "locality", "political" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lincoln County",
               "short_name" : "Lincoln County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Oregon",
               "short_name" : "OR",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, OR, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 44.6383219,
                  "lng" : -123.9129439
               },
               "southwest" : {
                  "lat" : 44.598776,
                  "lng" : -123.954585
               }
            },
            "location" : {
               "lat" : 44.621507,
               "lng" : -123.9384478
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 44.6383219,
                  "lng" : -123.9129439
               },
               "southwest" : {
                  "lat" : 44.598776,
                  "lng" : -123.954585
               }
            }
         },
         "place_id" : "ChIJmcjO1AjUwVQRDsRYrfWvzyo",
         "types" : [ "locality", "political" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Tama County",
               "short_name" : "Tama County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Iowa",
               "short_name" : "IA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, IA, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 42.00388600000001,
                  "lng" : -92.56695289999999
               },
               "southwest" : {
                  "lat" : 41.9784431,
                  "lng" : -92.60007299999999
               }
            },
            "location" : {
               "lat" : 41.9972134,
               "lng" : -92.5835266
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 42.00388600000001,
                  "lng" : -92.56695289999999
               },
               "southwest" : {
                  "lat" : 41.9784431,
                  "lng" : -92.60007299999999
               }
            }
         },
         "place_id" : "ChIJvwoVNEOE74cR3oQfIk7m6fU",
         "types" : [ "locality", "political" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Lewis County",
               "short_name" : "Lewis County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Washington",
               "short_name" : "WA",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "98591",
               "short_name" : "98591",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Toledo, WA 98591, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 46.44799889999999,
                  "lng" : -122.8419249
               },
               "southwest" : {
                  "lat" : 46.43233009999999,
                  "lng" : -122.85575
               }
            },
            "location" : {
               "lat" : 46.4398305,
               "lng" : -122.846783
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 46.44799889999999,
                  "lng" : -122.8419249
               },
               "southwest" : {
                  "lat" : 46.43233009999999,
                  "lng" : -122.85575
               }
            }
         },
         "place_id" : "ChIJPw9m6cb4k1QRyA5L3wI_dRM",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Uma solicitação de geocodificação para "Toledo" com region=es (Espanha) retornará a cidade espanhola. Solicitação:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&region=es&key=YOUR_API_KEY

Resposta:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Toledo",
               "short_name" : "Toledo",
               "types" : [ "administrative_area_level_4", "political" ]
            },
            {
               "long_name" : "Vega de Toledo",
               "short_name" : "Vega de Toledo",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Toledo",
               "short_name" : "TO",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Castile-La Mancha",
               "short_name" : "CM",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Toledo, Toledo, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0629256
               }
            },
            "location" : {
               "lat" : 39.8628316,
               "lng" : -4.027323099999999
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 39.88605099999999,
                  "lng" : -3.9192423
               },
               "southwest" : {
                  "lat" : 39.8383676,
                  "lng" : -4.0629256
               }
            }
         },
         "place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Filtragem de componentes

Em uma resposta de geocodificação, a Google Maps Geocoding API pode retornar resultados de endereço restritos a uma área específica. A restrição é especificada usando o filtro components. Um filtro consiste em uma lista de pares component:value separados por uma barra vertical (|). Somente resultados que correspondem a todos os filtros serão retornados. Os valores de filtro são compatíveis com os mesmos métodos de correção ortográfica e correspondência parcial de outras solicitações de geocodificação. Se um resultado de geocodificação for uma correspondência parcial para um filtro de componente, ele conterá um campo partial_match na resposta.

Os components que podem ser filtrados incluem:

  • route corresponde ao nome longo ou curto de uma rota.
  • locality corresponde aos tipos locality e sublocality.
  • administrative_area corresponde a todos os níveis administrative_area.
  • postal_code corresponde a postal_code e postal_code_prefix.
  • country corresponde ao nome do país ou a um código de país ISO 3166-1 de duas letras.

    Observação: seguimos o padrão ISO para definir os países para que a filtragem funcione melhor ao usar o código de norma ISO correspondente do país.

Observação: cada componente de endereço só pode ser especificado no parâmetro address ou como um filtro de componente, mas não ambos. Isso pode resultar em ZERO_RESULTS.

Um código geográfico para "Santa Cruz" com components=country:ES retornará Santa Cruz de Tenerife nas Ilhas Canárias, Espanha. Solicitação:

https://maps.googleapis.com/maps/api/geocode/json?address=santa+cruz&components=country:ES&key=YOUR_API_KEY

Resposta:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "Santa Cruz de Tenerife",
               "types" : [ "locality", "political" ]
            },
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "Santa Cruz de Tenerife",
               "types" : [ "administrative_area_level_4", "political" ]
            },
            {
               "long_name" : "Anaga",
               "short_name" : "Anaga",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Santa Cruz de Tenerife",
               "short_name" : "TF",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "Canarias",
               "short_name" : "CN",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "Spain",
               "short_name" : "ES",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Santa Cruz de Tenerife, Santa Cruz de Tenerife, Spain",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            },
            "location" : {
               "lat" : 28.4636296,
               "lng" : -16.2518467
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 28.487616,
                  "lng" : -16.2356646
               },
               "southwest" : {
                  "lat" : 28.4280248,
                  "lng" : -16.3370045
               }
            }
         },
         "place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
         "types" : [ "locality", "political" ]
      }
   ],
   "status" : "OK"
}

Uma consulta que contenha um filtro de componente retornará somente os resultados de geocodificação que correspondam ao filtro. Se nenhuma correspondência for encontrada, o geocodificador retornará um resultado que corresponda ao filtro em si. Solicitação:

https://maps.googleapis.com/maps/api/geocode/json?address=Torun&components=administrative_area:TX|country:US&key=YOUR_API_KEY

Resposta:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Texas",
               "short_name" : "TX",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Texas, USA",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 36.5007041,
                  "lng" : -93.5080389
               },
               "southwest" : {
                  "lat" : 25.8371638,
                  "lng" : -106.6456461
               }
            },
            "location" : {
               "lat" : 31.9685988,
               "lng" : -99.9018131
            },
            "location_type" : "APPROXIMATE",
            "viewport" : {
               "northeast" : {
                  "lat" : 36.5015087,
                  "lng" : -93.5080389
               },
               "southwest" : {
                  "lat" : 25.8371638,
                  "lng" : -106.6456461
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJSTKCCzZwQIYRPN4IGI8c6xY",
         "types" : [ "administrative_area_level_1", "political" ]
      }
   ],
   "status" : "OK"
}

A filtragem de componente retornará uma resposta ZERO_RESULTS somente se você fornecer filtros que se excluam. Solicitação:

https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY

Resposta:

{
   "results" : [],
   "status" : "ZERO_RESULTS"
}

Ao usar o filtro components, é possível fazer uma consulta sem o parâmetro address, mas não especificar um componente sem um valor. Solicitação:

https://maps.googleapis.com/maps/api/geocode/json?components=route:Annegatan|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY

Resposta:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "Annegatan",
               "short_name" : "Annegatan",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Helsingfors",
               "short_name" : "Helsingfors",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            }
         ],
         "formatted_address" : "Annegatan, Helsingfors, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9427959
               },
               "southwest" : {
                  "lat" : 60.1626627,
                  "lng" : 24.934
               }
            },
            "location" : {
               "lat" : 60.1657808,
               "lng" : 24.938451
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.168997,
                  "lng" : 24.9427959
               },
               "southwest" : {
                  "lat" : 60.1626627,
                  "lng" : 24.934
               }
            }
         },
         "place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
         "types" : [ "route" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Annevägen",
               "short_name" : "Annevägen",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Vanda",
               "short_name" : "Vanda",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "01420",
               "short_name" : "01420",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Annevägen, 01420 Vanda, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.3282738,
                  "lng" : 25.1162163
               },
               "southwest" : {
                  "lat" : 60.32564009999999,
                  "lng" : 25.1076474
               }
            },
            "location" : {
               "lat" : 60.3271069,
               "lng" : 25.1118046
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.3283059302915,
                  "lng" : 25.1162163
               },
               "southwest" : {
                  "lat" : 60.32560796970849,
                  "lng" : 25.1076474
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJ3UJCNt4GkkYR8-_a8Dh25kA",
         "types" : [ "route" ]
      },
      {
         "address_components" : [
            {
               "long_name" : "Anneplatsen",
               "short_name" : "Anneplatsen",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Helsingfors",
               "short_name" : "Helsingfors",
               "types" : [ "administrative_area_level_3", "political" ]
            },
            {
               "long_name" : "Finland",
               "short_name" : "FI",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "00100",
               "short_name" : "00100",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "Anneplatsen, 00100 Helsingfors, Finland",
         "geometry" : {
            "bounds" : {
               "northeast" : {
                  "lat" : 60.1695664,
                  "lng" : 24.9357125
               },
               "southwest" : {
                  "lat" : 60.168997,
                  "lng" : 24.934
               }
            },
            "location" : {
               "lat" : 60.1692741,
               "lng" : 24.9348016
            },
            "location_type" : "GEOMETRIC_CENTER",
            "viewport" : {
               "northeast" : {
                  "lat" : 60.17063068029151,
                  "lng" : 24.9362052302915
               },
               "southwest" : {
                  "lat" : 60.1679327197085,
                  "lng" : 24.9335072697085
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJeahMqswLkkYR2vQfG1nHI3M",
         "types" : [ "route" ]
      }
   ],
   "status" : "OK"
}

Geocodificação inversa (busca de endereço)

O termo geocodificação geralmente se refere à conversão de um endereço legível em uma localização em um mapa. O processo oposto, ou seja, converter uma localização em um mapa em um endereço legível, é conhecido como geocodificação inversa.

Parâmetros necessários para uma solicitação de geocodificação inversa:

  • latlng — os valores de latitude e longitude que especificam a localização para a qual você deseja obter o endereço legível mais próximo.
         ou
    place_id — o ID de local da localização para a qual você deseja obter o endereço legível. O ID de local é um identificador exclusivo que pode ser usado com outras APIs do Google. Por exemplo, você pode usar o placeID retornado pela Google Maps Roads API para obter o endereço de um ponto registrado. Para saber mais sobre IDs de local, consulte a visão geral de IDs de local. O ID de local só poderá ser especificado se a solicitação incluir uma chave de API ou um ID de cliente da Google Maps APIs Premium Plan.
  • key — a chave de API do aplicativo. Essa chave identifica o aplicativo para fins de gerenciamento de cotas. Saiba como obter uma chave.

    Observação: clientes Google Maps APIs Premium Plan podem usar uma chave de API ou um ID de cliente válido e assinatura digital nas solicitações do Geocoding invertidas. Saiba mais sobre parâmetros de autenticação para clientes Premium Plan.

Parâmetros opcionais para uma solicitação de geocodificação inversa:

Veja a seguir os parâmetros opcionais que você pode incluir em uma solicitação de geocodificação inversa:

  • language — o idioma no qual retornar os resultados.
    • Confira a lista de idiomas suportados. O Google atualiza os idiomas suportados com frequência, portanto, esta lista pode não estar completa.
    • Se language não for fornecido, o geocodificador tentará usar o idioma preferencial conforme especificado no cabeçalho Accept-Language ou o idioma nativo do domínio do qual a solicitação foi enviada.
    • O geocodificador faz o possível para fornecer um endereço residencial legível tanto para o usuário quanto para os locais. Para atingir este objetivo, ele retorna os endereços residenciais no idioma local, transliterado para um script legível pelo usuário, se necessário, observando o idioma preferencial. Todos os outros endereços são retornados no idioma preferencial. Os componentes de endereço são todos retornados no mesmo idioma, escolhido pelo primeiro componente.
    • Se um nome não estiver disponível no idioma preferencial, o geocodificador usa a correspondência mais próxima.
  • result_type — um ou mais tipos de endereço, separados por uma barra vertical (|). Exemplos de tipos de endereço: country, street_address, postal_code. Para obter uma lista completa dos valores permitidos, consulte os tipos permitidos nesta página. Especificar um tipo restringe os resultados ao tipo em questão. Se vários tipos forem especificados, a API retornará todos os endereços que correspondam a qualquer um dos tipos. Observação: esse parâmetro está disponível somente para solicitações que incluam uma chave de API ou um ID de cliente.
  • location_type — um ou mais tipos de localização, separados por uma barra vertical (|). Especificar um tipo restringe os resultados ao tipo em questão. Se vários tipos forem especificados, a API retornará todos os endereços que correspondam a qualquer um dos tipos. Observação: esse parâmetro está disponível somente para solicitações que incluam uma chave de API ou um ID de cliente. Os valores a seguir são suportados:
    • "ROOFTOP" restringe os resultados a endereços para os quais temos informações de localização com precisão de endereço.
    • "RANGE_INTERPOLATED" restringe os resultados àqueles que reflitam uma aproximação (normalmente em uma estrada) interpolada entre dois pontos precisos (como interseções). Uma faixa interpolada geralmente indica que códigos geográficos de rooftop não estão disponíveis para um endereço.
    • "GEOMETRIC_CENTER" restringe os resultados a centros geométricos de uma localização, como uma polilinha (por exemplo, uma rua) ou um polígono (região).
    • "APPROXIMATE" restringe os resultados àqueles que são caracterizados como aproximações.

Se as restrições result_type e location_type estiverem presentes, a API retornará somente resultados que correspondam às restrições result_type e location_type.

Geocodificação inversa para latitude/longitude

A consulta a seguir contém um valor de latitude/longitude para uma localização no Brooklyn:

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY

Observação: não insira espaços entre os valores de latitude e longitude ao passar o parâmetro latlng.

A consulta acima retorna o seguinte resultado:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "277",
               "short_name" : "277",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Bedford Avenue",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "sublocality", "political" ]
            },
            {
               "long_name" : "Kings",
               "short_name" : "Kings",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "New York",
               "short_name" : "NY",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "11211",
               "short_name" : "11211",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
         "geometry" : {
            "location" : {
               "lat" : 40.714232,
               "lng" : -73.9612889
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 40.7155809802915,
                  "lng" : -73.9599399197085
               },
               "southwest" : {
                  "lat" : 40.7128830197085,
                  "lng" : -73.96263788029151
               }
            }
         },
         "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
         "types" : [ "street_address" ]
      },

  ... Additional results[] ...

Observe que o geocodificador inverso retornou mais de um resultado. Os resultados de "formatted_address" não são apenas endereços postais, mas qualquer forma de nomear um local geograficamente. Por exemplo, ao geocodificar um ponto da cidade de Chicago, o ponto geocodificado pode ser denotado como um endereço, como a cidade (Chicago), como o estado (Illinois) ou como o país (Estados Unidos). Todas essas opções são "endereços" para o geocodificador. O geocodificador inverso retorna qualquer um desses tipos como resultados válidos.

Ele pode corresponder entidades políticas (países, províncias, cidades e bairros), endereços e códigos postais.

A lista completa de valores de formatted_address retornados pela consulta anterior é mostrada abaixo.

"formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
"formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11211, USA",
"formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11249, USA",
"formatted_address" : "Bedford Av/Grand St, Brooklyn, NY 11211, USA",
"formatted_address" : "Brooklyn, NY 11211, USA",
"formatted_address" : "Williamsburg, Brooklyn, NY, USA",
"formatted_address" : "Brooklyn, NY, USA",
"formatted_address" : "New York, NY, USA",
"formatted_address" : "New York, USA",
"formatted_address" : "United States",

Geralmente, os endereços são retornados em ordem do mais específico para o menos específico. Quanto mais preciso for um endereço, mais proeminente ele será nos resultados, como neste caso. Observe que retornamos diferentes tipos de endereço, desde o endereço mais específico até entidades políticas menos específicas, como bairros, cidades, estados, países etc. Se quiser corresponder a um tipo específico de endereço, consulte a seção abaixo sobre como restringir endereços por tipo.

Observação: a geocodificação inversa é uma estimativa. O geocodificador tentará encontrar a localização endereçável mais próxima dentro de uma determinada tolerância. Se nenhuma correspondência for encontrada, o geocodificador não retornará resultados.

Geocodificação inversa para ID de local

A consulta a seguir contém um ID de local para uma localização no Brooklyn:

https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJd8BlQ2BZwokRAFUEcm_qrcA&key=YOUR_API_KEY

A consulta acima retorna o seguinte resultado:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "277",
               "short_name" : "277",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Bedford Ave",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "sublocality_level_1", "sublocality", "political" ]
            },
            {
               "long_name" : "Kings County",
               "short_name" : "Kings County",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "New York",
               "short_name" : "NY",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "11211",
               "short_name" : "11211",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         "geometry" : {
            "location" : {
               "lat" : 40.714232,
               "lng" : -73.9612889
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 40.7155809802915,
                  "lng" : -73.9599399197085
               },
               "southwest" : {
                  "lat" : 40.7128830197085,
                  "lng" : -73.96263788029151
               }
            }
         },
         "partial_match" : true,
         "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
         "types" : [ "street_address" ]
      }
   ],
   "status" : "OK"
}

Codificação inversa restringida por tipo

O exemplo a seguir restringe os endereços retornados para aqueles com tipo de localização de ROOFTOP e tipo de endereço de street_address.

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&location_type=ROOFTOP&result_type=street_address&key=YOUR_API_KEY

Observação: essas restrições só são válidas para a codificação inversa.

Respostas de geocodificação inversa

O formato das respostas de geocodificação inversa é o mesmo da geocodificação. Consulte Respostas de geocodificação. Veja abaixo os códigos de status possíveis em uma resposta de geocodificação inversa.

Códigos de status de geocodificação inversa

O campo "status" do objeto de resposta de geocodificação contém o status da solicitação e pode conter informações de depuração para ajudar a rastrear o motivo de falhas de geocodificação inversa: O campo "status" pode conter os seguintes valores:

  • "OK" indica que nenhum erro ocorreu e que pelo menos um endereço foi retornado.
  • "ZERO_RESULTS" indica que a geocodificação inversa foi bem-sucedida, mas não retornou resultados. Isso pode ocorrer se o geocodificador receber latlng em um local remoto.
  • “OVER_QUERY_LIMIT” indica que você ultrapassou a cota.
  • "REQUEST_DENIED" indica que a solicitação foi negada. Isso pode ocorrer devido a solicitação incluir um parâmetro result_type ou location_type, mas não uma chave de API ou um ID de cliente.
  • "INVALID_REQUEST" geralmente indica uma das seguintes situações:
    • A consulta (address, components ou latlng) está ausente.
    • Um parâmetro result_type ou location_type inválido foi fornecido.
  • “UNKNOWN_ERROR” indica que a solicitação não foi processada devido a um erro de servidor. A solicitação poderá ser bem-sucedida se você tentar novamente.

O parâmetro sensor

Anteriormente, a Google Maps API exigia a inclusão do parâmetro sensor para indicar se o aplicativo usou um sensor para determinar a localização do usuário. Esse parâmetro não é mais obrigatório.

Enviar comentários sobre…

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