Solicitação e resposta de geocodificação inversa (busca de endereço)

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

O termo geocodificação geralmente se refere a traduzir um endereço legível em um local em um mapa. O processo oposto, ou seja, traduzir um local no mapa em um endereço legível, é conhecido como geocodificação inversa.

Solicitações de geocodificação inversas

Parâmetros obrigatórios

  • latlng: as coordenadas de latitude e longitude especificando o local para o qual você quer o endereço legível mais próximo.
  • key: a chave de API do aplicativo. Essa chave identifica seu aplicativo para fins de gerenciamento de cotas. Saiba como receber uma chave.

Parâmetros opcionais

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

  • language: o idioma em que os resultados serão retornados.
    • Consulte a lista de idiomas suportados. Como o Google atualiza os idiomas com suporte, talvez essa lista não seja completa.
    • Se language não for fornecido, o geocodificador tentará usar o idioma preferido, conforme especificado no cabeçalho Accept-Language, ou o idioma nativo do domínio a partir do qual a solicitação foi enviada.
    • O geocodificador faz o possível para fornecer um endereço legível para ambos os usuários e os habitantes locais. Para atingir esse objetivo, ele retorna endereços no idioma local, transliterado para um script legível pelo usuário, se necessário, observando o idioma preferido. Todos os outros endereços são retornados no idioma preferencial. Os componentes de endereço são retornados no mesmo idioma escolhido no primeiro componente.
    • Se um nome não estiver disponível no idioma preferencial, o geocodificador usará a correspondência mais próxima.
  • region: o código da região, especificado como um valor ccTLD ("domínio de nível superior") de dois caracteres. O parâmetro também pode afetar os resultados com base na legislação aplicável.
  • result_type: um filtro de um ou mais tipos de endereço, separados por uma barra vertical (|). Se o parâmetro contiver vários tipos de endereços, a API retornará todos os endereços que correspondam a qualquer um dos tipos. Observação sobre o processamento: o parâmetro result_type não restringe a pesquisa aos tipos de endereço especificados. Em vez disso, a result_type funciona como um filtro pós-pesquisa: a API busca todos os resultados para o latlng especificado e descarta aqueles que não correspondem aos tipos de endereço especificados. Os valores a seguir são aceitos:
    • street_address indica um endereço preciso.
    • route indica uma rota nomeada (como "US 101").
    • intersection indica uma interseção principal, normalmente de duas estradas principais.
    • 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 costuma ser 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 os estados. Nem todos os países têm esses níveis administrativos. Na maioria dos casos, nomes curtos para administrative_area_level_1 vão respeitar 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 vários sinais e dados de localização.
    • administrative_area_level_2 indica uma entidade civil de segunda ordem abaixo do nível de país. Nos Estados Unidos, esses níveis administrativos são os condados. Nem todos os países têm esses níveis administrativos.
    • administrative_area_level_3 indica uma entidade civil de terceira ordem abaixo do nível de 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 todos os países 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.
    • administrative_area_level_6 indica uma entidade civil de sexta 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_7 indica uma entidade civil de sétima ordem abaixo do nível de 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 usado comumente para a entidade.
    • locality indica uma entidade política de cidade ou município incorporada.
    • sublocality indica uma entidade civil de primeira ordem abaixo da localidade. Para alguns locais, é possível receber um dos tipos adicionais: sublocality_level_1 até sublocality_level_5. Cada nível de sublocalidade é uma entidade civil. Números maiores indicam uma área geográfica menor.
    • neighborhood indica um bairro nomeado
    • premise indica um local nomeado, normalmente um edifício ou condomínios com um nome comum
    • subpremise indica uma entidade de primeira ordem abaixo de uma localização com nome, geralmente um prédio dentro de um conjunto que prédios com um nome em comum
    • plus_code indica uma referência de local codificada, derivada de latitude e longitude. Os Plus Codes podem ser usados em vez de endereços nos lugares em que não existem, ou seja, quando os imóveis não estão numerados ou as ruas não têm nome. Para mais detalhes, consulte https://plus.codes.
    • postal_code indica um código postal, conforme usado para endereçar correspondências no país.
    • natural_feature indica um recurso natural de destaque.
    • airport indica um aeroporto.
    • park indica um parque nomeado.
    • point_of_interest indica um ponto de interesse nomeado. Normalmente, esses "PDIs" são entidades locais de destaque que não se encaixam facilmente em outra categoria, como "Empire State Building" ou "Torre Eiffel".
  • location_type: um filtro de um ou mais tipos de local, separados por uma barra vertical (|). Se o parâmetro contiver vários tipos de locais, a API retornará todos os endereços que correspondam a qualquer um dos tipos. Observação sobre o processamento: o parâmetro location_type não restringe a pesquisa aos tipos de local especificados. Em vez disso, o location_type atua como um filtro pós-pesquisa: a API busca todos os resultados para o latlng especificado e descarta os resultados que não correspondem aos tipos de local especificados. Os seguintes valores são aceitos:
    • "ROOFTOP" retorna apenas os endereços dos quais o Google tem informações de local com precisão de endereço.
    • "RANGE_INTERPOLATED" retorna apenas os endereços que refletem uma aproximação (geralmente em uma via) interpolada entre dois pontos precisos (como interseções). Um intervalo interpolado geralmente indica que os códigos geográficos da cobertura não estão disponíveis para um endereço.
    • "GEOMETRIC_CENTER" retorna apenas centros geométricos de uma localização, como uma polilinha (por exemplo, uma rua) ou um polígono (região).
    • "APPROXIMATE" retorna apenas os endereços que são caracterizados como aproximados.

Se os filtros result_type e location_type estiverem presentes, a API retornará somente os resultados que correspondem aos valores result_type e location_type. Se nenhum dos valores de filtro for aceitável, a API retornará ZERO_RESULTS.

Exemplo de geocodificação inversa

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

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 <code>results[]</code> ...

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

O geocodificador reverso relaciona entidades políticas (países, províncias, cidades e bairros), endereços e códigos postais.

Veja abaixo a lista completa de valores formatted_address retornados pela consulta anterior.

{
   "plus_code" : {
      "compound_code" : "P27Q+MCM New York, NY, USA",
      "global_code" : "87G8P27Q+MCM"
   },
   "results" : [
      {
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "street_address" ]
      },
      {
         "formatted_address" : "279 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "premise" ]
      },
      {
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "establishment", "point_of_interest" ]
      },
      {
         "formatted_address" : "291-275 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "route" ]
      },
      {
         "formatted_address" : "P27Q+MC New York, NY, USA",
         ...
         "types" : [ "plus_code" ]
      },
      {
         "formatted_address" : "South Williamsburg, Brooklyn, NY, USA",
         ...
         "types" : [ "neighborhood", "political" ]
      },
      {
         "formatted_address" : "Brooklyn, NY 11211, USA",
         ...
         "types" : [ "postal_code" ]
      },
      {
         "formatted_address" : "Williamsburg, Brooklyn, NY, USA",
         ...
         "types" : [ "neighborhood", "political" ]
      },
      {
         "formatted_address" : "Kings County, Brooklyn, NY, USA",
         ...
         "types" : [ "administrative_area_level_2", "political" ]
      },
      {
         "formatted_address" : "Brooklyn, NY, USA",
         ...
         "types" : [ "political", "sublocality", "sublocality_level_1" ]
      },
      {
         "formatted_address" : "New York, NY, USA",
         ...
         "types" : [ "locality", "political" ]
      },
      {
         "formatted_address" : "New York, USA",
         ...
         "types" : [ "administrative_area_level_1", "political" ]
      },
      {
         "formatted_address" : "United States",
         ...
         "types" : [ "country", "political" ]
      }
   ],
   "status" : "OK"
}

Essa API retorna diferentes tipos de endereços, desde o mais específico até as entidades políticas menos específicas, como bairros, cidades, municípios e estados. Geralmente, o endereço mais exato é o resultado mais proeminente, como nesse caso. Se você quiser corresponder a um tipo específico de endereço, consulte a seção abaixo sobre como restringir resultados por tipo. Por isso, o local dos resultados em relação um ao outro pode variar.

Geocodificação inversa filtrada por tipo

O exemplo a seguir filtra os endereços retornados para incluir apenas aqueles com um tipo de local ROOFTOP e 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:esses filtros só são válidos para a geocodificação inversa.

Respostas de geocodificação inversas

O formato da resposta de geocodificação inversa é igual ao da resposta de 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" no 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 por que a geocodificação inversa não está funcionando. 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 recebeu um latlng em um local remoto.
  • "OVER_QUERY_LIMIT" indica que você ultrapassou a cota.
  • "REQUEST_DENIED" indica que a solicitação foi negada. Possivelmente, porque a solicitação inclui um parâmetro result_type ou location_type, mas não uma chave de API.
  • "INVALID_REQUEST" geralmente indica uma das seguintes opções:
    • A consulta (address, components ou latlng) está ausente.
    • Um result_type ou location_type inválido foi informado.
  • "UNKNOWN_ERROR" indica que a solicitação não foi processada devido a um erro de servidor. Se você tentar novamente, a solicitação pode dar certo.

Geocodificação inversa com Plus Codes

O campo plus_code na resposta da Geocoding contém um Plus Code que se aproxima da latitude e longitude consultadas. Além disso, na maioria dos casos, a matriz de resultados JSON contém um resultado de geocodificação com um tipo plus_code e um endereço que contém um Plus Code. A distância entre o Plus Code decodificado e o ponto de solicitação é menor que 10 metros.