Geocodificar um local de forma inversa

Desenvolvedores do Espaço Econômico Europeu (EEE)

A geocodificação inversa traduz uma localização no mapa em um endereço legível. Você representa o local no mapa pelas coordenadas de latitude e longitude.

Ao fazer uma geocodificação reversa de um local, a resposta contém:

Essa API retorna diferentes tipos de endereços, desde o endereço de rua mais específico até entidades políticas menos específicas, como bairros, cidades, municípios e estados. O endereço mais exato geralmente é o primeiro resultado. Se você quiser corresponder a um tipo específico de endereço, use o parâmetro types.

Solicitação de geocodificação inversa

Uma solicitação de geocodificação reversa é uma solicitação HTTP GET. É possível especificar o local como uma string não estruturada:

https://geocode.googleapis.com/v4beta/geocode/location/LATITUDE,LONGITUDE

Ou como um conjunto estruturado de coordenadas de latitude e longitude representadas por parâmetros de consulta:

https://geocode.googleapis.com/v4beta/geocode/location?location.latitude=LATITUDE&location.longitude=LONGITUDE

Normalmente, você usa o formato estruturado ao processar componentes de local capturados em um formulário HTML.

Transmita todos os outros parâmetros como parâmetros de URL ou, para parâmetros como a chave de API ou a máscara de campo, em cabeçalhos como parte da solicitação GET. Exemplo:

Transmitir uma string de local não estruturada

Um local não estruturado é formatado como uma string separada por vírgulas de coordenadas de latitude e longitude:

https://geocode.googleapis.com/v4beta/geocode/location/37.4225508,-122.0846338?key=API_KEY

Ou em um comando curl:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4beta/geocode/location/37.4225508,-122.0846338"

Transmitir um local estruturado

Especifique o local estruturado usando o parâmetro de consulta location, do tipo LatLng. O objeto LatLng permite especificar a latitude e a longitude como parâmetros de consulta separados:

https://geocode.googleapis.com/v4beta/geocode/location?location.latitude=37.4225508&location.longitude=-122.0846338&key=API_KEY

Usar o OAuth para fazer uma solicitação

A API Geocoding v4 é compatível com o OAuth 2.0 para autenticação. Para usar o OAuth com a API Geocoding, o token OAuth precisa receber o escopo correto. A API Geocoding é compatível com os seguintes escopos para uso com geocodificação inversa:

  • https://www.googleapis.com/auth/maps-platform.geocode — Use com todos os endpoints da API Geocoding.
  • https://www.googleapis.com/auth/maps-platform.geocode.location — Use somente com GeocodeLocation para geocodificação inversa.

Além disso, é possível usar o escopo geral https://www.googleapis.com/auth/cloud-platform para todos os endpoints da API Geocoding. Esse escopo é útil durante o desenvolvimento, mas não na produção, porque é um escopo geral que permite o acesso a todos os endpoints.

Para mais informações e exemplos, consulte Usar o OAuth.

Resposta de geocodificação inversa

A geocodificação reversa retorna um objeto GeocodeLocationResponse que contém:

  • A matriz results de objetos GeocodeResult que representa o lugar.

    O geocodificador inverso retorna mais de um resultado na matriz results. Os resultados não são apenas endereços postais, mas qualquer forma de nomear uma localização geograficamente. Por exemplo, ao geocodificar um ponto da cidade de Chicago, ele pode ser rotulado como um endereço, como a cidade (Chicago), o estado (Illinois) ou 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.

  • O campo plusCode, do tipo PlusCode, contém o plus code que melhor se aproxima da latitude e da longitude na solicitação. Além disso, cada elemento da matriz results contém um Plus Code. A distância entre o Plus Code decodificado e o ponto de solicitação é menor que 10 metros.

O objeto JSON completo tem este formato:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "placeId": "ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "location": {
        "latitude": 37.422588300000008,
        "longitude": -122.0846489
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.421239319708512,
          "longitude": -122.0859978802915
        },
        "high": {
          "latitude": 37.423937280291511,
          "longitude": -122.08329991970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        }
      ],
      "types": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCW83+PM",
        "compoundCode": "CW83+PM Mountain View, CA, USA"
      }
    },
    {
      "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "location": {
        "latitude": 37.4220541,
        "longitude": -122.08532419999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.4207051197085,
          "longitude": -122.08667318029148
        },
        "high": {
          "latitude": 37.423403080291493,
          "longitude": -122.08397521970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        }
      ],
      "types": [
        "establishment",
        "point_of_interest"
      ],
      "plusCode": {
        "globalCode": "849VCWC7+RV",
        "compoundCode": "CWC7+RV Mountain View, CA, USA"
      }
    },
   ...
  ],
  "plusCode": {
    "globalCode": "849VCWF8+24H",
    "compoundCode": "CWF8+24H Mountain View, CA, USA"
  }
}

Parâmetros obrigatórios

  • local

    As coordenadas de latitude e longitude que especificam onde você quer o endereço legível mais próximo.

Parâmetros opcionais

  • languageCode

    O idioma em que os resultados serão retornados.

    • Consulte a lista de idiomas aceitos. O Google atualiza os idiomas com frequência, então esta lista pode não estar completa.
    • Se languageCode não for fornecido, a API usará en como padrão. Se você especificar um código de idioma inválido, a API vai retornar um erro INVALID_ARGUMENT.
    • A API faz o possível para fornecer um endereço legível para o usuário e os moradores locais. Para isso, ele retorna endereços em português, transliterados 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 preferido. Todos os componentes de endereço são retornados no mesmo idioma, que é escolhido no primeiro componente.
    • Se um nome não estiver disponível no idioma preferido, a API usará a correspondência mais próxima.
    • O idioma preferido tem uma pequena influência no conjunto de resultados que a API escolhe retornar e na ordem em que eles são retornados. O geocodificador interpreta abreviações de maneira diferente dependendo do idioma, como as abreviações de tipos de rua ou sinônimos que podem ser válidos em um idioma, mas não em outro.

  • regionCode

    O código regional como um valor código CLDR de dois caracteres. Não há valor padrão. A maioria dos códigos CLDR é idêntica aos códigos ISO 3166-1.

    Ao geocodificar um endereço, geocodificação direta, esse parâmetro pode influenciar, mas não restringir totalmente, os resultados do serviço à região especificada. Ao geocodificar um local ou um lugar, geocodificação inversa ou geocodificação de lugar, esse parâmetro pode ser usado para formatar o endereço. Em todos os casos, esse parâmetro pode afetar os resultados com base na legislação aplicável.

  • granularidade

    Uma ou mais granularidades de local, especificadas como parâmetros de consulta separados, conforme definido por Granularity. Se você especificar vários parâmetros granularity, a API vai retornar todos os endereços que correspondem a qualquer uma das granularidades.

    O parâmetro granularity não restringe a pesquisa às granularidades de local especificadas. Em vez disso, o granularity funciona como um filtro pós-pesquisa. A API busca todos os resultados do location especificado e descarta aqueles que não correspondem às granularidades de local especificadas.

    Se você especificar types e granularity, a API vai retornar apenas os resultados que correspondem aos dois. Exemplo:

    https://geocode.googleapis.com/v4beta/geocode/location/37.4225508,-122.0846338?granularity=ROOFTOP&granularity=GEOMETRIC_CENTER&key=API_KEY

  • tipos

    Um ou mais tipos de endereço, especificados como parâmetros de consulta separados. Se você especificar vários parâmetros types, a API vai retornar todos os endereços que corresponderem a qualquer um dos tipos.

    O parâmetro types não restringe a pesquisa aos tipos de endereço especificados. Em vez disso, o types funciona como um filtro pós-pesquisa. A API busca todos os resultados do local especificado e descarta aqueles que não correspondem aos tipos de endereço especificados.

    Se você especificar types e granularity, a API vai retornar apenas os resultados que correspondem aos dois. Exemplo:

    https://geocode.googleapis.com/v4beta/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2&types=locality&key=API_KEY

    Os valores a seguir são compatíveis:

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

    A matriz types no corpo GeocodeResult da 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, geralmente de duas vias 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 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 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 comumente 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 do imóvel, 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. Para mais detalhes, consulte https://plus.codes.
    postal_code Um código postal, como 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.