A API Geolocation do W3C padroniza como os navegadores modernos consultam os sensores de localização em smartphones, computadores e tablets.
Disponível por meio do objeto global navigator.geolocation, essa interface permite que páginas web solicitem coordenadas com o consentimento explícito do usuário. Neste guia, apresentamos detalhes técnicos e código pronto para produção.
Inspecione a Resposta Geolocation do seu Navegador
Dispare uma chamada a navigator.geolocation para conferir os dados de coordenadas, altitude, velocidade, rumo e timestamp ao vivo.
1. Arquitetura Básica e Métodos da API
A especificação Geolocation do W3C organiza-se em três funções principais:
navigator.geolocation.getCurrentPosition(success, error, options)
Solicita uma leitura única da posição atual do usuário. Retorna um objeto GeolocationPosition em caso de sucesso ou GeolocationPositionError em falhas.
navigator.geolocation.watchPosition(success, error, options)
Registra uma função ouvinte que é chamada sempre que o dispositivo muda de posição. Retorna um watchId para monitoramento contínuo.
navigator.geolocation.clearWatch(watchId)
Encerra o monitoramento iniciado por watchPosition(), preservando a bateria e desligando o rastreamento por sensores.
2. Implementação em JavaScript Pronta para Produção
Veja um exemplo completo com controle de timeout, fallback e alta precisão configurada:
// Check browser support
if ('geolocation' in navigator) {
const options = {
enableHighAccuracy: true, // Request GPS hardware rather than IP lookup
timeout: 10000, // Maximum wait time of 10 seconds
maximumAge: 0 // Do not return cached coordinates
};
function successCallback(position) {
const { latitude, longitude, accuracy, altitude, heading, speed } = position.coords;
console.log(`Latitude: ${latitude}, Longitude: ${longitude}`);
console.log(`Accuracy radius: ${accuracy} meters`);
}
function errorCallback(error) {
switch(error.code) {
case error.PERMISSION_DENIED:
console.error("User denied Geolocation permission.");
break;
case error.POSITION_UNAVAILABLE:
console.error("Location information is unavailable (weak GPS/Wi-Fi signal).");
break;
case error.TIMEOUT:
console.error("The request to get user location timed out.");
break;
}
}
navigator.geolocation.getCurrentPosition(successCallback, errorCallback, options);
} else {
console.warn("Geolocation API is not supported in this browser.");
}3. Opções de Configuração: PositionOptions
| Propriedade | Tipo | Padrão | Comportamento e Impacto Técnico |
|---|---|---|---|
enableHighAccuracy | Boolean | false | Se true, orienta o navegador a ligar o chip GNSS/GPS (< 3-5 m). Se false, utiliza triangulação Wi-Fi ou celular econômica em energia. |
timeout | Positive integer (ms) | Infinity | Tempo limite em milissegundos antes de retornar erro TIMEOUT. Recomendado: de 8.000 a 12.000 ms. |
maximumAge | Positive integer (ms) | 0 | Tempo máximo de armazenamento em cache tolerado. 0 força a coleta de uma nova coordenada de satélite ou Wi-Fi. |
4. Diretivas de Segurança e Políticas de Acesso
- Contexto Seguro Obrigatório (HTTPS): Desde o Chrome 50 e iOS 10, a geolocalização é bloqueada em conexões HTTP simples.
- Gesto do Usuário Recomendado: Acionar a solicitação a partir do clique em um botão ('Buscar Localização') eleva a taxa de aprovação.
- Declaração em Iframes: Ao integrar ferramentas em <iframe>, inclua a diretiva allow='geolocation'.
Converta os Graus Decimais da API
Converta com facilidade as saídas decimais do navegador para Graus Minutos Segundos (GMS) ou Universal Transverse Mercator (UTM).