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/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, 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/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 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 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 métodos 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 métodos.

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.

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

    1. GeocodeResult.types: essa matriz indica o tipo ou os tipos gerais do resultado. Os valores possíveis são extraídos das Tabelas A e B na página "Tipos de lugar (novo)".
    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 Tipos de endereço e de componentes de endereço na página "Tipos de lugar (novo)".

    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.

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

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 disponíveis. 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 vai 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/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 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/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 a serem 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.