Serviço Geocoding

Visão geral

Geocodificação é o processo de conversão de endereços (como "1600 Amphitheatre Parkway, Mountain View, CA") em coordenadas geográficas (como latitude 37.423021 e longitude -122.083739) que podem ser usadas para inserir marcadores ou posicionar o mapa.

A geocodificação inversa é o processo de conversão de coordenadas geográficas em um endereço legível. O geocodificador inverso também permite encontrar o endereço de um determinado ID de local.

A Google Maps API oferece uma classe de geocodificador que geocodifica e geocodifica inversamente de forma dinâmica a entrada do usuário. Quando a API é carregada, ela recebe uma cota inicial de solicitações de geocodificação. Após usar essa cota, solicitações adicionais terão limitações de uso por segundo. Em vez disso, para geocodificar endereços estáticos e conhecidos, consulte a documentação do serviço web Geocoding.

Solicitações de Geocoding

O acesso ao serviço Geocoding é assíncrono, pois a Google Maps API precisa chamar um servidor externo. Por isso, passe um método de retorno de chamada a ser executado na conclusão da solicitação. Esse método de retorno de chamada processa os resultados. Observe que o geocodificador pode retornar mais de um resultado.

Acesse o serviço Geocoding da Google Maps API no código usando o objeto google.maps.Geocoder. O método Geocoder.geocode() inicia uma solicitação ao serviço Geocoding passando um literal de objeto GeocoderRequest contendo os termos de entrada e um método de retorno de chamada para execução no recebimento da resposta.

O literal de objeto GeocoderRequest contém os seguintes campos:

{
 address: string,
 location: LatLng,
 placeId: string,
 bounds: LatLngBounds,
 componentRestrictions: GeocoderComponentRestrictions,
 region: string
}

Parâmetros obrigatórios: É necessário informar um, e apenas um, dos seguintes campos:

• address — o endereço a ser geocodificado.
• location — o LatLng (ou LatLngLiteral) para o qual você quer obter o endereço legível mais próximo. O geocodificador executa uma geocodificação inversa. Consulte Geocodificação inversa para obter mais informações.
• placeId — o ID de local da localização para a qual você deseja obter o endereço legível mais próximo. O ID de local é um identificador exclusivo que pode ser usado com outras APIs do Google. Por exemplo, você pode usar o placeIdlocal retornado pela Google Maps Roads API para obter o endereço de um ponto registrado. Para saber mais sobre IDs de local, consulte a visão geral de IDs de local. Se você passa um placeId, o geocodificador executa uma geocodificação inversa. Consulte Geocodificação inversa para obter mais informações.

Parâmetros opcionais:

• bounds — os LatLngBounds nos quais os resultados da geocodificação são direcionados de forma mais proeminente. O parâmetro bounds influencia, mas não restringe totalmente, os resultados do geocodificador. (Para saber mais, consulte Direcionamento de porta de visualização abaixo.)
• componentRestrictions — usado para restringir os resultados a uma área específica. (Para saber mais, consulte Filtragem de componentes abaixo.)
• region — o código de região especificado como uma subtag de idioma region da IANA. Na maioria das vezes, essas tags são mapeadas diretamente para valores de dois caracteres de ccTLD ("domínio de nível superior") familiares. O parâmetro region influencia, mas não restringe totalmente, os resultados do geocodificador. (Para saber mais, consulte Direcionamento de código de região abaixo.)

Respostas de geocodificação

O serviço Geocoding exige um método de retorno de chamada para execução na recuperação dos resultados do geocodificador. Esse retorno de chamada deve passar dois parâmetros para receber os results e um código de status, nessa ordem.

Resultados da geocodificação

O objeto GeocoderResult representa um único resultado de geocodificação. Uma solicitação de geocodificação pode retornar vários objetos de resultado:

results[]: {
 types[]: string,
 formatted_address: string,
 address_components[]: {
   short_name: string,
   long_name: string,
   postcode_localities[]: string,
   types[]: string
 },
 partial_match: boolean,
 place_id: string,
 postcode_localities[]: string,
 geometry: {
   location: LatLng,
   location_type: GeocoderLocationType
   viewport: LatLngBounds,
   bounds: LatLngBounds
 }
}

Esses campos são explicados a seguir:

• types[] é uma matriz indicando 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 código geográfico de "Chicago" retorna "locality", que indica que "Chicago" é uma cidade, e retorna também "political", indicando que é uma entidade política.
• formatted_address é uma string que contém o endereço legível da localização. Frequentemente esse endereço é equivalente ao "endereço postal" que, algumas vezes, difere de um país para o outro. (Observe que alguns países, como a Grã-Bretanha, não permitem a distribuição de endereços postais verdadeiros devido a restrições de licenciamento.) Normalmente, esse endereço é composto de um ou mais componentes de endereço. Por exemplo, o endereço "111 8th Avenue, New York, NY" contém componentes de endereço separados para "111 8th Avenue" (um endereço), "New York" (a cidade) e "NY" (o estado dos EUA). Esses componentes de endereço são comentados abaixo. (Para obter mais informações sobre tipos, consulte Tipos abaixo.)
• address_components[] é uma matriz que contém componentes de endereço separados, como explicado acima.

• 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. Pode ser recomendável 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ê passou a solicitação. Elas também podem ser retornadas quando uma solicitação corresponde a dois ou mais locais na mesma localidade. Por exemplo, "21 Henr St, Bristol, UK" retornará uma correspondência parcial para Henry Street e Henrietta Street. Observe que, se uma solicitação incluir um componente de endereço com um erro ortográfico, o serviço de geocodificação poderá sugerir um endereço alternativo. Sugestões acionadas dessa maneira também serão marcadas como correspondências parciais.

• place_id é um identificador único de um local que pode ser usado com outras Google APIs. Por exemplo, use place_id com a biblioteca Google Places API para obter detalhes sobre um estabelecimento local, como número de telefone, horário de funcionamento, comentários de usuários e muito mais. Consulte a visão geral de IDs de local.
• postcode_localities[] é uma matriz que denota todas as localidades contidas em um código postal. Esse elemento só está presente quando o resultado é um código postal que contém várias localidades.

• geometry contém as seguintes informações:

  • location contém o valor de latitude e longitude geocodificado. Observe que retornamos essa localização como um objeto LatLng e não como uma string formatada.
  • location_type armazena dados adicionais sobre a localização especificada. No momento, os seguintes valores são permitidos:
    • google.maps.GeocoderLocationType.ROOFTOP indica que o resultado retornado reflete um código geográfico preciso.
    • google.maps.GeocoderLocationType.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 códigos geográficos de rooftop não estão disponíveis para um endereço.
    • google.maps.GeocoderLocationType.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).
    • google.maps.GeocoderLocationType.APPROXIMATE indica que o resultado retornado é uma aproximação.
  
  
  • viewport armazena a porta de visualização recomendada para o resultado retornado.
  • bounds (opcional) armazena os LatLngBounds que podem conter totalmente o resultado retornado. Observe que esses valores podem não corresponder à porta de visualização recomendada. (Por exemplo, São Francisco inclui as Ilhas Farallon que, tecnicamente, fazem parte da cidade, mas não deveriam ser retornadas na porta de visualização.)

Os endereços são retornados pelo geocodificador usando a configuração de idioma preferencial do navegador ou o idioma especificado no carregamento do JavaScript da API usando o parâmetro language. (Para obter mais informações, consulte Localização.)

Tipos de componentes de endereço

A matriz types[] no resultado retornado indica o tipo de endereço. Esses tipos também podem ser retornados em matrizes address_components[] para indicar o tipo do componente de endereço específico. Endereços no geocodificador podem ter vários tipos. Os tipos podem ser considerados "tags". Por exemplo, muitas cidades incluem as tags de tipo political e locality.

Os tipos a seguir são permitidos e retornados pelo geocodificador HTTP:

• street_address indica um endereço preciso.
• route indica uma rota com nome (como "US 101").
• intersection indica uma interseção, geralmente de duas vias importantes.
• 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 normalmente é 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 estados. Nem todas as nações incluem esses níveis administrativos.
• administrative_area_level_2 indica uma entidade civil de segunda ordem abaixo do nível do país. Nos Estados Unidos, esses níveis administrativos são condados. Nem todas as nações incluem esses níveis administrativos.
• administrative_area_level_3 indica uma entidade civil de terceira ordem abaixo do nível do país. Esse tipo indica uma divisão civil secundária. Nem todas as nações 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 todas as nações 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 todas as nações incluem esses níveis administrativos.
• colloquial_area indica um nome alternativo comumente usado 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. Algumas localizações podem receber um destes tipos adicionais: sublocality_level_1 a sublocality_level_5. Cada nível de sublocalidade é uma entidade civil. Números maiores indicam uma área geográfica menor.
• neighborhood indica um bairro com nome.
• premise indica uma localização com nome, geralmente um prédio ou um conjunto de prédios com um nome em 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.
• postal_code indica um código postal usado pelo serviço postal do país.
• natural_feature indica uma característica natural proeminente.
• airport indica um aeroporto.
• park indica um parque com nome.

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 desses tipos, os componentes de endereço podem incluir os tipos abaixo:

• post_box indica uma caixa postal específica.
• street_number indica o número exato do local na rua.
• floor indica o andar no endereço de um edifício.
• room indica a sala no endereço de um edifício.

Códigos de status

O código de status pode retornar um dos seguintes valores:

• "OK" indica que nenhum erro ocorreu; o endereço foi analisado e pelo menos um código geográfico foi retornado.
• ZERO_RESULTS indica que o código geográfico foi bem-sucedido, mas não retornou resultados. Isso poderá ocorrer se o geocodificador receber um address que não existe.
• "OVER_QUERY_LIMIT" indica que você ultrapassou a cota.
• "REQUEST_DENIED" indica que a solicitação foi negada.
• "INVALID_REQUEST" geralmente indica que a consulta (address, components ou latlng) está ausente.
• "UNKNOWN_ERROR" indica que a solicitação não foi processada devido a um erro de servidor. A solicitação poderá ser bem-sucedida se você tentar novamente.

Nesse exemplo, geocodificamos um endereço e colocamos um marcador nos valores retornados de latitude e longitude. Observe que o manipulador é passado como um literal de função anônimo.

  var geocoder;
  var map;
  function initialize() {
    geocoder = new google.maps.Geocoder();
    var latlng = new google.maps.LatLng(-34.397, 150.644);
    var mapOptions = {
      zoom: 8,
      center: latlng
    }
    map = new google.maps.Map(document.getElementById("map"), mapOptions);
  }

  function codeAddress() {
    var address = document.getElementById("address").value;
    geocoder.geocode( { 'address': address}, function(results, status) {
      if (status == google.maps.GeocoderStatus.OK) {
        map.setCenter(results[0].geometry.location);
        var marker = new google.maps.Marker({
            map: map,
            position: results[0].geometry.location
        });
      } else {
        alert("Geocode was not successful for the following reason: " + status);
      }
    });
  }

<body onload="initialize()">
 <div id="map" style="width: 320px; height: 480px;"></div>
  <div>
    <input id="address" type="textbox" value="Sydney, NSW">
    <input type="button" value="Encode" onclick="codeAddress()">
  </div>
</body>

Ver o exemplo (geocoding-simple.html)

Geocodificação inversa (busca de endereço)

O termo geocodificação geralmente se refere à conversão de um endereço legível em uma localização em um mapa. O processo inverso, ou seja, converter uma localização no mapa em um endereço legível, é conhecido como geocodificação inversa.

O geocodificador permite a geocodificação inversa direta. Em vez de informar um address textual, informe um par de latitude/longitude separado por vírgula no parâmetro location. Como alternativa, informe um placeId para encontrar o endereço de um determinado ID de local.

Geocodificação inversa por localização

O exemplo a seguir geocodifica um valor de latitude/longitude e centraliza o mapa nessa localização, exibindo uma janela de informações com o endereço formatado. Retornamos o segundo resultado, que é menos específico que o primeiro (neste caso, um nome de bairro):

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 8,
    center: {lat: 40.731, lng: -73.997}
  });
  var geocoder = new google.maps.Geocoder;
  var infowindow = new google.maps.InfoWindow;

  document.getElementById('submit').addEventListener('click', function() {
    geocodeLatLng(geocoder, map, infowindow);
  });
}

function geocodeLatLng(geocoder, map, infowindow) {
  var input = document.getElementById('latlng').value;
  var latlngStr = input.split(',', 2);
  var latlng = {lat: parseFloat(latlngStr[0]), lng: parseFloat(latlngStr[1])};
  geocoder.geocode({'location': latlng}, function(results, status) {
    if (status === google.maps.GeocoderStatus.OK) {
      if (results[1]) {
        map.setZoom(11);
        var marker = new google.maps.Marker({
          position: latlng,
          map: map
        });
        infowindow.setContent(results[1].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert('No results found');
      }
    } else {
      window.alert('Geocoder failed due to: ' + status);
    }
  });
}

Ver o exemplo (geocoding-reverse.html).

Observe que, no exemplo anterior, mostramos o segundo resultado (selecionando results[1]). O geocodificador inverso retorna frequentemente mais de um resultado. "Endereços" geocodificados não são apenas endereços postais, mas qualquer forma de nomear uma localização geograficamente. Por exemplo, ao geocodificar um ponto da cidade de Chicago, o ponto geocodificado pode ser rotulado como um endereço, como a cidade (Chicago), como o estado (Illinois) ou como o país (Estados Unidos). Todas essas opções são endereços para o geocodificador. O geocodificador inverso retorna todos esses resultados.

Ele pode corresponder entidades políticas (países, províncias, cidades e bairros), endereços e códigos postais.

A lista completa de endereços retornados pela consulta anterior é mostrada abaixo.

results[0].formatted_address: "275-291 Bedford Ave, Brooklyn, NY 11211, USA",
results[1].formatted_address: "Williamsburg, NY, USA",
results[2].formatted_address: "New York 11211, USA",
results[3].formatted_address: "Kings, New York, USA",
results[4].formatted_address: "Brooklyn, New York, USA",
results[5].formatted_address: "New York, New York, USA",
results[6].formatted_address: "New York, USA",
results[7].formatted_address: "United States"

Os endereços são retornados na ordem de correspondência, da melhor para a pior. Geralmente, o endereço mais exato é o resultado mais proeminente, como neste caso. Observe que retornamos diferentes tipos de endereço, desde o endereço mais específico até entidades políticas menos específicas, como bairros, cidades, estados, países etc. Para corresponder um endereço mais genérico, examine o campo results[].types.

Observação: a geocodificação inversa não é uma ciência exata. O geocodificador tentará encontrar a localização endereçável mais próxima dentro de uma determinada tolerância.

Geocodificação inversa por ID de local

O exemplo a seguir aceita um ID de local, encontra o endereço correspondente e centraliza o mapa nessa localização. Além disso, exibe uma janela de informações mostrando o endereço formatado do local relevante:

// Initialize the map.
function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 8,
    center: {lat: 40.72, lng: -73.96}
  });
  var geocoder = new google.maps.Geocoder;
  var infowindow = new google.maps.InfoWindow;

  document.getElementById('submit').addEventListener('click', function() {
    geocodePlaceId(geocoder, map, infowindow);
  });
}

// This function is called when the user clicks the UI button requesting
// a reverse geocode.
function geocodePlaceId(geocoder, map, infowindow) {
  var placeId = document.getElementById('place-id').value;
  geocoder.geocode({'placeId': placeId}, function(results, status) {
    if (status === google.maps.GeocoderStatus.OK) {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);
        var marker = new google.maps.Marker({
          map: map,
          position: results[0].geometry.location
        });
        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert('No results found');
      }
    } else {
      window.alert('Geocoder failed due to: ' + status);
    }
  });
}

Ver o exemplo (geocoding-place-id.html).

Direcionamento de porta de visualização

Também é possível instruir o serviço Geocoding a dar preferência a resultados em uma determinada porta de visualização (expressa como uma caixa limitadora). Isso é feito definindo o parâmetro bounds no literal de objeto GeocoderRequest para definir os limites dessa porta de visualização. Observe que o direcionamento somente prioriza resultados dentro dos limites. Se resultados mais relevantes existirem fora desses limites, eles poderão ser incluídos.

Por exemplo, um código geográfico para "Winnetka" geralmente retorna este subúrbio de Chicago:

{
  "types":["locality","political"],
  "formatted_address":"Winnetka, IL, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["locality","political"]
  },{
    "long_name":"Illinois",
    "short_name":"IL",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location":[ -87.7417070, 42.1083080],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJW8Va5TnED4gRY91Ng47qy3Q"
}

Entretanto, a adição de um parâmetro bounds definindo uma caixa limitadora para San Fernando Valley em Los Angeles resulta no retorno de um bairro chamado "Winnetka" nessa localização:

{
  "types":["sublocality","political"],
  "formatted_address":"Winnetka, California, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["sublocality","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_3","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "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"]
  }],
  "geometry":{
    "location": [34.213171,-118.571022],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ"
}

Direcionamento de código da região

Também é possível configurar o serviço Geocoding para retornar resultados direcionados a uma região específica usando explicitamente o parâmetro region. Esse parâmetro aceita um código de região especificado como uma subtag de idioma region da IANA. Na maioria das vezes, essas tags são mapeadas diretamente para valores de dois caracteres de ccTLD familiares ("domínio de nível superior") como "uk" em "co.uk", por exemplo. Em alguns casos, a tag region também permite códigos ISO-3166-1, que ocasionalmente diferem dos valores de ccTLD ("GB" para "Grã-Bretanha", por exemplo).

As solicitações de geocodificação podem ser enviadas para qualquer domínio no qual o aplicativo principal do Google Maps ofereça geocodificação. Observe que o direcionamento somente prioriza resultados de um domínio específico. Se resultados mais relevantes existirem fora desse domínio, eles poderão ser incluídos.

Por exemplo, um código geográfico para "Toledo" retorna esse resultado, já que o domínio padrão do serviço Geocoding é definido como Estados Unidos:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, OH, USA",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Ohio",
    "short_name":"OH",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "place_id": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw"
}

Um código geográfico de "Toledo" com o campo region definido como 'es' (Espanha) retorna a cidade espanhola:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, España",
  "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":"Castilla-La Mancha",
    "short_name":"CM",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"España",
    "short_name":"ES",
    "types":["country","political"]
  }],
  "place_id": "ChIJ8f21C60Lag0R_q11auhbf8Y"
}

Filtragem de componentes

Também é possível configurar o serviço Geocoding para retornar resultados de endereço restritos a uma área específica. Especifique a restrição usando o parâmetro componentRestrictions. Um filtro consiste em um ou mais destes itens: route, locality, administrativeArea, postalCode ou country. Somente os resultados correspondentes a todos os filtros são retornados. 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.

O exemplo de função a seguir demonstra o uso do parâmetro componentRestrictions para filtrar por country e postalCode:

function codeAddress() {
geocoder.geocode({
  componentRestrictions: {
    country: 'AU',
    postalCode: '2000'
  }
}, function(results, status) {
  if (status == google.maps.GeocoderStatus.OK) {
    map.setCenter(results[0].geometry.location);
    var marker = new google.maps.Marker({
      map: map,
      position: results[0].geometry.location
    });
  } else {
    window.alert('Geocode was not successful for the following reason: ' + status);
  }
});
}