A geocodificação converte um endereço em um local em um mapa. Quando você geocodifica um endereço, a resposta contém o seguinte:
- ID de lugar da localização
- Coordenadas de latitude e longitude
- Plus Code
- 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/v4/geocode/address/ADDRESS_STRING
Ou como um conjunto estruturado de componentes de endereço representados por parâmetros de consulta:
https://geocode.googleapis.com/v4/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 é um endereço formatado como uma string ou um Plus Code. A geocodificação de endereços não resolve coordenadas de latitude e longitude ou outras strings não estruturadas que não representam um endereço ou um Plus Code. As solicitações que usam essas strings não são aceitas e podem levar a respostas de erro ou comportamento não especificado. Exemplos de consultas não aceitas incluem o seguinte:
| Tipo de consulta | Exemplo |
|---|---|
| Coordenadas de latitude e longitude. Use a geocodificação inversa. | "37.422131,-122.084801" |
| Muitos conceitos ou restrições, como os nomes de vários lugares, estradas ou cidades em uma única consulta | "Market Street San Francisco San Jose Airport" |
| Elementos de endereço postal não representados no Google Maps |
"C/O John Smith 123 Main Street" "P.O. Box 13 San Francisco" |
| Nomes de empresas, redes ou categorias combinados com locais em que essas entidades não estão disponíveis | "Tesco near Dallas, Texas" |
| Consultas ambíguas com várias interpretações | "Charger drop-off" |
| Nomes históricos que não estão mais em uso | "Middlesex United Kingdom" |
| Elementos ou intents não geoespaciais | "How many boats are in Ventura Harbor?" |
| Nomes não oficiais ou de vaidade |
"The Jenga" "The Helter Skelter" |
Por exemplo, o exemplo a seguir transmite a string de endereço codificada por URL "1600 Amphitheatre Parkway, Mountain View, CA":
https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA?key=API_KEY
Observe que 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/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"
Os endereços podem conter muitos tipos de caracteres especiais. Por exemplo, um "/" como em "7/1 King St, Concord West". Codifique o "/" como %2F:
https://geocode.googleapis.com/v4/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/v4/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/v4/geocode/address/849VCWC8%2BR4?key=API_KEY
Transmitir um endereço estruturado
Especifique um endereço estruturado usando o address parâmetro de consulta, 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/v4/geocode/address?address.postalCode=01062&key=API_KEY
Para especificar vários componentes de endereço, como componentes de endereço capturados em um formulário HTML, use vários parâmetros de consulta:
https://geocode.googleapis.com/v4/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 do OAuth precisa receber o escopo correto. A API Geocoding oferece suporte aos seguintes escopos para uso com geocodificação direta:
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.address: use apenas comGeocodeAddresspara geocodificação direta.
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
A geocodificação retorna um
GeocodeAddressResponse
objeto que contém a matriz results de
GeocodeResult
objetos. Cada objeto GeocodeResult representa um único lugar.
As respostas da API Geocoding incluem types matrizes em dois locais principais no
GeocodeResult:
GeocodeResult.types: essa matriz indica o(s) tipo(s) geral(is) do resultado. Os valores possíveis são extraídos de Tabela A e Tabela B na página Tipos de lugar (novo).GeocodeResult.addressComponents[].types: cada componente de endereço tem umatypesmatriz 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 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 Plus Code que você quer geocodificar. Observação:a geocodificação de endereços não resolve coordenadas de latitude e longitude ou outras strings não estruturadas que não representam um endereço ou um Plus Code. Consulte Transmitir uma string de endereço não estruturada para mais detalhes e exemplos de consultas não aceitas. 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 unidades, conjuntos ou andares precisam ser evitados. Os elementos de endereço de rua precisam ser delimitados por espaços codificados por URL para%20. Por exemplo, transmita o endereço "24 Sussex Drive Ottawa ON" como:24%20Sussex%20Drive%20Ottawa%20ON
%2Be os espaços são codificados por URL para%20:- Um código global é um código de área com quatro caracteres e um código local com seis caracteres ou mais. Por exemplo, codifique "849VCWC8+R9" como
849VCWC8%2BR9. - Um código composto é um código local com seis caracteres ou mais e um
local explícito. Por exemplo, codifique "CWC8+R9 Mountain View, CA, USA"
como
CWC8%2BR9%20Mountain%20View%20CA%20USA.
- Um código global é um código de área com quatro caracteres e um código local com seis caracteres ou mais. Por exemplo, codifique "849VCWC8+R9" como
Parâmetros opcionais
locationBias
Especifica uma área para pesquisar como uma
Viewport. Esse local serve como um viés, o que significa que os resultados em torno do local especificado 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 baixos e altos diagonalmente opostos. O ponto baixo marca o canto sudoeste do retângulo, e o ponto alto representa o canto nordeste do retângulo.
Uma janela de visualização é considerada uma região fechada, o que significa que ela inclui o limite. Os limites de latitude precisam variar entre -90 e 90 graus, inclusive, e os limites de longitude precisam variar entre -180 e 180 graus, inclusive:
- Se
low=high, a janela de visualização consiste 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 ehigh.longitude= 180 graus, a janela de visualização inclui todas as longitudes. - Se
low.longitude= 180 graus ehigh.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 - Se
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
languageCodenão for fornecido, a API vai usarencomo padrão. Se você especificar um código de idioma inválido, a API vai retornar um erroINVALID_ARGUMENT. - A API faz o possível para fornecer um endereço de rua legível para o usuário e os moradores locais. Para atingir esse objetivo, ela retorna endereços de rua no idioma 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 regional como um código CLDR de duas letras valor. 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.
-
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
$fieldsoufields, ou usando o cabeçalho HTTPX-Goog-FieldMask. Por exemplo, a solicitação abaixo vai retornar apenas o campoplaceIDda 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/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA
{ "results": [ { "placeId": "ChIJiSSC8QK6j4AR98Thup8mqTc" } ] }
Consulte Escolher campos a serem retornados para mais detalhes.
Direcionamento 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/v4/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 que define uma caixa delimitadora em torno da parte nordeste dos EUA resulta nesse geocódigo retornando apenas a cidade de Washington, D.C.:
https://geocode.googleapis.com/v4/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
Direcionamento de região
Em uma solicitação de geocodificação, você pode 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
duas letras que especifica o viés 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 para a Espanha:
https://geocode.googleapis.com/v4/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/v4/geocode/address/Toledo?regionCode=es&key=API_KEY