HTML5 e GeoLocalização com a API do Google Maps

Neste primeiro post eu irei mostrar como é possível capturar as informações de localização utilizando HTML5.

Antes de mais nada, você deve possuir uma conta no Google e acessar o link abaixo para receber a sua chave para acesso à API do Google Maps:



http://code.google.com/intl/pt-BR/apis/maps/signup.html


Ao acessar o site acima, você deve concordar com os termos e condições do Google, digitar o domínio onde você irá utlizar a API e clicar em “Gerar chave API” para obter a chave.

Com a chave em mãos, o passo seguinte será colocar na tag header o script abaixo:

<script src="http://maps.google.com/maps?file=api&amp;v=2.x&amp;key=[A sua KEY da API do Google Maps]" type="text/javascript"></script>


Em seguida, também na tag header, o script abaixo:




<script type="text/javascript"> $(document).ready(function() {
//Verifica se o Navegador tem suporte para Geolocalização
if(navigator.geolocation){
//Retorna as informações ou erro navigator.geolocation.getCurrentPosition( function(position){ var lat = position.coords.latitude; var lon = position.coords.longitude; // Iniciando o GeoCoder var geocoder = new GClientGeocoder(); geocoder.getLocations("("+lat+','+lon+")",localizacao); function localizacao(retorno){ if (!retorno || retorno.Status.code != 200) { //Tratar o retorno.Status.code aqui } else { place = retorno.Placemark[0]; alert(place.address); } } },


//Em caso de erro function (error) { switch(error.code) { case error.TIMEOUT: //Erro de tempo de espera case error.POSITION_UNAVAILABLE: //Erro de posição não encontrada ou indisponível case error.PERMISSION_DENIED: //O usuário se negou a fornecer a localização. case error.UNKNOWN_ERROR: //Erro desconhecido } } ); } else {
//Mensagem de erro para não suporte à Geolocalização.
} });
</script>

Segurança
O método navigator.geolocation.getCurrentPosition(position, error) irá perguntar ao usuário se ele deseja fornecer as informações de localização. Em caso de erro, timeout ou negação, a função onError é chamada e a resposta deverá ser dada de acordo com o erro especificado. Se preferir, não exiba mensagem de erro e permita que o usuário acesse o site sem problemas. De acordo com a documentação da API, por motivos de segurança, o usuário poderá escolher entre disponibilizar sua localização ou não.


Como extrair endereços estruturados Segundo informações da documentação da API, caso você queira acessar informações estruturadas a respeito de um endereço, GClientGeocoder também fornece um método getLocations() que retorna um objeto JSON que consiste nas informações a seguir: Status request – O tipo de solicitação. Nesse caso, sempre geocode. code – Um código de resposta (semelhante aos códigos de status HTTP) indicando se a solicitação de geocódigo obteve êxito ou não. Consulte a lista completa de códigos de status. Placemark – Vários marcadores podem ser retornados caso o geocodificador encontre várias correspondências. address – Uma versão bem formatada e com uso correto de maiúsculas do endereço. AddressDetails – O endereço formatado como xAL, ou eXtensible Address Language, um padrão internacional de formatação de endereços.   Accuracy – Um atributo que indica com que precisão foi possível geocodificar o endereço especificado. Consulte uma lista dos valores possíveis na API do Google Maps.
Point – Um ponto no espaço em 3D. coordinates – A longitude, a latitude e a altitude do endereço. Nesse caso, a altitude é sempre definida como 0. Exemplo de JSON retornado:


{ "name": "1600 Amphitheatre Parkway, Mountain View, CA, USA", "Status": { "code": 200, "request": "geocode" }, "Placemark": [ { "address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "AddressDetails": { "Country": { "CountryNameCode": "US", "AdministrativeArea": { "AdministrativeAreaName": "CA", "SubAdministrativeArea": { "SubAdministrativeAreaName": "Santa Clara", "Locality": { "LocalityName": "Mountain View", "Thoroughfare": { "ThoroughfareName": "1600 Amphitheatre Pkwy" }, "PostalCode": { "PostalCodeNumber": "94043" } } } } }, "Accuracy": 8 }, "Point": { "coordinates": [-122.083739, 37.423021, 0] } } ] }


Tratamento do retorno.Status.code (ou getLocations().Status.code)

Caso o código retornado tenha sido diferente de 200 (sucesso), você poderá tratar o erro retornado. Para saber os códigos de erro, basta acessar a documentação da API no link abaixo:

http://code.google.com/intl/pt-BR/apis/maps/documentation/javascript/v2/reference.html#GGeoStatusCode

Objeto Placemark[]

Ainda de acordo com a documentação da API do Google Maps, este objeto retorna as informações estruturadas de GeoLocalização do usuário e pode ser utilizado também em caso de várias marcações de endereço em um mapa.


Objeto Placemark[].AddressDetails.Accuracy
De acordo com testes realizados em diferentes cidades, dependendo do equipamento, do provedor de acesso e da localização em que o site é acessado, entre outros fatores, essa informação nem sempre é 100% precisa. Para saber a acurácia da informação retornada, basta acessar o objeto supracitado.

Exemplo de utilização com Google Maps

Para testar o código utilizando Google Maps, você deve realizar algumas modificações.


Antes da inicialização do GeoCoder, você deve inicializar e configurar a visualização do Google Maps, como segue:


// Iniciando o Mapa var mapa = new GMap2(document.getElementById("gmap"));
// Centralizar o mapa na localização encontrada mapa.setCenter(new GLatLng(lat,lon), 15);

Antes da verificação do retorno do Status.code, você deve remover todas as sobreposições do mapa inserindo a linha abaixo:


//Remove todas as sobreposições do mapa mapa.clearOverlays();

E, para finalizar, após preencher a variável place com o retorno do Placemark, você deve inserir o seguinte código;


point = new GLatLng(place.Point.coordinates[1], 
  place.Point.coordinates[0]);


marker = new GMarker(point); mapa.addOverlay(marker);
marker.openInfoWindowHtml('<p><strong>Coordenadas:</strong> ' + 
  place.Point.coordinates[1] + "," + 
  place.Point.coordinates[0] + '</p>' +
  '<p><strong>Logradouro:</strong> ' + 
place.AddressDetails.Country.AdministrativeArea.Locality.DependentLocality.Thoroughfare.ThoroughfareName + '</p>' +
  '<p><strong>Bairro:</strong> ' + place.AddressDetails.Country.AdministrativeArea.Locality.DependentLocality.DependentLocalityName + 
  '</p>' +'<p><strong>Cidade:</strong> ' + place.AddressDetails.Country.AdministrativeArea.Locality.LocalityName + '</p>' +
'<p><strong>País:</strong> ' +
    place.AddressDetails.Country.CountryName + '</p>');


É importante frisar que, o exemplo acima não trabalha com persistência de dados e para ver o exemplo funcionando, clique aqui.


Obrigado a todos e até o próximo post.