Solicitação e resposta de geocodificação reversa (pesquisa de endereço)

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

Solicitações de geocodificação inversa

Parâmetros obrigatórios

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

Parâmetros opcionais

Estes são os parâmetros opcionais que podem ser incluídos em uma solicitação de geocodificação reversa:

  • language: o idioma em que os resultados serão retornados.
    • Consulte a lista de idiomas aceitos. O Google atualiza com frequência os idiomas compatíveis. Por isso, esta lista pode não estar completa.
    • Se language não for fornecido, o geocodificador tentará usar o idioma preferido especificado no cabeçalho Accept-Language ou o idioma nativo do domínio de onde a solicitação é enviada.
    • O geocodificador faz o possível para fornecer um endereço que seja legível para o usuário e para os moradores. Para alcançar esse objetivo, ele retorna endereços no idioma local, transliterados para uma escrita legível pelo usuário, se necessário, observando o idioma preferido. Todos os outros endereços são retornados no idioma preferido. Os componentes do endereço são retornados no mesmo idioma, que é escolhido a partir do primeiro componente.
    • Se um nome não estiver disponível no idioma preferido, o geocodificador vai 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 um pipe (|). Se o parâmetro tiver vários tipos de endereço, a API vai retornar todos os endereços que correspondem 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, o result_type atua 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 seguintes valores são aceitos:

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

    A matriz types no corpo GeocodeResult na resposta indica o tipo de endereço. Exemplos de tipos de endereço incluem um endereço de rua, um país ou uma entidade política. A matriz types no campo AddressComponents do corpo GeocodeResult indica o tipo de cada parte do endereço. Exemplos incluem números de rua ou países.

    Os endereços podem ter vários tipos. Os tipos podem ser considerados "tags". Por exemplo, muitas cidades são marcadas com os tipos political e locality.

    Os tipos a seguir são aceitos e retornados nas matrizes de tipo de endereço e de componente de endereço:

    Tipo de endereço Descrição
    street_address Um endereço preciso.
    route Uma rota nomeada (como "US 101").
    intersection Uma interseção principal, normalmente de duas estradas principais.
    political Uma entidade política. Normalmente, esse tipo indica um polígono de administração civil.
    country A entidade política nacional, normalmente o tipo de ordem mais alta retornado pelo geocodificador.
    administrative_area_level_1 Uma entidade civil de primeira ordem, abaixo do nível de país. Nos Estados Unidos, esses níveis administrativos são estados. Nem todos os países incluem esses níveis administrativos. Na maioria dos casos, os nomes curtos de administrative_area_level_1 são muito parecidos com as subdivisões da ISO 3166-2 e outras listas amplamente divulgadas. No entanto, 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 Uma entidade civil de segunda ordem, abaixo do nível de 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 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 Uma entidade civil de quarta 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_5 Uma entidade civil de quinta 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_6 Uma entidade civil de sexta 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_7 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 Um nome alternativo usado com frequência para a entidade.
    locality Uma entidade política incorporada de cidade ou município.
    sublocality Uma entidade civil de primeira ordem, abaixo de uma região administrativa. 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 Um bairro com nome.
    premise Um local nomeado, geralmente um edifício ou um conjunto de edifícios com um nome comum.
    subpremise Uma entidade endereçável abaixo do nível da instalação, como um apartamento, uma unidade ou uma suíte.
    plus_code 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. Consulte https://plus.codes para mais detalhes.
    postal_code Um código postal usado para endereçar correspondências no país.
    natural_feature Um recurso natural de destaque.
    airport Um aeroporto.
    park Um parque nomeado.
    point_of_interest 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".

    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).

  • location_type: um filtro de um ou mais tipos de local, separados por um pipe (|). Se o parâmetro tiver vários tipos de local, a API vai retornar todos os endereços que corresponderem a qualquer um deles. 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 do latlng especificado e descarta aqueles que não correspondem aos tipos de local especificados. Os valores a seguir são compatíveis:
    • "ROOFTOP" retorna apenas os endereços para os quais o Google tem informações de localização precisas até o nível do endereço da rua.
    • "RANGE_INTERPOLATED" retorna apenas os endereços que refletem uma aproximação (normalmente em uma estrada) interpolada entre dois pontos precisos (como interseções). Um intervalo interpolado geralmente indica que os códigos geográficos de rooftop não estão disponíveis para um endereço.
    • "GEOMETRIC_CENTER" retorna apenas centros geométricos de um local, 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.
  • extra_computations: use esse parâmetro para especificar os seguintes recursos adicionais na resposta: Para ativar vários desses recursos para a mesma solicitação de API, inclua o parâmetro extra_computations na solicitação para cada recurso, por exemplo: 
    extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES

Se os filtros result_type e location_type estiverem presentes, a API vai retornar apenas os resultados que correspondem aos valores result_type e location_type. Se nenhum dos valores do filtro for aceitável, a API vai 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 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 na cidade de Chicago, ele pode ser indicado como um endereço, como a cidade (Chicago), o estado (Illinois) ou o país (Estados Unidos). Todos são "endereços" para o geocodificador. O geocodificador reverso retorna qualquer um desses tipos como resultados válidos.

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

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

{
   "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 endereço mais específico até entidades políticas menos específicas, como bairros, cidades, municípios e estados. O endereço mais exato geralmente é o resultado mais proeminente, como neste caso. Se você quiser corresponder a um tipo específico de endereço, consulte a seção abaixo sobre como restringir os resultados por tipo. Por isso, a localização dos resultados em relação uns aos outros 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 de ROOFTOP e um 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:esses filtros são válidos apenas para a geocodificação reversa.

Respostas de geocodificação reversa

O formato da resposta de geocodificação reversa é o mesmo 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 da 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 o motivo da falha da geocodificação reversa. O campo "status" pode conter os seguintes valores:

  • "OK" indica que nenhum erro ocorreu e pelo menos um endereço foi retornado.
  • "ZERO_RESULTS" indica que a geocodificação reversa 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 sua cota.
  • "REQUEST_DENIED" indica que a solicitação foi negada. Talvez porque a solicitação inclua um parâmetro result_type ou location_type, mas não uma chave de API.
  • "INVALID_REQUEST" geralmente indica uma das seguintes situações:
    • A consulta (address, components ou latlng) está ausente.
    • Um 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. Se você tentar novamente, a solicitação pode dar certo.

Geocodificação inversa de Plus Codes

O campo plus_code na resposta de geocodificação contém um plus code que se aproxima mais da latitude e longitude da consulta. Além disso, na maioria dos casos, a matriz de resultados JSON contém um resultado de geocodificação completo com um tipo plus_code e um endereço contendo um código de adição. A distância entre o código Plus decodificado e o ponto de solicitação é garantida como menor que 10 metros.