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 JavaScript Object Notation (JSON);xmlindica 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, os parâmetros são separados usando o caractere "e comercial" ("&").
O restante desta página descreve a geocodificação e a geocodificação inversa separadamente, porque diferentes parâmetros estão disponíveis para cada tipo de solicitação.
Parâmetros de geocodificação (pesquisa de latitude/longitude)
Parâmetros obrigatórios em uma solicitação de geocodificação:
key: a chave de API do seu aplicativo. Essa chave identifica seu aplicativo para fins de gerenciamento de cota. Saiba como pegar uma chave.É necessário especificar
address,componentsou ambos em uma solicitação:address: o endereço ou 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 do endereço precisam ser delimitados por espaços (mostrados aqui como URL com escape para%20):address=24%20Sussex%20Drive%20Ottawa%20ON
%2Be os espaços, para%20):- O código global é um código de área com quatro caracteres e um código local com, pelo menos, seis caracteres (849VCWC8+R9 é
849VCWC8%2BR9). - O código composto é um código local com, pelo menos, seis caracteres e um local explícito (CWC8+R9 Mountain View, CA, EUA é
CWC8%2BR9%20Mountain%20View%20CA%20USA).
- O código global é um código de área com quatro caracteres e um código local com, pelo menos, seis caracteres (849VCWC8+R9 é
components: um filtro de componentes com elementos separados por um pipe (|). O filtro de componentes também é aceito como um parâmetro opcional se umaddressfor fornecido. Cada elemento no filtro de componentes consiste em um parcomponent:valuee restringe totalmente os resultados do geocodificador. Saiba mais sobre a filtragem de componentes abaixo.
Consulte as Perguntas frequentes para mais orientações.
Parâmetros opcionais em uma solicitação de geocodificação:
bounds: a caixa delimitadora da janela de visualização em que os resultados de geocódigo são direcionados de forma mais proeminente. Esse parâmetro apenas influencia, não restringe totalmente, os resultados do geocodificador. Para mais informações, consulte Direcionamento da janela de visualização abaixo.language: 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. Por isso, esta lista pode não estar completa.
- Se
languagenão for fornecido, o geocodificador tentará usar o idioma preferencial especificado no cabeçalhoAccept-Languageou o idioma nativo do domínio de onde a solicitação é enviada. - O geocodificador faz o possível para fornecer um endereço que seja legível para o usuário e para os moradores. Para alcançar esse objetivo, 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 retornados no mesmo idioma, que é escolhido pelo primeiro componente.
- Se um nome não estiver disponível no idioma preferido, o geocodificador 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. Por exemplo, utca e tér são sinônimos de rua e praça, respectivamente, em húngaro.
region: o código da região, especificado como um valor ccTLD ("domínio de nível superior") de dois caracteres. Esse parâmetro apenas influencia, não restringe totalmente, os resultados do geocodificador. Para mais informações, consulte Direcionamento de região abaixo. O parâmetro também pode afetar os resultados com base na legislação aplicável.components: um filtro de componentes com elementos separados por um pipe (|). O filtro de componentes é obrigatório se a solicitação não incluir umaddress. Cada elemento no filtro de componentes consiste em um parcomponent:valuee restringe totalmente os resultados do geocodificador. Saiba mais sobre a filtragem de componentes abaixo.extra_computations: use esse parâmetro para especificar os seguintes recursos adicionais na resposta:ADDRESS_DESCRIPTORS: consulte descritores de endereço para mais detalhes.BUILDING_AND_ENTRANCES: consulte entradas e contornos de edifícios para mais detalhes.
extra_computationsna 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 flag output
na solicitação de URL ou no formato JSON por padrão.
Neste exemplo, a API Geocoding solicita uma resposta json para uma consulta no endereço "1600 Amphitheatre Parkway, Mountain View, CA".
Esta solicitação demonstra o uso da flag output 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 output do XML:
https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
Selecione as guias abaixo para conferir 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ço e geometria geocodificadas.
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 forem 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>
A resposta XML consiste em um único
<GeocodeResponse> e dois elementos de nível superior:
<status>contém metadados sobre a solicitação. Consulte os Códigos de status abaixo.- Zero ou mais elementos
<result>, cada um contendo um único conjunto de informações de endereço e geometria geocodificados.
A resposta XML é consideravelmente mais longa do que a resposta JSON. Por
esse motivo, recomendamos que você use json como a sinalização de saída
preferida, a menos que seu serviço exija xml por algum motivo.
Além disso, o processamento de árvores XML requer alguns cuidados para que você faça referência
a nós e elementos adequados. Consulte
Como analisar XML com XPath para conferir alguns padrões de design recomendados para processamento de saída.
- Os resultados em XML são agrupados em um elemento raiz
<GeocodeResponse>. - O JSON denota entradas com vários elementos por matrizes plurais (
types), enquanto o XML as denota usando vários elementos singulares (<type>). - Os elementos em branco são indicados por matrizes vazias em JSON, mas pela ausência de
qualquer elemento no XML. Uma resposta que não gera resultados vai retornar uma matriz
resultsvazia em JSON, mas nenhum elemento<result>em XML, por exemplo.
Códigos de status
O campo "status" no objeto de resposta de geocodificação contém o status
da solicitação e pode conter informações de depuração para ajudar a rastrear o motivo da falha da geocodificação. 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 umaddressinexistente.OVER_DAILY_LIMITindica uma das seguintes opções:- A chave de API está ausente ou é inválida.
- O faturamento não foi ativado na 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, o cartão de crédito expirou).
Consulte as Perguntas frequentes sobre o Google Maps para saber como corrigir esse problema.
"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,componentsoulatlng)."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 um campo error_message adicional no objeto de resposta de geocodificação. Esse campo contém informações mais detalhadas sobre os motivos do código de status fornecido.
Resultados
Quando o geocodificador retorna resultados, ele os coloca em uma matriz results (JSON). Mesmo que o geocodificador não retorne resultados (por exemplo, se o endereço não
existir), ele ainda vai retornar uma matriz results vazia. As respostas XML consistem em zero
ou mais elementos <result>.
Um resultado típico contém os seguintes campos:
- A matriz
types[]indica o tipo do resultado retornado. Essa matriz contém um conjunto de zero ou mais tags que identificam o tipo de recurso retornado no resultado. Por exemplo, um geocódigo de "Chicago" retorna "região", que indica que "Chicago" é uma cidade, e também retorna "político", que indica que é uma entidade política. Os componentes podem ter uma matriz de tipos vazia quando não há tipos conhecidos para esse componente de endereço. A API pode adicionar novos valores de tipo conforme necessário. Para mais informações, consulte Tipos de endereço e componentes de endereço. formatted_addressé uma string que contém o endereço legível do 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 que contém os componentes separados aplicáveis a esse 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_namede "Alaska" e umshort_namede "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_componentsvaria 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ê precisa analisar a resposta e selecionar os valores apropriados usando expressões. Consulte o guia sobre como analisar uma resposta.
postcode_localities[]é uma matriz que denota até 100 localidades contidas em um código postal. Isso só aparece quando o resultado é um código postal com várias localidades.geometrycontém as seguintes informações:locationcontém o valor de latitude, longitude geocodificado. Para pesquisas de endereço normais, esse campo geralmente é o mais importante.location_typearmazena dados adicionais sobre o local especificado. Os seguintes valores são compatíveis:"ROOFTOP"indica que o resultado retornado é um geocódigo preciso para o qual temos informações de localização precisas até o endereço da rua."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 rooftop não estão disponíveis para um endereço."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 resultado retornado é aproximado.
viewportcontém a viewport recomendada para exibir o resultado retornado, especificado como dois valores de latitude e longitude que definem osouthweste o cantonortheastda caixa delimitadora da viewport. Geralmente, a janela de visualização é usada para enquadrar um resultado ao mostrá-lo a um usuário.bounds(retornado opcionalmente) armazena a caixa delimitadora, que pode conter totalmente o resultado retornado. Talvez esses valores não correspondam à janela de visualização recomendada. Por exemplo, São Francisco inclui as Ilhas Farallon, que tecnicamente fazem parte da cidade, mas provavelmente não precisam ser retornadas na janela de informações.
-
plus_code(consulte Open Location Code e Plus Codes; links em inglês) é uma referência de local codificada, derivada de coordenadas de latitude e longitude, que representa uma área: 1/8000 de um grau por 1/8000 de um grau (aproximadamente 14 m x 14 m no Equador) ou menor. 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. A API nem sempre retorna códigos Plus.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_matchindica 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 identificador exclusivo que pode ser usado com outras APIs do Google. Por exemplo, você pode usarplace_idem uma solicitação da API Places para conferir detalhes de uma empresa local, como número de telefone, horário de funcionamento, avaliações de usuários e muito mais. Consulte a visão geral do ID de lugar.
Tipos de endereço e de componentes de endereço
A matriz types na resposta indica o tipo de endereço. Exemplos de tipos de endereço incluem um endereço de rua, um país ou uma entidade política. A matriz types no campo address_component indica o tipo de cada parte do endereço. Exemplos incluem números de rua ou países.
Os endereços podem ter vários tipos. Os tipos podem ser considerados "tags".
Por exemplo, muitas cidades são marcadas com os tipos political e
locality.
Os tipos a seguir são aceitos e retornados nas matrizes de tipo de endereço e de componente de endereço:
| Tipo de endereço | Descrição |
|---|---|
street_address |
Um endereço preciso. |
route |
Uma rota nomeada (como "US 101"). |
intersection |
Uma interseção principal, normalmente de duas estradas principais. |
political |
Uma entidade política. Normalmente, esse tipo indica um polígono de administração civil. |
country |
A entidade política nacional, normalmente o tipo de ordem mais alta retornado pelo geocodificador. |
administrative_area_level_1 |
Uma entidade civil de primeira ordem, abaixo do nível de país. Nos Estados Unidos, esses níveis administrativos são estados. Nem todos os países incluem esses níveis administrativos. Na maioria dos casos, os nomes curtos de administrative_area_level_1 são muito parecidos com as subdivisões da ISO 3166-2 e outras listas amplamente divulgadas. No entanto, 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 |
Uma entidade civil de segunda ordem, abaixo do nível de país. Nos Estados Unidos, esses níveis administrativos são condados. Nem todos os países incluem esses níveis administrativos. |
administrative_area_level_3 |
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 |
Uma entidade civil de quarta 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_5 |
Uma entidade civil de quinta 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_6 |
Uma entidade civil de sexta 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_7 |
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 |
Um nome alternativo usado com frequência para a entidade. |
locality |
Uma entidade política incorporada de cidade ou município. |
sublocality |
Uma entidade civil de primeira ordem, abaixo de uma região administrativa. 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 |
Um bairro com nome. |
premise |
Um local nomeado, geralmente um edifício ou um conjunto de edifícios com um nome comum. |
subpremise |
Uma entidade endereçável abaixo do nível da instalação, como um apartamento, uma unidade ou uma suíte. |
plus_code |
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. Consulte https://plus.codes para mais detalhes. |
postal_code |
Um código postal, como o usado para endereçar correspondências no país. |
natural_feature |
Um recurso natural de destaque. |
airport |
Um aeroporto. |
park |
Um parque nomeado. |
point_of_interest |
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 abaixo.
| Tipo de componente de endereço | Descrição |
|---|---|
floor |
O andar de um endereço de edifício. |
establishment |
Geralmente, um lugar que ainda não foi categorizado. |
landmark |
Um lugar por perto que é usado como referência para ajudar na navegação. |
point_of_interest |
Um ponto de interesse nomeado. |
parking |
Um estacionamento ou uma estrutura para estacionar. |
post_box |
Uma caixa postal específica. |
postal_town |
Um agrupamento de áreas geográficas, como locality e sublocality, usado para endereços de correspondência em alguns países. |
room |
O número da sala de um endereço de edifício. |
street_number |
O número exato da rua. |
bus_station, train_station e transit_station |
O local de uma parada de ônibus, trem ou transporte público. |
Direcionamento de janela de visualização
Em uma solicitação de geocodificação, é possível instruir o serviço a dar preferência a resultados em uma determinada janela de visualização (expressa como uma caixa delimitadora). Para isso,
defina o parâmetro bounds no URL da solicitação.
O parâmetro bounds define as coordenadas de latitude/longitude
dos cantos sudoeste e nordeste desse retângulo delimitante usando um caractere de pipe
(|) para separar as coordenadas.
Por exemplo, um geocódigo para "Washington" geralmente retorna o estado de Washington, nos EUA:
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, a adição de um argumento bounds que define uma caixa delimitadora em torno da parte nordeste dos EUA faz com que esse geocódigo retorne 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, é possível instruir o serviço de geocodificação a retornar resultados tendenciosos para uma região específica usando o parâmetro region. Esse parâmetro usa um argumento ccTLD (domínio de nível superior com código de país) que especifica a inclinação da região. A maioria dos códigos ccTLD é idêntica aos
códigos ISO 3166-1, com algumas exceções notáveis. Por exemplo, o ccTLD do Reino Unido é "uk" (.co.uk), e 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 tendenciosos para cada domínio em que o aplicativo principal do Google Maps é lançado oficialmente. O direcionamento só prioriza resultados de um domínio específico. Resultados mais relevantes fora desse domínio podem ser incluídos.
Por exemplo, um geocódigo para "Toledo" retorna esse resultado porque o domínio 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) vai retornar 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 de geocodificação, a API Geocoding pode retornar resultados de endereço restritos a uma área específica. É possível especificar a restrição
usando o filtro components. Um filtro consiste em uma lista de pares component:value separados por um pipe (|). Os valores de filtro são compatíveis com os mesmos métodos de correção ortográfica e correspondência parcial de outras solicitações de geocodificação. Se o geocodificador encontrar uma correspondência parcial para um filtro de componente, a resposta conterá um campo partial_match.
Os components que podem ser filtrados incluem:
postal_codecorresponde apostal_codeepostal_code_prefix.countrycorresponde 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 definir países, e a filtragem funciona melhor quando utiliza o respectivo código ISO do país.
O components a seguir pode ser usado para influenciar os resultados, mas não será
aplicado:
routecorresponde ao nome longo ou curto de uma rota.localitycorresponde aos tiposlocalityesublocality.administrative_areacorresponde a todos os níveis deadministrative_area.
Observações sobre a filtragem de componentes:
- Não repita esses filtros de componente nas solicitações, ou a API vai retornar
Invalid_request:country,postal_code,route - Se a solicitação tiver filtros de componentes repetidos, a API vai avaliar esses filtros como E, e não como OU.
- Os resultados são consistentes com o Google Maps, que às vezes gera respostas
ZERO_RESULTSinesperadas. O uso do Place Autocomplete pode gerar resultados melhores em alguns casos de uso. Para saber mais, consulte estas perguntas frequentes. - Para cada componente de endereço, especifique-o no parâmetro
addressou em um filtrocomponents, mas não em ambos. Especificar os mesmos valores em ambos pode resultar emZERO_RESULTS.
Um geocódigo para "High St, Hastings" com components=country:GB retorna um resultado
em Hastings, Inglaterra, em vez de 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 geocodificação 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 de endereço usando o filtro components. Ao geocodificar um endereço completo, o parâmetro address é obrigatório se a solicitação contiver os nomes e números dos 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"
}