Solicitação
Uma solicitação da API Geocoding tem o seguinte formato:
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
em que outputFormat
pode ser um dos seguintes valores:
json
(recomendado) indica a saída em JSON (JavaScript Object Notation). ouxml
indica a saída em XML.
O HTTPS é obrigatório.
Alguns parâmetros são obrigatórios, enquanto outros são opcionais. Como é padrão em URLs,
são separados usando o caractere "e" comercial (&
).
O restante desta página descreve a geocodificação e geocodificação inversa separadamente, porque parâmetros diferentes estão disponíveis para cada tipo de solicitação.
Parâmetros de geocodificação (pesquisa de latitude/longitude)
Parâmetros obrigatórios para uma solicitação de geocodificação:
address
: o endereço ou Plus Code que você quer geocodificar. Especifique endereços de acordo com o formato usada pelo serviço postal do país em questão. Adicional elementos de endereço, como nomes de empresas e números de unidades, conjuntos ou andares devem ser evitados. Os elementos de endereço devem ser delimitados por espaços (mostrado aqui como escape de URL para%20
):address=24%20Sussex%20Drive%20Ottawa%20ON
Formate os Plus Codes como mostrado aqui (os sinais de adição têm escape de URL para%2B
, e os espaços, para%20
):- O código global é um código de área com quatro e seis caracteres ou mais
código local (849VCWC8+R9 é
849VCWC8%2BR9
). - O código composto é um código local com, pelo menos, seis caracteres
local explícito (CWC8+R9 Mountain View, CA, EUA é
CWC8%2BR9%20Mountain%20View%20CA%20USA
).
--OR--
components
: um filtro de componentes com elementos. separadas por uma barra vertical (|
). O filtro de componentes também é aceito. como um parâmetro opcional se umaddress
for fornecido. Cada elemento do filtro de componentes consiste em umcomponent:value
e restringe totalmente os resultados. do geocodificador. Veja mais informações sobre filtragem de componentes abaixo.- O código global é um código de área com quatro e seis caracteres ou mais
código local (849VCWC8+R9 é
key
: a chave de API do aplicativo. Essa chave identifica o aplicativo para fins de gerenciamento de cotas. Saiba como conseguir uma chave.
Consulte as Perguntas frequentes para orientações adicionais.
Parâmetros opcionais em uma solicitação de geocodificação:
bounds
: a caixa delimitadora da janela de visualização no qual os resultados de geocódigo podem ser direcionados de forma mais proeminente. Esse parâmetro apenas influenciar, não restringir totalmente, os resultados do geocodificador. Para mais informações, consulte Polarização da janela de visualização abaixo.language
: o idioma no qual retornar resultados.- 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á o idioma preferencial conforme especificado na cabeçalhoAccept-Language
ou o idioma nativo da domínio de onde a solicitação é 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.
- O idioma preferido tem uma pequena influência no conjunto de resultados que a API escolhe retornar e a ordem em que eles são retornados. O geocodificador interpreta abreviações de maneiras diferentes dependendo linguagem natural, como abreviações de tipos de rua ou sinônimos que possam ser válidos em um idioma, mas não em outro. Por exemplo, utca. e tér são sinônimos para rua e praça, respectivamente em húngaro.
region
: o código da região, especificado como um ccTLD ("domínio de nível superior") de dois caracteres. Esse parâmetro só vai influenciar, não restringir totalmente, os resultados do geocodificador. Para mais Para mais informações, consulte Direcionamento de região abaixo. A também pode afetar os resultados com base na legislação aplicável.components
: um filtro de componentes com elementos. separadas por uma barra vertical (|
). O filtro de componentes obrigatório se a solicitação não incluir umaddress
. Cada elemento do filtro de componentes consiste em umcomponent:value
e restringe totalmente os resultados. do geocodificador. Veja mais informações sobre filtragem de componentes abaixo.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
Respostas
As respostas de geocodificação são retornadas no formato indicado pela sinalização output
.
na solicitação do URL ou no formato JSON por padrão.
Neste exemplo, a API Geocoding solicita um json
resposta para uma consulta sobre o endereço "1600 Amphitheatre Parkway, Mountain View,
CA".
Esta solicitação demonstra o uso da flag output
do JSON:
https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
Esta solicitação demonstra o uso da flag XML output
:
https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
Selecione as guias abaixo para ver os exemplos de respostas JSON e XML.
JSON
{ "results": [ { "address_components": [ { "long_name": "1600", "short_name": "1600", "types": [ "street_number" ] }, { "long_name": "Amphitheatre Parkway", "short_name": "Amphitheatre Pkwy", "types": [ "route" ] }, { "long_name": "Mountain View", "short_name": "Mountain View", "types": [ "locality", "political" ] }, { "long_name": "Santa Clara County", "short_name": "Santa Clara County", "types": [ "administrative_area_level_2", "political" ] }, { "long_name": "California", "short_name": "CA", "types": [ "administrative_area_level_1", "political" ] }, { "long_name": "United States", "short_name": "US", "types": [ "country", "political" ] }, { "long_name": "94043", "short_name": "94043", "types": [ "postal_code" ] }, { "long_name": "1351", "short_name": "1351", "types": [ "postal_code_suffix" ] } ], "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "geometry": { "location": { "lat": 37.4222804, "lng": -122.0843428 }, "location_type": "ROOFTOP", "viewport": { "northeast": { "lat": 37.4237349802915, "lng": -122.083183169709 }, "southwest": { "lat": 37.4210370197085, "lng": -122.085881130292 } } }, "place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8", "plus_code": { "compound_code": "CWC8+W7 Mountain View, CA", "global_code": "849VCWC8+W7" }, "types": [ "street_address" ] } ], "status": "OK" }
Observe que a resposta JSON contém dois elementos raiz:
"status"
contém metadados sobre a solicitação. Consulte Códigos de status abaixo."results"
contém uma matriz de informações de endereços geocodificados e informações geométricas.
Geralmente, apenas uma entrada na matriz "results"
é retornada para
pesquisas de endereço, embora o geocodificador possa retornar vários resultados quando as
as consultas são ambíguas.
XML
<GeocodeResponse> <status>OK</status> <result> <type>street_address</type> <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address> <address_component> <long_name>1600</long_name> <short_name>1600</short_name> <type>street_number</type> </address_component> <address_component> <long_name>Amphitheatre Parkway</long_name> <short_name>Amphitheatre Pkwy</short_name> <type>route</type> </address_component> <address_component> <long_name>Mountain View</long_name> <short_name>Mountain View</short_name> <type>locality</type> <type>political</type> </address_component> <address_component> <long_name>Santa Clara County</long_name> <short_name>Santa Clara County</short_name> <type>administrative_area_level_2</type> <type>political</type> </address_component> <address_component> <long_name>California</long_name> <short_name>CA</short_name> <type>administrative_area_level_1</type> <type>political</type> </address_component> <address_component> <long_name>United States</long_name> <short_name>US</short_name> <type>country</type> <type>political</type> </address_component> <address_component> <long_name>94043</long_name> <short_name>94043</short_name> <type>postal_code</type> </address_component> <geometry> <location> <lat>37.4224428</lat> <lng>-122.0842467</lng> </location> <location_type>ROOFTOP</location_type> <viewport> <southwest> <lat>37.4212648</lat> <lng>-122.0856069</lng> </southwest> <northeast> <lat>37.4239628</lat> <lng>-122.0829089</lng> </northeast> </viewport> </geometry> <place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id> <plus_code> <global_code>849VCWC8+X8</global_code> <compound_code>CWC8+X8 Mountain View, CA</compound_code> </plus_code> </result> </GeocodeResponse>
Observe que a resposta XML consiste em um único
<GeocodeResponse>
e dois elementos de nível superior:
<status>
contém metadados sobre a solicitação. Consulte Códigos de status abaixo.- Zero ou mais elementos
<result>
, cada um contendo um único conjunto de informações de endereços geocodificados e informações geométricas.
A resposta XML é consideravelmente mais longa do que a resposta JSON. Para
Por isso, recomendamos usar json
como a opção
a menos que seu serviço exija xml
por algum motivo.
Além disso, o processamento de árvores XML requer certo cuidado para que você faça referência
nós e elementos apropriados. Consulte
Análise de XML com XPath para alguns padrões de design recomendados para o processamento de saída.
- Os resultados XML são agrupados em um elemento
<GeocodeResponse>
raiz. - JSON indica entradas com vários elementos usando matrizes plurais (
types
), enquanto XML indica isso usando vários elementos singulares (<type>
). - Os elementos em branco são indicados por matrizes vazias em JSON, mas pela ausência de
esse elemento em XML. Uma resposta que não gera resultados retornará um erro
A matriz
results
em JSON, mas sem elementos<result>
em XML, por exemplo.
Códigos de status
O campo "status"
no objeto de resposta da geocodificação contém o status
da solicitação e podem conter informações de depuração para ajudá-lo a rastrear o motivo pelo qual a geocodificação
não está funcionando. O campo "status"
pode conter os seguintes valores:
"OK"
indica que nenhum erro ocorreu; o endereço foi analisado e, pelo menos, um geocódigo foi retornado."ZERO_RESULTS"
indica que o geocódigo deu certo, mas não retornou resultados. Isso pode ocorrer se o geocodificador recebeu umaddress
inexistente.OVER_DAILY_LIMIT
indica o seguinte:- A chave de API está ausente ou é inválida.
- O faturamento não foi ativado em sua conta.
- Um limite de uso definido pelo próprio usuário foi excedido.
- A forma de pagamento fornecida não é mais válida (por exemplo, uma o cartão de crédito expirou).
Consulte as Perguntas frequentes do Google Maps para saber como corrigir isso.
"OVER_QUERY_LIMIT"
indica que você ultrapassou sua cota."REQUEST_DENIED"
indica que o pedido foi recusado."INVALID_REQUEST"
normalmente indica que está faltando a consulta (address
,components
oulatlng
)."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.
Mensagens de erro
Quando o geocodificador retorna um código de status diferente de OK
, pode haver uma
error_message
no objeto de resposta da geocodificação. Este campo contém mais
informações detalhadas sobre os motivos por trás do código de status fornecido.
Resultados
Quando o geocodificador retorna resultados, ele os coloca em um results
(JSON)
matriz. Mesmo que o geocodificador não retorne resultados (por exemplo, quando o endereço não existe), ele ainda
retorna uma matriz results
vazia. (Respostas em XML consistem em zero ou mais
<result>
elements.)
Um resultado típico contém os seguintes campos:
- A matriz
types[]
indica o tipo do resultado. Essa matriz contém um conjunto de zero ou mais tags que identificam o tipo atributo retornado no resultado. Por exemplo, um geocódigo de "Chicago" retorna "região administrativa" que indica "Chicago" é uma cidade e também retorna "político" o que indica que é uma entidade política. Os componentes podem ter tipos vazios quando não houver tipos conhecidos para o componente de endereço. A API pode adicionar novos valores de tipo conforme necessário. Para mais informações, consulte Tipos e componentes de endereço. formatted_address
é uma string que contém o elemento endereço deste local.Esse endereço costuma ser equivalente ao endereço postal. Alguns países, como o Reino Unido, não permitem a distribuição de endereços postais verdadeiros devido a restrições de licenciamento.
O endereço formatado é composto de maneira lógica por um ou mais componentes de endereço. Por exemplo, o endereço "Avenida Paulista, 111, São Paulo, SP" consiste nos seguintes componentes: "Avenida Paulista" (o trajeto), "111" (o número), "São Paulo" (a cidade) e "SP" (o estado brasileiro).
Não analise o endereço formatado de maneira programática. Em vez disso, use os componentes de endereço individuais, que a resposta da API inclui, além do campo de endereço formatado.
address_components[]
é uma matriz contendo os valores componentes aplicáveis a este endereço.Normalmente, cada componente de endereço contém os seguintes campos:
types[]
é uma matriz que indica o tipo do componente de endereço. Consulte a lista de tipos compatíveis.long_name
é a descrição completa em texto ou o nome do componente do endereço retornado pelo geocodificador.short_name
é um nome abreviado, no formato de texto, para o componente de endereço, se estiver disponível. Por exemplo, um componente de endereço para o estado do Alasca pode ter umlong_name
de "Alaska" e umshort_name
de "AK", usando a abreviação postal de 2 letras.
Observe os seguintes fatos sobre a matriz
address_components[]
:- A matriz de componentes de endereço pode conter mais componentes do que
formatted_address
. - A matriz não inclui necessariamente todas as entidades políticas que contêm um endereço, além daquelas incluídas em
formatted_address
. Para recuperar todas as entidades políticas que contêm um endereço específico, use a geocodificação inversa, transmitindo a latitude/longitude do endereço como um parâmetro para a solicitação. - Não há garantia de que o formato da resposta vai permanecer o mesmo entre as solicitações. Especificamente, o número de
address_components
varia de acordo com o endereço solicitado e pode mudar para o mesmo endereço. Um componente pode mudar a posição na matriz. O tipo do componente pode mudar. Pode faltar um componente específico em uma resposta posterior.
Para processar a matriz de componentes, você deve analisar a resposta e selecionar valores apropriados usando expressões. Consulte o guia sobre analisar uma resposta.
postcode_localities[]
: uma matriz que indica até 100 localidades contido em um código postal. Só estará presente quando o resultado for um endereço que contém várias localidades.geometry
contém as seguintes informações:location
contém o valor de latitude e longitude geocodificado. Para valores normais pesquisas de endereço, esse campo é normalmente o mais importante.location_type
armazena dados adicionais sobre o local especificado. A valores a seguir são suportados no momento:"ROOFTOP"
indica que o resultado retornado é um geocódigo preciso para nas quais temos informações de localização que incluem o endereço."RANGE_INTERPOLATED"
indica que o resultado retornado reflete uma aproximação (normalmente em uma estrada) interpolada entre dois pontos precisos (como interseções). Resultados interpolados geralmente são retornados quando códigos geográficos de telhados não estão disponíveis para uma rua. endereço IP."GEOMETRIC_CENTER"
indica que o resultado retornado é o centro geométrico de um resultado, como uma polilinha (por exemplo, uma rua) ou um polígono (região)."APPROXIMATE"
indica que o o resultado retornado é aproximado.
viewport
contém a janela de visualização recomendada para exibição. o resultado retornado, especificado como dois valores de latitude,longitude que definem osouthwest
e cantonortheast
da caixa delimitadora da janela de visualização. Geralmente, o janela de visualização é usada para enquadrar um resultado ao exibi-lo ao usuário.bounds
(retornado opcionalmente) armazena a caixa delimitadora. que pode conter totalmente o resultado retornado. Esses limites podem não corresponder ao janela de visualização recomendada. Por exemplo, São Francisco inclui o Ilhas Farallon, que são tecnicamente parte da cidade, mas provavelmente não devem ser retornados na janela de visualização.
-
plus_code
(consulte Abrir código do local e Plus Codes) é uma codificação codificada referência de localização, derivada de coordenadas de latitude e longitude, que representa uma área: 1/8.000 de grau por 1/8.000 de grau (cerca de 14 m x 14 m no equador) ou menos. Os Plus Codes podem ser usados para substituir endereços em lugares onde não existem endereços (onde construções não estão numeradas ou as ruas não têm nome). A API nem sempre retorna os Plus Codes.Quando o serviço retorna um Plus Code, ele é formatado como um código global e um composto:
global_code
é um código de área com quatro caracteres e um código local com, pelo menos, seis caracteres (849VCWC8+R9).compound_code
é um código local com, pelo menos, seis caracteres e um local explícito (CWC8+R9, Mountain View, CA, EUA). Não analise esse conteúdo de forma programática.
-
partial_match
indica que o geocodificador não retornou uma correspondência exata para a solicitação original, mas conseguiu corresponder parte do endereço solicitado. Convém verificar se a solicitação original inclui erros de ortografia e/ou um endereço incompleto.Correspondências parciais ocorrem com mais frequência para endereços que não existem na localidade onde você enviou a solicitação. Elas também podem ser retornadas quando uma solicitação corresponde a dois ou mais locais na mesma localidade. Por exemplo, "Hillpar St, Bristol, UK" vai retornar uma correspondência parcial para Henry Street e Henrietta Street. Se uma solicitação incluir um componente de endereço com um erro ortográfico, o serviço de geocodificação pode sugerir um endereço alternativo. Sugestões acionadas dessa maneira também vão ser marcadas como correspondências parciais.
place_id
é um item exclusivo identificador que pode ser usado com outras APIs do Google. Por exemplo, é possível use oplace_id
em uma solicitação da API Places para receber detalhes de uma empresa local, como número de telefone, horário de funcionamento, avaliações e muito mais. Veja o ID de lugar geral do Google.
Tipos de endereço e de componentes de endereço
A matriz types[]
no resultado indica
tipo de endereço. Exemplos de tipos de endereço incluem um endereço, um
país ou uma entidade política. Também há uma matriz types[]
o address_components[]
, indicando o tipo de cada parte da
endereço IP. Exemplos incluem números de rua ou países. Veja abaixo uma lista completa
types.) Os endereços podem ter vários tipos. Os tipos podem ser considerados "tags".
Por exemplo, muitas cidades são marcadas com o political
e o
tipo locality
.
Os tipos a seguir são suportados e retornados pelo geocodificador nas Matrizes de tipo de endereço e tipo de componente de endereço:
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".
Uma lista vazia indica que não há tipos conhecidos para um componente de endereço específico, por exemplo, Lieu-dit na França.
Além do indicado acima, os componentes de endereço podem incluir os tipos listados aqui. Esta lista é não é uma lista completa e está sujeita a alterações.
floor
indica o andar de um edifício.establishment
geralmente indica um lugar que ainda não foi classificado.landmark
indica um lugar por perto que é usado como referência para ajudar na navegação.point_of_interest
indica um ponto de interesse nomeado.parking
indica um estacionamento ou uma estrutura desse tipo.post_box
indica uma caixa postal específica.postal_town
indica um agrupamento de áreas geográficas, comolocality
esublocality
, usadas para endereços de correspondência em alguns países.room
indica a sala de um edifício.street_number
indica o número exato da rua.bus_station
,train_station
etransit_station
indicam a localização de um ponto de ônibus, trem ou transporte público.
Polarização da janela de visualização
Em uma solicitação de geocodificação, você pode instruir o serviço Geocoding a preferir
resultados em uma determinada janela de visualização (expressa como uma caixa delimitadora). Você faz isso
no URL da solicitação, definindo o parâmetro bounds
.
O parâmetro bounds
define as coordenadas de latitude/longitude.
dos cantos sudoeste e nordeste dessa caixa delimitadora, usando um
(|
) para separar as coordenadas.
Por exemplo, um geocódigo para "Washington" normalmente retorna o estado dos EUA de Washington:
Solicitação:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY
Resposta:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "WA",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
},
"location" : {
"lat" : 47.7510741,
"lng" : -120.7401385
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
}
},
"place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
"types" : [ "administrative_area_level_1", "political" ]
}
],
"status" : "OK"
}
No entanto, adicionar um argumento bounds
definindo uma caixa delimitadora ao redor
a parte nordeste dos EUA resulta neste geocódigo que retorna a cidade de
Washington, D.C.:
Solicitação:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY
Resposta:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "Washington",
"types" : [ "locality", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "District of Columbia",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "DC",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, DC, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
},
"location" : {
"lat" : 38.9071923,
"lng" : -77.03687069999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
}
},
"place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Polarização de região
Em uma solicitação de geocodificação, você pode instruir o serviço Geocoding a retornar
resultados tendenciosos para uma região específica usando o region
. Esse parâmetro usa um ccTLD (código de país de nível
domínio) especificando a região polarização. A maioria dos códigos ccTLD é idêntica
ISO 3166-1, com algumas exceções notáveis. Por exemplo, os Estados Unidos
O ccTLD do Reino é "uk" (.co.uk
), enquanto o código ISO 3166-1 é "gb"
(tecnicamente para a entidade "Reino Unido da Grã-Bretanha e
Irlanda do Norte").
Os resultados de geocodificação podem ser polarizados para cada domínio no qual a principal O aplicativo Google Maps foi lançado oficialmente. O direcionamento somente prefere resultados de um domínio específico; caso existam resultados mais relevantes fora deste domínio, elas poderão ser incluídas.
Por exemplo, um geocódigo para "Toledo" retorna esse resultado, pois o padrão da API Geocoding é definido como Estados Unidos. Solicitação:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY
Resposta:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Lucas County",
"short_name" : "Lucas County",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Ohio",
"short_name" : "OH",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, OH, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
},
"location" : {
"lat" : 41.6639383,
"lng" : -83.55521200000001
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
}
},
"place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Uma solicitação de geocodificação para "Toledo" com region=es
(Espanha) vão
a cidade espanhola.
Solicitação:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo®ion=es&key=YOUR_API_KEY
Resposta:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Toledo",
"short_name" : "TO",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Castile-La Mancha",
"short_name" : "CM",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
},
"location" : {
"lat" : 39.8628316,
"lng" : -4.027323099999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
}
},
"place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Filtragem de componentes
Em uma resposta da Geocoding, a API Geocoding pode retornar endereços
resultados restritos a uma área específica. É possível especificar a restrição usando
o filtro components
. Um filtro consiste em uma lista de
Pares de component:value
separados por uma barra vertical (|
).
Os valores de filtro oferecem suporte aos mesmos métodos de correção ortográfica e parcial
correspondentes a outras solicitações de geocodificação. Se o geocodificador encontra uma correspondência parcial para um
filtro de componente, a resposta conterá um campo partial_match
.
As components
que podem ser filtradas incluem:
postal_code
corresponde apostal_code
epostal_code_prefix
.country
corresponde a um nome de país ou um código de país ISO 3166-1 de duas letras. A API segue a norma ISO para definindo países, e a filtragem funciona melhor quando se usa o parâmetro código ISO correspondente do país.
O seguinte components
pode ser usado para influenciar os resultados, mas não será
aplicada:
route
corresponde ao nome longo ou curto de uma rota.locality
partidas contralocality
esublocality
.administrative_area
corresponde a todas asadministrative_area
níveis.
Observações sobre a filtragem de componentes:
- Não repita esses filtros de componentes em solicitações, ou a API retornará
Invalid_request
:country
epostal_code
.route
- Se a solicitação contiver filtros de componentes repetidos, a API avaliará esses filtros como AND, não OR.
- Os resultados são consistentes com o Google Maps, que ocasionalmente produz
respostas
ZERO_RESULTS
inesperadas. Como usar o Place Autocomplete pode fornecer melhores resultados em alguns casos de uso. Para saber mais, consulte este Perguntas frequentes. - Para cada componente de endereço, especifique no
address
. ou em um filtrocomponents
, mas não ambos. Especificação os mesmos valores em ambos podem resultar emZERO_RESULTS
.
Um geocódigo para "High St, Hastings" com components=country:GB
retorna um resultado em Hastings, Inglaterra e não em Hastings-On-Hudson, EUA.
Solicitação:
https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY
Resposta:
{
"results" : [
{
"address_components" : [
{
"long_name" : "High Street",
"short_name" : "High St",
"types" : [ "route" ]
},
{
"long_name" : "Hastings",
"short_name" : "Hastings",
"types" : [ "postal_town" ]
},
{
"long_name" : "East Sussex",
"short_name" : "East Sussex",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "England",
"short_name" : "England",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United Kingdom",
"short_name" : "GB",
"types" : [ "country", "political" ]
},
{
"long_name" : "TN34 3EY",
"short_name" : "TN34 3EY",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "High St, Hastings TN34 3EY, UK",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
},
"location" : {
"lat" : 50.85830319999999,
"lng" : 0.5924594
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
}
},
"partial_match" : true,
"place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
"types" : [ "route" ]
}
],
"status" : "OK"
}
Uma solicitação de geocódigo para a localidade de "Santa Cruz" com components=country:ES
retorna Santa Cruz de Tenerife nas Ilhas Canárias, Espanha.
Solicitação:
https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|country:ES&key=YOUR_API_KEY
Resposta:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "Santa Cruz de Tenerife",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "TF",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Canary Islands",
"short_name" : "CN",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Santa Cruz de Tenerife, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
},
"location" : {
"lat" : 28.4636296,
"lng" : -16.2518467
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
}
},
"place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
A filtragem de componentes retorna uma resposta ZERO_RESULTS
.
somente se você fornecer filtros que se excluem mutuamente.
Solicitação:
https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY
Resposta:
{
"results" : [],
"status" : "ZERO_RESULTS"
}
É possível fazer consultas válidas sem o parâmetro address, usando o
Filtro components
. (Ao geocodificar um endereço completo,
o parâmetro address
será obrigatório se a solicitação contiver o
nomes e números de edifícios.
Solicitação:
https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY
Resposta:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Annankatu",
"short_name" : "Annankatu",
"types" : [ "route" ]
},
{
"long_name" : "Helsinki",
"short_name" : "HKI",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Finland",
"short_name" : "FI",
"types" : [ "country", "political" ]
},
{
"long_name" : "00101",
"short_name" : "00101",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "Annankatu, 00101 Helsinki, Finland",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
},
"location" : {
"lat" : 60.1657808,
"lng" : 24.938451
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
}
},
"place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
"types" : [ "route" ]
}
],
"status" : "OK"
}