Geocodificar um local de forma inversa

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

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

Quando você faz a geocodificação inversa de um local, a resposta contém:

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 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 inversa é uma solicitação HTTP GET. É possível especificar o local como uma string não estruturada:

https://geocode.googleapis.com/v4/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/v4/geocode/location?location.latitude=LATITUDE&location.longitude=LONGITUDE

Normalmente, o formato estruturado é usado 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 de coordenadas de latitude e longitude separadas por vírgulas:

https://geocode.googleapis.com/v4/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/v4/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/v4/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 a geocodificação inversa:

  • https://www.googleapis.com/auth/maps-platform.geocode: use com todos os métodos da API Geocoding.
  • https://www.googleapis.com/auth/maps-platform.geocode.location: use apenas 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 métodos da API Geocoding. Esse escopo é útil durante o desenvolvimento, mas não na produção, porque é um escopo geral que permite acesso a todos os métodos.

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

Resposta de geocodificação inversa

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

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

    As respostas da API Geocoding incluem matrizes types em dois lugares principais no GeocodeResult:

    1. GeocodeResult.types: essa matriz indica os tipos gerais do resultado. Os valores possíveis são extraídos dos tipos de lugar usados pela API Places. Para mais informações, consulte as tabelas A e B de tipos de lugar.
    2. GeocodeResult.addressComponents[].types: cada componente de endereço tem uma matriz types que indica o tipo dessa parte específica do endereço. Esses valores são extraídos da tabela de tipos de endereço e de componentes de endereço usada pela API Places.

    O geocodificador reverso 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 indicado 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 reverso 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 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.

    Observação: a API nem sempre retorna Plus Codes.

O objeto JSON completo está no 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 por humanos mais próximo.

Parâmetros opcionais

  • languageCode

    O idioma em que os resultados serão retornados.

    • Consulte a lista de idiomas compatíveis. O Google atualiza os idiomas compatíveis com frequência. Por isso, essa lista pode não estar completa.
    • Se languageCode não for fornecido, a API usará como padrão o idioma e o script locais do local. 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 que seja legível para o usuário e os moradores locais. Para isso, ele retorna endereços no idioma local, transliterados para um script legível pelo usuário, se necessário, de acordo com o idioma preferido. Todos os outros endereços são retornados no idioma preferencial. Os componentes de endereço são todos retornados no mesmo idioma, que é escolhido no primeiro componente.
    • Se um nome não estiver disponível no idioma preferido, a API vai usar a correspondência mais próxima.
    • O idioma preferencial 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 da região como um valor de 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 para a região especificada. Ao geocodificar um local ou um lugar, fazer uma geocodificação inversa ou uma 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, granularity funciona como um filtro pós-pesquisa. A API busca todos os resultados para o location especificado e descarta os que não correspondem às granularidades de local especificadas.

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

    https://geocode.googleapis.com/v4/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. Os valores possíveis são extraídos da tabela Tipos de endereço e de componentes de endereço na página Tipos de lugar (novo). Se você especificar vários parâmetros types, a API vai retornar todos os endereços que correspondem a qualquer um dos tipos.

    O parâmetro types não restringe a pesquisa aos tipos de endereço especificados. Em vez disso, types funciona como um filtro pós-pesquisa. A API busca todos os resultados para o 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 corresponderem a ambos. Exemplo:

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

  • FieldMask

    Crie uma máscara de campo de resposta para especificar os campos que serão retornados na resposta. Transmita a máscara de campo de resposta ao método usando o parâmetro de URL $fields ou fields ou o cabeçalho HTTP X-Goog-FieldMask. Por exemplo, a solicitação abaixo vai retornar apenas os campos placeID da resposta.

    curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: results.placeId' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"
    A resposta é: 
    {
  "results": [
    {
      "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE"
    },
    {
      "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g"
    },
    {
      "placeId": "ChIJ1yjFJ1-7j4ARG_RVqFD1h7k"
    },
    {
      "placeId": "ChIJ09H2YwK6j4ARoF7qfCBxhB8"
    },
    ...
  ]
}

    Consulte Escolher campos para retornar para mais detalhes.