Geocodificar um endereço

A geocodificação converte um endereço em um local no 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 geocódigo

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 representado 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 da API e a máscara de campo, em cabeçalhos como parte da solicitação GET.

Observação: os URLs precisam ser codificados corretamente para serem válidos e são limitados a 4.096 caracteres para todos os serviços da Web. Considere esse limite ao criar seus URLs. Diferentes navegadores, proxies e servidores podem ter limites de caracteres de URL diferentes.

Transmitir uma string de endereço não estruturada

Um endereço não estruturado é um endereço formatado como uma string ou um Plus Code. Por exemplo, o exemplo a seguir transmite a string de endereço codificada em 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 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, um / como em "7/1 King St, Concord West". O URL codifica o "/" como %2F:

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

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

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

No próximo exemplo, você especifica uma string de endereço não estruturado como o Plus Code 849VCWC8+R4. Codifique 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 do endereço na solicitação como parâmetros de consulta individuais.

Por exemplo, para especificar apenas o CEP do endereço que você usa, 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 oferece suporte ao OAuth 2.0 para autenticação. Para usar o OAuth com a API Geocoding, o token OAuth precisa ser atribuído ao escopo correto. A API Geocoding oferece suporte aos seguintes escopos para uso com a 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 apenas com GeocodeAddress para geocodificação direta.

Além disso, você pode usar o escopo https://www.googleapis.com/auth/cloud-platform geral 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 acesso a todos os endpoints.

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

Resposta de geocódigo

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

Observação: geralmente, apenas uma entrada na matriz results é retornada para pesquisas de endereço, embora o geocodificador possa retornar vários resultados quando as consultas de endereço são ambíguas.

O objeto JSON completo está no 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. Outros elementos de endereço, como nomes de empresas e números de unidade, suíte ou andar, devem ser evitados. Os elementos de endereço precisam ser delimitados por espaços e codificados em URL para %20. Por exemplo, transmita o endereço "24 Sussex Drive Ottawa ON" como:

  24%20Sussex%20Drive%20Ottawa%20ON

  Formate os códigos Plus conforme mostrado abaixo. Os sinais de adição são codificados em URL para %2B e os espaços são codificados em URL para %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, USA" como CWC8%2BR9%20Mountain%20View%20CA%20USA.

Parâmetros opcionais

• locationBias

  Especifica uma área para pesquisar como um Viewport. Esse local serve como uma polarização, o que significa que os resultados em torno do local especificado podem ser retornados, incluindo resultados próximos, mas fora da área.

  Observação : o parâmetro locationBias pode ser substituído se o endereço solicitado contiver um local explícito, como Barcelona, Spain. Nesse caso, locationBias é ignorado.

  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 baixos e altos diagonalmente opostos. O ponto mais baixo marca o canto sudoeste do retângulo, e o ponto mais alto representa o canto nordeste do retângulo.

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

  • Se low = high, a viewport consiste nesse único ponto.
  • Se low.longitude for maior que 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 viewport inclui todas as longitudes.
  • Se low.longitude = 180 graus e high.longitude = -180 graus, o intervalo de longitude estará vazio.
  • Se low.latitude for maior que high.latitude, o intervalo de latitude vai estar vazio.

  Os valores mínimo e máximo precisam ser preenchidos, e a caixa representada não pode estar vazia. Uma viewport vazia resulta em um erro.

  Por exemplo, esta string de consulta define uma viewport que inclui toda 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 aceitos. O Google atualiza com frequência os idiomas compatíveis, 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 que seja legível para o usuário e para os moradores. Para isso, ele retorna endereços no idioma local, transliterados para uma escrita 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 do 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 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 abreviações de tipos de ruas 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, 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.

Viés de local

Use o parâmetro locationBias para instruir o serviço de geocodificação 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.

Observação:esse parâmetro adiciona apenas uma tendência para os resultados dentro da viewport, mas não garante que os resultados estejam contidos nela. O artigo de práticas recomendadas de geocodificação oferece algumas orientações sobre qual endpoint de API se adapta melhor a cada caso de uso.

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 em torno da parte nordeste dos EUA faz com que esse geocódigo retorne 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 de geocodificação a retornar resultados tendenciosos para 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 inclinação da região. A maioria dos códigos 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 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) só retorna resultados da Espanha:

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