Versão Impressão

HTML5

Um guia de referência para os desenvolvedores web.

24. Geolocation API

Métodos de Geolocalização

Há três populares maneiras de um agente de usuário descobrir sua posição no globo:

Geolocalização IP
É o método usado pela maioria dos navegadores web em computadores. Através de consultas whois e serviços de localização de IP, vai determinar a cidade ou região em que você está.
Triangulação GPRS
Dispositivos conectados a uma rede de celulares e sem um GPS, ou com o GPS desligado, podem determinar sua posição pela triângulação das antenas GPRS próximas. É bem mais preciso que o método baseado em IP, vai mostrar em que parte do bairro você está.
GPS
É o método mais preciso. Em condições ideais, a margem de erro é de apenas 5 metros.

Embora essas sejam as três maneiras mais populares de se resolver o problema, podem não ser as únicas. Alguns agentes de usuário podem usar uma combinação desses métodos, ou mesmo um novo método que venha a ser inventado. Por isso, a Geolocation API é agnóstica em relação ao método usado. Há apenas uma maneira de ligar e desligar o "modo de alta precisão", o que vai ter significado diferente em cada agente de usuário.

Para obter a posição do usuário, basta executar o script:

navigator.geolocation.getCurrentPosition(showpos)

Onde showpos é uma função callback, que vai receber um objeto de posicionamento. Veja um exemplo:

function showpos(position){
  lat=position.coords.latitude
  lon=position.coords.longitude
  alert('Your position: '+lat+','+lon)
}

Claro, você pode fazer o que quiser, abrir um mapa, submeter a posição via Ajax, enviar os dados para um webservice, etc.

O método getCurrentPosition recebe dois outros parâmetros. O primeiro é uma função para tratamento de erro. O segundo, um objeto de configuração.

Tratando erros

Quando o script tenta acessar o posicionamento, o navegador exibe uma barra como esta:

Barra de confirmação de Geolocalização

O usuário pode então escolher se deseja ou não compartilhar sua posição com o site. Além de o usuário poder dizer não, muita coisa pode dar errado na hora de obter a geolocalização. Para tratar isso, você pode passar o segundo parâmetro a getCurrentPosition:

navigator.geolocation.getCurrentPosition(showpos,erropos)

Caso algo dê errado, a função erropos vai receber um objeto PositionError, que tem o atributo code, que pode ter um dos seguintes valores:

1 - Permissão negada
O usuário clicou em "não compartilhar".
2 - Posição indisponível
O agente de usuário está desconectado, os satélites de GPS não puderam ser alcançados ou algum erro semelhante.
3 - Timeout
Tempo esgotado ao obter uma posição. Você pode definir o tempo máximo ao chamar getCurrentPosition.
0 - Erro desconhecido
Alguma outra coisa impediu o agente de usuário de obter uma posição.

Não trate a resposta do usuário como um erro

Em sua função de tratamento de erro, se obtiver o código de erro 1, por favor, não incomode o usuário com mensagens de erro. Ele escolheu não compartilhar sua posição com o site. Talvez a melhor atitude seja não fazer nada nesse momento.

O objeto de configuração

O terceiro parâmetro de getCurrentPosition é um objeto de configuração, que pode ter as seguintes propriedades:

enableHighAccuracy
Se true, liga o modo de alta precisão. Num celular isso pode instruir o navegador, por exemplo, a usar o GPS ao invés da triangulação GPRS
timeout
O tempo em milissegundos que o agente do usuário vai esperar pela posição antes de disparar um erro tipo 3.
maximumAge
O tempo, em milissegundos, que o navegador pode cachear a posição.

watchPosition

Se o que você deseja é rastrear a posição do usuário continuamente, pode usar, ao invés de getCurrentPosition, o método watchPosition. Ele tem a mesma assinatura de getCurrentPosition:

w=navigator.geolocation.watchPosition(showpos,erropos)

A diferença é que a função showpos será chamada toda vez que a posição do usuário mudar. O valor de retorno é um número, que pode ser usado posteriormente para cancelar o watcher:

navigator.geolocation.clearWatch(w)