Geolocation API - JavaScript

A API de Geolocalização permite que scripts em JavaScript acessem informações sobre a localização geográfica do usuário. Para utilizá-la, o objeto navigator possui a propriedade geolocation, que é uma instância do tipo Geolocation. O método principal para obter a localização é o getCurrentPosition(), que aceita até três parâmetros:

getCurrentPosition(success);
getCurrentPosition(success, error);
getCurrentPosition(success, error, options);

success: uma função executada quando as coordenadas do usuário são obtidas com sucesso.
error: uma função executada em caso de erro ao tentar obter a localização.
options: parâmetros opcionais de configuração.

Como a localização é obtida de forma assíncrona, o parâmetro success deve ser uma função de callback chamada ao término da operação. Essa função recebe como argumento um objeto GeolocationPosition, cujo atributo coords (do tipo GeolocationCoordinates) contém os dados de localização do usuário. Os atributos principais de coords incluem:

latitude: a latitude em graus.
longitude: a longitude em graus.
altitude: altura em metros acima do nível do mar.
speed: velocidade atual do usuário (em metros por segundo), se aplicável.
accuracy: precisão da latitude e longitude em metros.
altitudeAccuracy: precisão da altitude em metros.
heading: direção em que o dispositivo está apontando. O valor é representado em graus (0° corresponde ao norte, e os valores aumentam no sentido horário). Se o dispositivo estiver parado ou não puder determinar a direção, esse valor será NaN ou null.

A seguir, um exemplo de como obter os dados de localização:

function success(position) {
    console.log("Latitude: ", position.coords.latitude);
    console.log("Longitude: ", position.coords.longitude);
    console.log("Altitude: ", position.coords.altitude);
    console.log("Velocidade: ", position.coords.speed);
    console.log("Precisão: ", position.coords.accuracy);
    console.log("Direção: ", position.coords.heading);
}
navigator.geolocation.getCurrentPosition(success);

Por motivos de segurança, os navegadores exigem que o usuário conceda permissão explícita para acessar sua localização. Quando o método geolocation.getCurrentPosition() é chamado, o navegador exibe um aviso solicitando essa permissão.

Aviso de permissão para acessar a localização do usuário

Tratamento de Erros

Se o usuário negar o acesso à localização ou ocorrer outro problema, a função error, passada como segundo parâmetro, será chamada. Ela recebe um objeto do tipo GeolocationPositionError, que possui os seguintes atributos principais:

message: uma descrição legível do erro.
code: um código de erro que pode assumir os seguintes valores:
- 1 (PERMISSION_DENIED): o usuário negou a permissão para acessar a localização.
- 2 (POSITION_UNAVAILABLE): a localização está indisponível.
- 3 (TIMEOUT): o tempo limite para obter a localização foi excedido.

Exemplo de implementação com tratamento de erros:

function successHandler(position) {
    console.log("Latitude: ", position.coords.latitude);
    console.log("Longitude: ", position.coords.longitude);
}
function errorHandler(error) {
    console.log("Erro: ", error.message);
    console.log("Código do erro: ", error.code);
}
navigator.geolocation.getCurrentPosition(successHandler, errorHandler);

Se a permissão for negada, o console exibirá algo como:

Erro:  User denied Geolocation
Código do erro:  1

Monitoramento Contínuo de Posição

O método watchPosition() registra uma função de callback que será chamada automaticamente toda vez que a posição do dispositivo mudar. Ele aceita os mesmos parâmetros que o método getCurrentPosition() e retorna um identificador único. Esse identificador pode ser usado no método clearWatch() para interromper o monitoramento.

Abaixo está um exemplo prático que monitora continuamente a posição do dispositivo até que o monitoramento seja explicitamente interrompido:

<!DOCTYPE html>
<html lang="pt-br">
<head>
    <meta charset="utf-8" />
    <title>Exemplo de Geolocalização</title>
</head>
<body>
    <button id="btn">Parar Monitoramento</button>
    <script>
        function successHandler(position) {
            console.log("Latitude: ", position.coords.latitude);
            console.log("Longitude: ", position.coords.longitude);
        }
        function errorHandler(error) {
            console.log("Erro: ", error.message);
        }

        const geolocation = navigator.geolocation;
        const watchID = geolocation.watchPosition(successHandler, errorHandler);

        document.getElementById("btn").addEventListener("click", () => geolocation.clearWatch(watchID));
    </script>
</body>
</html>

Neste exemplo, o monitoramento contínuo da posição do dispositivo é interrompido ao clicar no botão "Parar Monitoramento". Enquanto o monitoramento estiver ativo, a cada mudança na posição do dispositivo, a função successHandler será chamada automaticamente com os novos dados de localização.