Aprende Google Maps Geocoding através de exemplos O Serviço Geocoding, ou serviço de geocodificação, é um processo integrado na API Javascript v3 do Google Maps que permite transformar um endereço nas respectivas coordenadas geográficas.

Aprende Google Maps Geocoding através de exemplos

por quinta-feira, 25 de junho de 2015
geocoding

O Serviço Geocoding, ou serviço de geocodificação, é um processo integrado na API Javascript v3 do Google Maps que permite transformar um endereço nas respectivas coordenadas geográficas.
O geocoder do google maps está incluído na API JavaScript v3 e por isso não necessitas de definir qualquer parâmetro adicional no URL de chamada da API. Uma vez que este serviço já está incluído na API também não há custos para além dos preços aplicados à utilização da própria API.
No entanto deves ter em conta que o processo de geocoding tem limites de utilização.

Limites de utilização do geocoding

Após o carregamento da API podes realizar alguns pedidos de geocodificação (menos de 10) mas depois o serviço fica limitado a pouco mais de 1 pedido por segundo. Se ultrapassares estes limites a API emite um alerta ao utilizador. Para evitar que este alerta seja visível pelo utilizador e no caso de necessitares de efetuar vários pedidos consecutivos ao serviço de geocoding, deves programar a chamada ao geocoder com setTimeout superior a 750 milisegundos.

Onde podes utilizar o serviço geocoding

Com o serviço de geocoding podes adicionar um marcador no mapa ou centrar o mapa numa determinada região.

Imagina que estás a criar um mapa para mostrar os pontos de interesse do teu país. Através do geocoder podes permitir que o utilizador efectue uma pesquisa por localidade ou por nome de uma rua, movendo o mapa automaticamente para a região pretendida.

Da mesma forma é possível adicionar um novo marcador no mapa.

  1. O utilizador indica a morada desejada numa caixa de texto.
  2. Recorrendo ao serviço de geocoding o endereço é convertido para as suas coordenadas geográficas.
  3. Automaticamente o mapa é centrado na área desejada.
  4. Um novo marcador é adicionado no respectivo local.

O serviço de geocoding pode ainda ser utilizado para a conversão de endereços em massa. Ou seja, podes converter vários endereços nas respectivas coordenadas geográficas para incluir numa base de dados. No entanto esta funcionalidade está para além do âmbito deste artigo.

Neste tutorial eu vou explicar como posicionar o mapa numa determinada região e adicionar um marcador na localização pretendida através da indicação de um endereço.

Antes de iniciar o tutorial vê uma demonstração do mapa ou faz o download do código necessário para seguir este exemplo.

DEMO DOWNLOAD

Estrutura do HTML necessário à aplicação.

Este exemplo é composto por um mapa, uma caixa de texto e um botão. A caixa de texto serve para receber o endereço a pesquisar e o botão inicia o processo geocoder.

Primeiro é necessário preparar os ficheiros HTML, CSS e JavaScript com as opções básicas para incluir um mapa com a API do Google Maps na página web.

HTML /index.htmlmarnoto.com
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <link rel="stylesheet" type="text/css" href="css/style.css">
    <script type="text/javascript" src="https://maps.googleapis.com/maps/api/js?sensor=false"></script>
    <script type="text/javascript" src="js/map.js"></script>
  </head>
  <body> 
    <div id="map-canvas"></div>
  </body>
</html>
CSS /style.cssmarnoto.com
html {
  height: 100%;
}
body {
  height: 100%;
  margin: 0;
  padding: 0;
}
#map-canvas {
   margin: 0;
   padding: 0;
   height: 400px;
   max-width: none;
}
#map-canvas img {
   max-width: none !important;
}
JS /map.jsmarnoto.com
var map;
var marker;

function initialize() {
  var mapOptions = {
    center: new google.maps.LatLng(40.680898,-8.684059),
    zoom: 11,
    mapTypeId: google.maps.MapTypeId.ROADMAP
  };
  var map = new google.maps.Map(document.getElementById("map-canvas"), mapOptions);
}
google.maps.event.addDomListener(window, "load", initialize);

De seguida incluir a caixa de texto que vai receber o endereço e um botão.

HTML /index.htmlmarnoto.com
...
  <body>
    <div>
       Indique um endereço <input type="text" id="address-input">
       <button onclick="searchAddress();">Pesquisar</button>
    </div>   
    <div id="map-canvas"></div>
  </body>
</html>

Presumo que já tenhas todos os elementos HTML preparados, vamos prosseguir para a fase mais importante.

Como iniciar o processo Geocoder

O serviço google maps geocoding é realizado com recurso ao método google.maps.Geocoder() e não é necessário incluir qualquer chamada no url da API. O método Geocoder já vem incluído na API básica.

Neste caso eu vou inserir o serviço de geocoding numa função específica fora da função normalmente designada de initialize(). Eu vou designar esta função de searchAddress() mas tu podes atribuir outro nome qualquer.

JS /map.jsmarnoto.com
function searchAddress() {

}

Dentro da função searchAddress() começas por criar uma nova variável que vai obter o valor da caixa de texto onde é indicado o endereço a converter.

JS /map.jsmarnoto.com
function searchAddress() {

  var addressInput = document.getElementById('address-input').value;

}

Seguidamente é definida outra variável com o nome geocoder para iniciar uma nova instância do método google.maps.Geocoder().

JS /map.jsmarnoto.com
function searchAddress() {

  var addressInput = document.getElementById('address-input').value;

  var geocoder = new google.maps.Geocoder();
}

O Geocoder() possui um método denominado de geocode(). É através deste método que vais efectuar o pedido de geocodificação.

Este método aceita dois parâmetros. No primeiro parâmetro, denominado de GeocodeRequest, defines um objecto com a propriedade address: cujo valor é igual ao valor da caixa de texto address-input guardado na variável addressInput. {address: addressInput}

No segundo parâmetro defines uma função callback que vai processar os resultados obtidos. function(results, status) {

JS /map.jsmarnoto.com
function searchAddress() {

  var addressInput = document.getElementById('address-input').value;

  var geocoder = new google.maps.Geocoder();

  geocoder.geocode({address: addressInput}, function(results, status) {

  }
}

O objecto GeocodeRequest (primeiro parâmetro) também aceita a propriedade {location: LatLng}. Ao utilizares a propriedade “location” estarás a indicar ao Serviço Geocoding que queres obter uma morada através das coordenadas LatLng. A este processo dá-se o nome de Reverse Geocoding.

Neste exemplo estás a enviar a propriedade address e é assim que o serviço de geocoding do google maps sabe qual o procedimento a tomar. Que neste caso é converter um endereço nas coordenadas latitude e longitude.

geocoder.geocode({address: addressInput}, ...

A função callback definida no segundo parâmetro também aceita dois parâmetros. O primeiro parâmetro results recebe o resultado ou resultados, podem ser mais do que um. Com o segundo parâmetro status é efetuada a verificação do sucesso do serviço de geocoding.

Se o geocoder foi bem sucedido, então podes passar ao tratamento da informação recebida através do parâmetro results. Se o geocoder não foi bem sucedido, então procedes à verificação das suas causas. Mediante a resposta obtida no parâmetro status vais tentar resolver o problema ou transmites uma resposta ao utilizador para tomar determinado procedimento.

Este processo é bem mais fácil de compreender com um exemplo prático.
A primeira acção a tomar é a verificação do status devolvido. if (status == google.maps.GeocoderStatus.OK) {

JS /map.jsmarnoto.com
function searchAddress() {

  var addressInput = document.getElementById('address-input').value;

  var geocoder = new google.maps.Geocoder();

  geocoder.geocode({address: addressInput}, function(results, status) {

    if (status == google.maps.GeocoderStatus.OK) {

    }
  }
}

Se o valor do parâmetro status é igual a google.maps.GeocoderStatus.OK isto quer dizer que o processo de geocodificação foi bem sucedido e devolveu um ou mais resultados. GeocoderStatus pode devolver outros valores mas para já vais acreditar que correu tudo bem e podes continuar com o tratamento da informação recebida.

Uma vez que o Geocoder pode devolver um ou mais resultados então a variável results é do tipo array. Mas acreditando que o serviço de geocode acertou no resultado que tu pretendes então vais trabalhar com o resultado do primeiro indice results[0].

A informação devolvida pelo geocoder é composta por um objecto denominado de GeocoderResults. Uma das propriedades deste objecto é outro objecto denominado de geometry. Uma das propriedades do objecto geometry é location e o seu valor é LatLng. Assim, podes definir o resultado da seguinte forma: results[0]: { geometry: { location: LatLng } }
Ou seja, para obteres as coordenadas LatLng, basta fazer isto: results[0].geometry.location

Uma vez que este valor já está no formato de latlng não precisas de o transformar com google.maps.Latlng. Basta inserir este valor directamente no processo que queres utilizar. Neste caso vais centrar o mapa na localização recebida pelo geocode, com a função da API map.setCenter(results[0].geometry.location) e passas o valor de latlng como único parâmetro.

Adicionalmente podes redefinir o valor do zoom para reposicionar o mapa e dar destaque à região da morada.

JS /map.jsmarnoto.com
function searchAddress() {

  var addressInput = document.getElementById('address-input').value;

  var geocoder = new google.maps.Geocoder();

  geocoder.geocode({address: addressInput}, function(results, status) {

    if (status == google.maps.GeocoderStatus.OK) {

      map.setCenter(results[0].geometry.location);

      map.setZoom(17);
    }
  }
}

Adicionar um marcador com google maps geocoder

Adicionar um marcador no mapa com o serviço Geocoding do Google Maps API através da indicação de um endereço é realizado da mesma forma anteriormente descrita. Com a adição de uma nova função que cria o marcador para adicionar no mapa e adicionalmente podes centrar o mapa na posição do marcador e ou aumentar o zoom. Seguindo o exemplo anteriormente:

JS /map.jsmarnoto.com
function searchAddress() {

  var addressInput = document.getElementById('address-input').value;

  var geocoder = new google.maps.Geocoder();

  geocoder.geocode({address: addressInput}, function(results, status) {

    if (status == google.maps.GeocoderStatus.OK) {

      var myResult = results[0].geometry.location; // referência ao valor LatLng

      createMarker(myResult); // adicionar chamada à função que adiciona o marcador

      map.setCenter(myResult);

      map.setZoom(17);

    }
  });
}

function createMarker(latlng) {

   // Se o utilizador efetuar outra pesquisa é necessário limpar a variável marker
   if(marker != undefined && marker != ''){
    marker.setMap(null);
    marker = '';
   }

   marker = new google.maps.Marker({
      map: map,
      position: latlng
   });

}

Se o geocode não foi bem sucedido

Se o geocode não foi bem sucedido a função devolve uma mensagem de alerta com a mensagem de erro devolvida pelo parâmetro “status”.

JS /map.jsmarnoto.com
...

  if (status == google.maps.GeocoderStatus.OK) {

    var myResult = results[0].geometry.location; // referência ao valor LatLng

    createMarker(myResult); // adicionar chamada à função que adiciona o marcador

    map.setCenter(myResult);

    map.setZoom(17);

  } else { // se o valor de status é diferente de "google.maps.GeocoderStatus.OK"

    // mensagem de erro
    alert("O Geocode não foi bem sucedido pela seguinte razão: " + status);

  }

...

O código demonstrado neste tutorial é o mínimo necessário para a inclusão do serviço de geocoding numa aplicação. A partir daqui podes passar para o estudo das respostas possíveis das propriedades "status" e "results".

Ver exemplo do mapa.

Todas as dúvidas ou comentários são bem-vindos. Por favor, utiliza a secção de comentários para que todos partilhem da informação.

Download dos ficheiros necessários para este exemplo

Miguel Marnoto

A minha especialização no Google Maps e na sua API JavaScript v3 é uma consequência do gosto pelos mapas e o reconhecimento da importância que o serviço Google Maps tem hoje no dia-a-dia das pessoas.

5 comentários para ''Aprende Google Maps Geocoding através de exemplos"

COMENTAR
  1. Me ajudou bastante. Valeu pelo post!

    ResponderEliminar
  2. show.. como eu faria pra já fazer ele pesquisar um endereço no onload do html? no meu caso vou colocar oendereço fixo na variavel address e não pegar do text.. agradeço se puder dar uma dica.

    ResponderEliminar
  3. muito obrigado, nenhum outro tutorial conseguiu exemplificar de forma simples e direta

    ResponderEliminar