Geocodificar um local de forma inversa

Desenvolvedores da Área Econômica Europeia (AEE)

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

Ao fazer 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. Geralmente, o endereço mais exato é o primeiro resultado. Se você quiser encontrar um tipo específico de endereço, use o types parâmetro.

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, 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. Por exemplo:

Transmitir uma string de local não estruturada

Um local não estruturado é um local 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 location parâmetro de consulta, 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 oferece suporte ao OAuth 2.0 para autenticação. Para usar o OAuth com a API Geocoding, o token do OAuth precisa ter o escopo correto atribuído. A API Geocoding oferece suporte aos 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 apenas com GeocodeLocation para geocodificação inversa.

Além disso, você pode 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 inversa retorna um GeocodeLocationResponse objeto que contém:

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

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

    1. GeocodeResult.types: essa matriz indica o(s) tipo(s) geral(is) 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 types matriz 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 usada pela API Places.

    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 longitude na solicitação. Além disso, cada elemento da results matriz contém um Plus Code. A distância entre o Plus Code decodificado e o ponto de solicitação é inferior a 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 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, então essa lista pode não ser exaustiva.
    • 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 para os moradores locais. Para atingir esse objetivo, ela retorna endereços na língua local, 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. 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 vai 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 da região como um valor de código CLDR de duas letras. 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, granularity funciona como um filtro pós-pesquisa. A API busca todos os resultados do location especificado e descarta aqueles resultados que não correspondem às granularidades de local especificadas.

    Se você especificar types e granularity, então 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 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 do local especificado e descarta aqueles resultados que não correspondem aos tipos de endereço especificados.

    Se você especificar types e granularity, então 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 para o método usando o parâmetro de URL $fields ou fields, ou usando 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 a serem retornados para mais detalhes.