Geocodificar um endereço

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

A geocodificação converte um endereço em um local em um mapa. Quando você geocodifica um endereço, a resposta contém:

  • ID do lugar do local
  • Coordenadas de latitude e longitude do local
  • Plus Code do local
  • Detalhes do endereço expandidos

Solicitação de geocodificação

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

https://geocode.googleapis.com/v4beta/geocode/address/ADDRESS_STRING

Ou como um conjunto estruturado de componentes de endereço representados por parâmetros de consulta:

https://geocode.googleapis.com/v4beta/geocode/address?STRUCTURED_ADDRESS

Normalmente, você usa o formato estruturado ao processar componentes de endereço 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 e a máscara de campo, em cabeçalhos como parte da solicitação GET.

Transmitir uma string de endereço não estruturada

Um endereço não estruturado é formatado como uma string ou um Plus Code. Por exemplo, o seguinte exemplo transmite a string de endereço codificada por URL "1600 Amphitheatre Parkway, Mountain View, CA":

https://geocode.googleapis.com/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA?key=API_KEY

O caractere "+" no URL é convertido em um espaço.

Também é possível fazer a solicitação usando um comando curl:

curl -H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

Os endereços podem conter vários tipos de caracteres especiais. Por exemplo, "/" como em "7/1 King St, Concord West". Faça a codificação do URL "/" como %2F:

https://geocode.googleapis.com/v4beta/geocode/address/7%2F1+King+St,+Concord+West
?key=API_KEY

Outro exemplo comum é o caractere "#", como em "9500 W Bryn Mawr Ave #650, Rosemont". Codifique o "#" como %2FE:

https://geocode.googleapis.com/v4beta/geocode/address/9500+W+Bryn+Mawr+Ave+%23650,+Rosemont?key=API_KEY

No exemplo a seguir, você especifica uma string de endereço não estruturada como o Plus Code 849VCWC8+R4. Verifique se você codificou o caractere "+" como %2B:

https://geocode.googleapis.com/v4beta/geocode/address/849VCWC8%2BR4?key=API_KEY

Transmitir um endereço estruturado

Especifique um endereço estruturado usando o parâmetro de consulta address, do tipo PostalAddress. O objeto PostalAddress permite especificar alguns ou todos os componentes de endereço na solicitação como parâmetros de consulta individuais.

Por exemplo, para especificar apenas o CEP do endereço, use PostalAddress.postalCode:

https://geocode.googleapis.com/v4beta/geocode/address?address.postalCode=01062&key=API_KEY

Para especificar vários componentes de endereço, como os capturados em um formulário HTML, use vários parâmetros de consulta:

https://geocode.googleapis.com/v4beta/geocode/address?address.addressLines=1600+Amphithreater+Pkwy&address.locality=Mountain+View&address.administrativeArea=CA&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 direta:

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

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

A geocodificação retorna um objeto GeocodeAddressResponse que contém a matriz results de objetos GeocodeResult. Cada objeto GeocodeResult representa um único lugar.

O objeto JSON completo tem este formato:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "location": {
        "latitude": 37.422010799999995,
        "longitude": -122.08474779999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.420656719708511,
          "longitude": -122.08547523029148
        },
        "high": {
          "latitude": 37.4233546802915,
          "longitude": -122.0827772697085
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCWC8+R4",
        "compoundCode": "CWC8+R4 Mountain View, CA, USA"
      }
    }
  ]
}

Parâmetros obrigatórios

  • address: o endereço ou o Plus Code que você quer geocodificar. Especifique os endereços de acordo com o formato usado pelo serviço postal nacional do país em questão. Evite outros elementos de endereço, como nomes de empresas e números de unidade, conjunto ou andar. Os elementos de endereço precisam ser delimitados por espaços e ter codificação de URL para %20. Por exemplo, transmita o endereço "24 Sussex Drive Ottawa ON" como: 
    24%20Sussex%20Drive%20Ottawa%20ON
     Formate os Plus Codes conforme mostrado abaixo. Os sinais de adição são codificados para URL como %2B e os espaços, como %20:
    • Um código global é um código de área com quatro caracteres e um código local com, pelo menos, seis caracteres. Por exemplo, codifique "849VCWC8+R9" como 849VCWC8%2BR9.
    • Um código composto é um código local com, pelo menos, seis caracteres e um local explícito. Por exemplo, codifique "CWC8+R9 Mountain View, CA, EUA" como CWC8%2BR9%20Mountain%20View%20CA%20USA.

Parâmetros opcionais

  • locationBias

    Especifica uma área para pesquisar como um Viewport. Essa localização serve como uma polarização, o que significa que resultados ao redor da localização especificada podem ser retornados, incluindo resultados próximos, mas fora da área.

    Especifique a região como uma janela de visualização retangular. Um retângulo é uma janela de visualização de latitude-longitude, representada como dois pontos diagonais opostos, um baixo e um alto. O ponto baixo marca o canto sudoeste do retângulo, e o ponto alto representa o canto nordeste.

    Uma janela de visualização é considerada uma região fechada, ou seja, inclui o limite. Os limites de latitude precisam estar entre -90 e 90 graus, e os de longitude entre -180 e 180 graus:

    • Se low = high, a janela de visualização consistirá nesse único ponto.
    • Se low.longitude > high.longitude, o intervalo de longitude será invertido (a janela de visualização cruza a linha de longitude de 180 graus).
    • Se low.longitude = -180 graus e high.longitude = 180 graus, a janela de visualização vai incluir todas as longitudes.
    • Se low.longitude = 180 graus e high.longitude = -180 graus, o intervalo de longitude estará vazio.
    • Se low.latitude > high.latitude, o intervalo de latitude estará vazio.

    Os valores baixo e alto precisam ser preenchidos, e a caixa representada não pode estar vazia. Uma janela de visualização vazia resulta em um erro.

    Por exemplo, esta string de consulta define uma janela de visualização que envolve totalmente a cidade de Nova York:

    ?locationBias.rectangle.low.latitude=40.477398&locationBias.rectangle.low.longitude=-74.259087&locationBias.rectangle.high.latitude=40.91618&locationBias.rectangle.high.longitude=-73.70018

  • languageCode

    O idioma em que os resultados serão retornados.

    • Consulte a lista de idiomas compatí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 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.

Tendência de local

Use o parâmetro locationBias para instruir o serviço Geocoding a dar preferência a resultados em uma determinada janela de visualização (expressa como uma caixa delimitadora). O parâmetro locationBias define as coordenadas de latitude/longitude dos cantos sudoeste e nordeste dessa caixa delimitadora.

Por exemplo, uma solicitação de geocodificação para o endereço "Washington" pode retornar resultados para Washington, D.C. e para o estado de Washington, nos EUA:

https://geocode.googleapis.com/v4beta/geocode/address/Washington?key=API_KEY

A resposta está no formato:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "placeId": "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "location": {
        "latitude": 38.9071923,
        "longitude": -77.0368707
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "bounds": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "formattedAddress": "Washington, DC, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "Washington",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "placeId": "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "location": {
        "latitude": 47.7510741,
        "longitude": -120.7401386
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024945,
          "longitude": -116.91607109999998
        }
      },
      "bounds": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024442,
          "longitude": -116.91607109999998
        }
      },
      "formattedAddress": "Washington, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "WA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
      ...
      ],
      "types": [
        "administrative_area_level_1",
        "political"
      ]
    }
  ]
}

No entanto, a adição de um parâmetro locationBias definindo uma caixa delimitadora ao redor da parte nordeste dos EUA resulta neste geocódigo retornando apenas a cidade de Washington, D.C.:

https://geocode.googleapis.com/v4beta/geocode/address/Washington?locationBias.rectangle.low.latitude=36.47&locationBias.rectangle.low.longitude=-84.72&locationBias.rectangle.high.latitude=43.39&locationBias.rectangle.high.longitude=-65.90&key=API_KEY

Polarização de região

Em uma solicitação de geocodificação, é possível instruir o serviço Geocoding a retornar resultados direcionados a uma região específica usando o parâmetro regionCode. Esse parâmetro usa um valor de código CLDR de dois caracteres que especifica a tendência regional. A maioria dos códigos do CLDR é idêntica aos códigos ISO 3166-1.

Não há valor padrão para regionCode. Por exemplo, um geocódigo para "Toledo" retorna resultados para os EUA e para a Espanha:

https://geocode.googleapis.com/v4beta/geocode/address/Toledo?key=API_KEY

Resposta:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "placeId": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "location": {
        "latitude": 41.652805199999996,
        "longitude": -83.5378674
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "bounds": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "formattedAddress": "Toledo, OH, USA",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJkwyrlqwLag0RiQIn2fdIshM",
      "placeId": "ChIJkwyrlqwLag0RiQIn2fdIshM",
      "location": {
        "latitude": 39.8628296,
        "longitude": -4.0273067
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "bounds": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "formattedAddress": "Toledo, España",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "administrative_area_level_4",
            "political"
          ],
          "languageCode": "es"
        },
        ...
      ],
      "types": [
        "administrative_area_level_4",
        "political"
      ]
    },
    ...
  ]
}

Uma solicitação de geocodificação para "Toledo" com regionCode=es (Espanha) retorna apenas resultados da Espanha:

https://geocode.googleapis.com/v4beta/geocode/address/Toledo?regionCode=es&key=API_KEY