Solicitação e resposta de geocodificação

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) ou
  • xml 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, 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 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 usado pelo serviço postal nacional do país em questão. Evite elementos de endereço adicionais, como nomes de empresas e números de unidades, conjuntos ou andares. Os elementos de endereço precisam ser delimitados por espaços (mostrados aqui como escape do URL para %20): 
    address=24%20Sussex%20Drive%20Ottawa%20ON
    Formate os Plus Codes conforme 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 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).

    --OR--
    components: um filtro de componentes com elementos separados por uma barra vertical (|). O filtro de componentes também será aceito como um parâmetro opcional se um address for fornecido. Cada elemento do filtro de componentes consiste em um par de component:value e restringe totalmente os resultados do geocodificador. Saiba mais sobre a filtragem de componentes abaixo.
  • key: a chave de API do aplicativo. Essa chave identifica seu aplicativo para fins de gerenciamento de cotas. Saiba como receber uma chave.

Para mais orientações, consulte as Perguntas frequentes.

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 devem ser direcionados de forma mais proeminente. Esse parâmetro não restringe totalmente, mas apenas influencia, os resultados do geocodificador. Para saber mais, consulte Polarização da janela de visualização abaixo.
  • language: o idioma no qual os resultados serão retornados.
    • Consulte a lista de idiomas compatíveis. O Google atualiza os idiomas compatíveis com frequência. Por isso, essa lista pode não estar completa.
    • Se language não for fornecido, o geocodificador tentará usar o idioma preferido conforme especificado no cabeçalho Accept-Language ou 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 locais. Para atingir esse objetivo, ele retorna endereços no idioma local, transliterado 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 preferencial. Todos os componentes de endereço são retornados no mesmo idioma, escolhido no primeiro componente.
    • Se um nome não estiver disponível no idioma preferencial, 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 são retornados. O geocodificador interpreta abreviações de maneiras diferentes dependendo do idioma, como abreviações de tipos de rua 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 para rua e praça, respectivamente em húngaro.
  • region: o código regional, especificado como um valor ccTLD ("domínio de nível superior") de dois caracteres. Esse parâmetro não restringe totalmente, mas apenas influencia, 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 uma barra vertical (|). O filtro de componentes é obrigatório se a solicitação não incluir um address. Cada elemento do filtro de componentes consiste em um par de component:value e restringe totalmente os resultados do geocodificador. Saiba mais sobre a filtragem de componentes abaixo.
  • extra_computations: o único valor permitido para esse parâmetro é ADDRESS_DESCRIPTORS. Consulte os descritores de endereço para mais detalhes.

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 uma resposta json para uma consulta no 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, mas o geocodificador pode retornar vários resultados quando as consultas de endereço 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. Por esse motivo, recomendamos que você use json como a sinalização de saída preferencial, a menos que seu serviço exija xml por algum motivo. Além disso, o processamento de árvores XML requer certo cuidado para referenciar nós e elementos adequados. Consulte Analisar XML com XPath para ver 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 essas entradas usando vários elementos singulares (<type>).
  • Os elementos em branco são indicados por meio de matrizes vazias em JSON e pela ausência desses elementos em XML. Uma resposta que não gera resultados retorna uma matriz results vazia em JSON, mas não retorna 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 pode conter informações de depuração para ajudar a rastrear por que 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 um address 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, o cartão de crédito expirou).

    Consulte as Perguntas frequentes do 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 ou latlng).
  • "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 do Geocoding. Esse campo contém informações mais detalhadas sobre os motivos por trás 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, quando o endereço não existe), ele ainda retorna uma matriz results vazia. As respostas em 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", indicando que é uma entidade política. Os componentes poderão ter uma matriz de tipos vazia quando não houver 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 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 um long_name de "Alaska" e um short_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, analise a resposta e selecione os valores apropriados usando as expressões. Consulte o guia sobre como analisar uma resposta.

  • postcode_localities[] é uma matriz que indica até 100 localidades contidas em um código postal. Isso só está presente quando o resultado é um CEP que contém várias localidades.
  • geometry contém as seguintes informações:
    • location contém o valor de latitude e longitude geocodificado. Para pesquisas normais de endereço, esse campo é normalmente o mais importante.

    • location_type armazena dados adicionais sobre o local especificado. No momento, os seguintes valores são aceitos:

      • "ROOFTOP" indica que o resultado retornado é um geocódigo preciso. 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 via) interpolada entre dois pontos precisos (como interseções). Resultados interpolados geralmente são retornados quando geocódigos de telhado 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.
    • viewport contém a janela de visualização recomendada para mostrar o resultado retornado, especificada como dois valores de latitude e longitude que definem os cantos southwest e northeast da caixa delimitadora da janela de visualização. Geralmente, a janela de visualização é usada para enquadrar um resultado quando ele é exibido para o usuário.
    • bounds (retornado opcionalmente) armazena a caixa delimitadora que pode conter totalmente o resultado retornado. Esses limites podem não corresponder à janela de visualização recomendada. Por exemplo, São Francisco inclui as Ilhas Farallon, que tecnicamente são parte da cidade, mas provavelmente não deveriam ser retornadas na janela de visualização.
  • plus_code (consulte Código de local aberto e Plus Codes) é uma referência de local codificada, 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 eles não existem, ou seja, quando os edifícios não estão numerados 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.
    Quando disponível, a API retorna o código global e o composto. No entanto, se o resultado estiver em um local remoto (por exemplo, um oceano ou deserto), apenas o código global poderá ser retornado.

  • 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 identificador exclusivo que pode ser usado com outras APIs do Google. Por exemplo, você pode usar place_id em uma solicitação da API Places para ver 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 dos IDs de lugar.

Tipos de endereço e de componentes de endereço

A matriz types[] no resultado indica o tipo de endereço. Exemplos de tipos de endereço incluem endereço, país ou entidade política. Há também uma matriz types[] em address_components[], indicando o tipo de cada parte do endereço. Exemplos incluem números de rua ou países. Veja abaixo uma lista completa de tipos. Os endereços podem ter vários tipos. Os tipos podem ser considerados "tags". Por exemplo, muitas cidades são marcadas com o tipo political e locality.

Os tipos a seguir são aceitos e retornados pelo geocodificador nas matrizes de tipo de endereço e 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 nomeado
  • premise indica um local nomeado, normalmente um edifício ou condomínios com um nome comum
  • subpremise 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 comum
  • plus_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. Essa lista não é 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, como locality e sublocality, 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 e transit_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, é possível instruir o serviço Geocoding a dar preferência a 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 caractere de barra vertical (|) 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, adicionar um argumento bounds que define uma caixa delimitadora ao redor da parte nordeste dos EUA resulta nesse 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, é possível instruir o serviço Geocoding a retornar resultados direcionados a uma região específica usando o parâmetro region. Esse parâmetro usa um argumento ccTLD (domínio de nível superior do código de país) que especifica a polarização de 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), enquanto o código ISO 3166-1 é "gb" (tecnicamente para a entidade "Reino Unido da Grã-Bretanha e Irlanda do Norte").

Os resultados da geocodificação podem ser polarizados para cada domínio no qual o aplicativo principal do Google Maps tenha sido oficialmente lançado. 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) retornará a cidade espanhola.

Solicitação:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&region=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 API Geocoding, ela 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 de component:value separados por uma barra vertical (|). Os valores de filtro são compatíveis com os mesmos métodos de correção ortográfica e correspondência parcial que outras solicitações do Geocoding. Se o geocodificador encontrar 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 a postal_code e postal_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 o padrão ISO para definir países, e a filtragem funciona melhor quando é usado o código ISO correspondente do país.

O components a seguir pode ser usado para influenciar os resultados, mas não será aplicado:

  • route corresponde ao nome longo ou curto de uma rota.
  • locality corresponde aos tipos locality e sublocality.
  • administrative_area corresponde a todos os níveis de administrative_area.

Observações sobre a filtragem de componentes:

  • Não repita esses filtros de componentes nas solicitações. Caso contrário, a API vai retornar Invalid_request: country, postal_code, route.
  • Se a solicitação contiver filtros de componentes repetidos, a API avaliará esses filtros como AND, não como OR.
  • Os resultados são consistentes com o Google Maps, que às vezes produz respostas ZERO_RESULTS inesperadas. Usar o Place Autocomplete pode gerar resultados melhores em alguns casos de uso. Para saber mais, consulte estas perguntas frequentes.
  • Especifique cada componente de endereço no parâmetro address ou em um filtro components, mas não em ambos. Especificar os mesmos valores em ambos pode resultar em ZERO_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 retornará uma resposta ZERO_RESULTS somente se você fornecer filtros que se excluam.

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 será necessário se a solicitação contiver os 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"
}