O termo geocodificação geralmente se refere à tradução de uma linguagem endereço em um local em um mapa. O processo oposto, traduzir um local no mapa em um endereço legível é conhecido como geocodificação inversa.
Solicitações de geocodificação inversa
Parâmetros obrigatórios
latlng
: latitude e longitude coordenadas especificando o local de onde deseja que o lugar mais próximo, legível por humanos.key
: a chave de API do aplicativo. Essa chave identifica o aplicativo para fins de gerenciamento de cotas. Saiba como conseguir uma chave.
Parâmetros opcionais
Estes são os parâmetros opcionais que você pode incluir em um solicitação de geocodificação:
language
: o idioma em que os resultados serão retornados.- Consulte a lista de serviços idiomas. O Google atualiza os idiomas com suporte com frequência. Por isso, pode não estar completa.
- Se
language
não for fornecido, o geocodificador tentará usar o idioma preferencial conforme especificado no cabeçalhoAccept-Language
ou o idioma nativo do domínio de onde a solicitação foi enviada. - O geocodificador faz o possível para fornecer um endereço que seja legível tanto para o usuário quanto para os locais. Para atingir esse objetivo, retorna endereços no idioma local, transliterado para um um script legível para o usuário, se necessário, observando o idioma de destino. Todos os outros endereços são retornados no campo idioma de destino. 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, o geocodificador usará a correspondência mais próxima.
region
: o código de região especificado como um valor de ccTLD ("domínio de nível superior") de dois caracteres. O parâmetro também pode afetar resultados com base na legislação aplicável.result_type
: um filtro de um ou mais tipos de endereço. separadas por uma barra vertical (|
). Se o parâmetro tiver várias tipos de endereço, a API retorna todos os endereços que correspondem a qualquer um dos tipos. Uma observação sobre o processamento: o parâmetroresult_type
não restringir a pesquisa aos tipos de endereço especificados. Em vez disso, aresult_type
atua como um filtro pós-pesquisa: a API busca todos resultados para olatlng
especificado e, em seguida, descarta esses resultados que não correspondam aos tipos de endereço especificados. Os valores a seguir são suportado:street_address
indica um endereço preciso.route
indica uma rota nomeada (como "US 101").intersection
indica uma interseção principal, normalmente de duas estradas principais.political
indica uma entidade política. Normalmente, esse tipo indica um polígono de administração civil.country
indica a entidade política nacional e costuma ser o tipo de ordem mais elevada retornado pelo geocodificador.administrative_area_level_1
indica uma entidade civil de primeira ordem abaixo do nível do país. Nos Estados Unidos, esses níveis administrativos são os estados. Nem todos os países têm esses níveis administrativos. Na maioria dos casos, nomes curtos para administrative_area_level_1 vão respeitar quase que totalmente as subdivisões da ISO 3166-2 e outras normas amplamente divulgadas. Porém, isso não é garantido, já que os resultados da nossa geocodificação se baseiam em vários sinais e dados de localização.administrative_area_level_2
indica uma entidade civil de segunda ordem abaixo do nível de país. Nos Estados Unidos, esses níveis administrativos são os condados. Nem todos os países têm esses níveis administrativos.administrative_area_level_3
indica uma entidade civil de terceira ordem abaixo do nível de país. Esse tipo indica uma divisão civil secundária. Nem todos os países incluem esses níveis administrativos.administrative_area_level_4
indica uma entidade civil de quarta ordem abaixo do nível do país. Esse tipo indica uma divisão civil secundária. Nem todos os países incluem esses níveis administrativos.administrative_area_level_5
indica uma entidade civil de quinta ordem abaixo do nível do país. Esse tipo indica uma divisão civil secundária. Nem todos os países incluem esses níveis administrativos.administrative_area_level_6
indica uma entidade civil de sexta ordem abaixo do nível do país. Esse tipo indica uma divisão civil secundária. Nem todos os países incluem esses níveis administrativos.administrative_area_level_7
indica uma entidade civil de sétima ordem abaixo do nível de país. Esse tipo indica uma divisão civil secundária. Nem todos os países incluem esses níveis administrativos.colloquial_area
indica um nome alternativo usado comumente para a entidade.locality
indica uma entidade política de cidade ou município incorporada.sublocality
indica uma entidade civil de primeira ordem abaixo da localidade. Para alguns locais, é possível receber um dos tipos adicionais:sublocality_level_1
atésublocality_level_5
. Cada nível de sublocalidade é uma entidade civil. Números maiores indicam uma área geográfica menor.neighborhood
indica um bairro nomeadopremise
indica um local nomeado, normalmente um edifício ou condomínios com um nome comumsubpremise
indica uma entidade de primeira ordem abaixo de uma localização com nome, geralmente um prédio dentro de um conjunto que prédios com um nome em comumplus_code
indica uma referência de local codificada, derivada de latitude e longitude. Os Plus Codes podem ser usados em vez de endereços nos lugares em que não existem, ou seja, quando os imóveis não estão numerados ou as ruas não têm nome. Para mais detalhes, consulte https://plus.codes.postal_code
indica um código postal, conforme usado para endereçar correspondências no país.natural_feature
indica um recurso natural de destaque.airport
indica um aeroporto.park
indica um parque nomeado.point_of_interest
indica um ponto de interesse nomeado. Normalmente, esses "PDIs" são entidades locais de destaque que não se encaixam facilmente em outra categoria, como "Empire State Building" ou "Torre Eiffel".
location_type
: um filtro de um ou mais tipos de local, separados por uma barra vertical (|
). Se o parâmetro tiver vários tipos de local, a API vai retornar todos os endereços que corresponderem a qualquer um deles. Observação sobre o processamento: o parâmetrolocation_type
não restringe a pesquisa aos tipos de local especificados. Em vez disso, alocation_type
atua como um filtro pós-pesquisa: a API busca todos resultados para olatlng
especificado e, em seguida, descarta esses resultados que não correspondem aos tipos de local especificados. Os seguintes valores são aceitos:"ROOFTOP"
retorna apenas os endereços para os quais o Google tem informações de localização que incluem o endereço."RANGE_INTERPOLATED"
retorna apenas os endereços que refletem uma aproximação (normalmente em uma estrada) interpolada entre dois pontos precisos (como interseções). Um intervalo interpolado geralmente indica que geocódigos de telhado não estão disponíveis para um endereço."GEOMETRIC_CENTER"
retorna apenas dados geométricos centros de um local, como uma polilinha (por exemplo, uma rua) ou polígono (região)."APPROXIMATE"
retorna apenas os endereços que são caracterizada como aproximada.
extra_computations
: use esse parâmetro para especificar o os seguintes recursos adicionais na resposta:ADDRESS_DESCRIPTORS
— Confira descritores de endereço para mais detalhes.BUILDING_AND_ENTRANCES
— Confira entradas e contornos de edifícios para mais detalhes.
extra_computations
na solicitação para cada recurso, Por exemplo:extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
Se os filtros result_type
e location_type
estiverem presentes, a API
retorna apenas os resultados que correspondem a result_type
e ao
location_type
. Se nenhum dos valores do filtro for aceitável, a
API vai retornar ZERO_RESULTS
.
Exemplo de geocodificação inversa
A consulta a seguir contém um valor de latitude/longitude para uma localização no Brooklyn:
https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY
A consulta acima retorna o seguinte resultado:
{
"results" : [
{
"address_components" : [
{
"long_name" : "277",
"short_name" : "277",
"types" : [ "street_number" ]
},
{
"long_name" : "Bedford Avenue",
"short_name" : "Bedford Ave",
"types" : [ "route" ]
},
{
"long_name" : "Williamsburg",
"short_name" : "Williamsburg",
"types" : [ "neighborhood", "political" ]
},
{
"long_name" : "Brooklyn",
"short_name" : "Brooklyn",
"types" : [ "sublocality", "political" ]
},
{
"long_name" : "Kings",
"short_name" : "Kings",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "New York",
"short_name" : "NY",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
},
{
"long_name" : "11211",
"short_name" : "11211",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
"geometry" : {
"location" : {
"lat" : 40.714232,
"lng" : -73.9612889
},
"location_type" : "ROOFTOP",
"viewport" : {
"northeast" : {
"lat" : 40.7155809802915,
"lng" : -73.9599399197085
},
"southwest" : {
"lat" : 40.7128830197085,
"lng" : -73.96263788029151
}
}
},
"place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
"types" : [ "street_address" ]
},
... Additional <code>results[]</code> ...
Observe que o geocodificador inverso retornou mais de um resultado. O
Os resultados de "formatted_address"
não são apenas endereços postais,
qualquer forma de nomear geograficamente uma localização. Por exemplo, ao geocodificar um ponto na cidade de Chicago, o ponto geocodificado pode ser denotado como um endereço, como a cidade (Chicago), como o estado (Illinois) ou como o país (Estados Unidos). Todos são "endereços" para o geocodificador. O geocodificador inverso retorna
qualquer um desses tipos como resultados válidos.
Ele pode corresponder a entidades políticas (países, províncias, cidades e bairros), endereços e códigos postais.
A lista completa de valores de formatted_address
retornados pela consulta anterior é mostrada abaixo.
{
"plus_code" : {
"compound_code" : "P27Q+MCM New York, NY, USA",
"global_code" : "87G8P27Q+MCM"
},
"results" : [
{
"formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
...
"types" : [ "street_address" ]
},
{
"formatted_address" : "279 Bedford Ave, Brooklyn, NY 11211, USA",
...
"types" : [ "premise" ]
},
{
"formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
...
"types" : [ "establishment", "point_of_interest" ]
},
{
"formatted_address" : "291-275 Bedford Ave, Brooklyn, NY 11211, USA",
...
"types" : [ "route" ]
},
{
"formatted_address" : "P27Q+MC New York, NY, USA",
...
"types" : [ "plus_code" ]
},
{
"formatted_address" : "South Williamsburg, Brooklyn, NY, USA",
...
"types" : [ "neighborhood", "political" ]
},
{
"formatted_address" : "Brooklyn, NY 11211, USA",
...
"types" : [ "postal_code" ]
},
{
"formatted_address" : "Williamsburg, Brooklyn, NY, USA",
...
"types" : [ "neighborhood", "political" ]
},
{
"formatted_address" : "Kings County, Brooklyn, NY, USA",
...
"types" : [ "administrative_area_level_2", "political" ]
},
{
"formatted_address" : "Brooklyn, NY, USA",
...
"types" : [ "political", "sublocality", "sublocality_level_1" ]
},
{
"formatted_address" : "New York, NY, USA",
...
"types" : [ "locality", "political" ]
},
{
"formatted_address" : "New York, USA",
...
"types" : [ "administrative_area_level_1", "political" ]
},
{
"formatted_address" : "United States",
...
"types" : [ "country", "political" ]
}
],
"status" : "OK"
}
Essa API retorna diferentes tipos de endereços, do mais específico endereço para entidades políticas menos específicas, como bairros, cidades, condados e estados. O endereço mais exato geralmente é o resultado mais proeminente, como neste caso. Se você quiser corresponder a um tipo específico de da rede, consulte a seção abaixo sobre como restringir resultados por tipo. Por isso, a localização dos resultados em relação podem variar.
Geocodificação inversa filtrada por tipo
O exemplo a seguir filtra os endereços retornados para incluir apenas os
com o tipo de local ROOFTOP
e o tipo de endereço de
street_address
.
https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452
&location_type=ROOFTOP&result_type=street_address&key=YOUR_API_KEY
Observação: esses filtros são válidos somente para geocodificação inversa.
Respostas de geocodificação inversa
O formato da resposta da geocodificação inversa é o mesmo da geocodificação resposta. Consulte Respostas do Geocoding. Veja abaixo os códigos de status possíveis em uma resposta de geocodificação inversa.
Códigos de status da geocodificação inversa
O campo "status"
no objeto de resposta da geocodificação contém
o status da solicitação e pode conter informações de depuração para ajudá-lo
descobrir por que a geocodificação reversa não está funcionando. O campo "status"
pode conter os seguintes valores:
"OK"
indica que não houve erros e que pelo menos um endereço foi retornado."ZERO_RESULTS"
indica que a geocodificação inversa foi deu certo, mas não retornou resultados. Isso pode ocorrer se o geocodificador foi transmitiu umlatlng
em um local remoto."OVER_QUERY_LIMIT"
indica que você ultrapassou a cota de ingestão de registros."REQUEST_DENIED"
indica que a solicitação foi negada. Isso pode ocorrer devido a solicitação incluir um parâmetroresult_type
oulocation_type
, mas não uma chave de API."INVALID_REQUEST"
geralmente indica uma das seguintes opções:- A consulta (
address
,components
oulatlng
). - Um
result_type
oulocation_type
inválido era dado.
- A consulta (
"UNKNOWN_ERROR"
indica que a solicitação não foi processada devido a um erro de servidor. Se você tentar novamente, a solicitação pode dar certo.
Geocodificação inversa de Plus Codes
O campo plus_code
na resposta da geocodificação contém um Plus Code que
faz uma aproximação da latitude e longitude consultadas.
Além disso, a matriz de resultados JSON, na maioria dos casos, contém um endereço de e-mail
resultado com um tipo plus_code
e um endereço contendo um sinal de adição
o código-fonte é alterado. A distância entre o Plus Code decodificado e o ponto de solicitação é
abaixo de 10 metros.