API de Geolocalização do JavaScript

A API de Geolocalização permite que uma página web pergunte ao navegador onde está o dispositivo do usuário. Com a permissão do usuário, você obtém coordenadas (latitude e longitude) que pode usar para exibir resultados próximos, centralizar um mapa ou marcar conteúdo com uma localização. Este guia abrange toda a API: como verificar o suporte, ler a posição atual uma vez, monitorar alterações de posição ao longo do tempo, as opções que controlam precisão e temporização, e como tratar erros e permissões corretamente.

Introdução à API de Geolocalização

A API de Geolocalização faz parte do ambiente do navegador (o objeto navigator), não da linguagem JavaScript em si. Se você não conhece a diferença entre recursos de linguagem e APIs fornecidas pelo navegador, consulte o capítulo Ambiente do navegador, especificações para obter contexto.

A API expõe três métodos em navigator.geolocation:

• getCurrentPosition() — obtém a posição uma vez.
• watchPosition() — obtém a posição repetidamente conforme o dispositivo se move.
• clearWatch() — interrompe uma assinatura de watchPosition().

Dois requisitos que você não pode ignorar

1. Contexto seguro. Os navegadores só expõem a geolocalização em páginas servidas via HTTPS (ou localhost durante o desenvolvimento). Em uma página http:// comum, navigator.geolocation pode estar ausente ou todas as chamadas falham. Esta é uma medida de privacidade e segurança.
2. Permissão do usuário. O navegador exibe um prompt na primeira vez que uma página solicita localização. Nada acontece até o usuário clicar em Permitir. Se ele escolher Bloquear, seu callback de erro é disparado com o código PERMISSION_DENIED.

Verificando a disponibilidade da API

Sempre faça a detecção de recursos antes de usar a API, pois navegadores antigos e páginas inseguras podem não fornecê-la.

Obtendo a posição atual

Para buscar a localização do dispositivo uma única vez, chame getCurrentPosition(success, error, options). Apenas o primeiro argumento é obrigatório.

const options = {
  // Ask for the highest-accuracy position available (e.g. GPS on mobile).
  enableHighAccuracy: true,
  // Give up after 5 seconds if no position is returned.
  timeout: 5000,
  // Never use a cached position; always fetch a fresh one.
  maximumAge: 0
};

function success(position) {
  const { latitude, longitude, accuracy } = position.coords;
  console.log(`Latitude: ${latitude}, Longitude: ${longitude}`);
  console.log(`Accurate to within ${accuracy} meters`);
}

function error(err) {
  console.error(`Error (${err.code}): ${err.message}`);
}

navigator.geolocation.getCurrentPosition(success, error, options);

O objeto de posição

O callback de sucesso recebe um objeto GeolocationPosition com dois campos:

• position.timestamp — quando a leitura foi feita (milissegundos desde a época).
• position.coords — um objeto GeolocationCoordinates contendo:

Os campos heading e speed geralmente só são preenchidos em dispositivos que estão realmente em movimento e possuem os sensores adequados.

O objeto de opções

As três opções são opcionais. Escolha-as com base no seu caso de uso:

Um trade-off comum: defina enableHighAccuracy: false e um maximumAge diferente de zero quando um resultado aproximado e rápido for suficiente (como "lojas próximas"); use enableHighAccuracy: true com maximumAge: 0 para navegação passo a passo.

Tratando erros

Quando uma solicitação falha, o callback de erro recebe um GeolocationPositionError. Sua propriedade code informa exatamente o que deu errado:

function error(err) {
  switch (err.code) {
    case err.PERMISSION_DENIED:      // 1
      console.error("User denied the request for location.");
      break;
    case err.POSITION_UNAVAILABLE:   // 2
      console.error("Location information is unavailable.");
      break;
    case err.TIMEOUT:                // 3
      console.error("The request to get location timed out.");
      break;
    default:
      console.error(`An unknown error occurred: ${err.message}`);
  }
}

• PERMISSION_DENIED (1) — o usuário bloqueou o acesso à localização, ou a página não está em um contexto seguro.
• POSITION_UNAVAILABLE (2) — o dispositivo não conseguiu determinar sua localização (sem sinal GPS/Wi-Fi, etc.).
• TIMEOUT (3) — nenhuma posição foi obtida dentro do timeout definido.

Verificando a permissão antecipadamente

Você pode inspecionar a permissão de geolocalização sem acionar um prompt usando a Permissions API. Isso é útil para personalizar sua interface (por exemplo, ocultar um botão "Encontrar-me" se o acesso já estiver bloqueado).

navigator.permissions.query({ name: "geolocation" }).then((result) => {
  // result.state is "granted", "prompt", or "denied"
  console.log(`Geolocation permission: ${result.state}`);
});

Monitoramento contínuo de posição

Para rastreamento em tempo real, watchPosition() chama seu callback de sucesso toda vez que a posição do dispositivo muda. Ele retorna um ID de observação numérico que você passa para clearWatch() para interromper o rastreamento — não limpá-lo mantém a localização ativa e consome a bateria.

const watchID = navigator.geolocation.watchPosition(success, error, options);
// success() now fires every time the position updates.

// Later, when tracking is no longer needed:
navigator.geolocation.clearWatch(watchID);

Se o seu rastreamento depende da tela girando entre retrato e paisagem, a API de Orientação de Tela combina bem com geolocalização em aplicativos de mapas.

Um exemplo completo: exibir sua localização em um mapa

Este exemplo usa a API de Geolocalização para obter suas coordenadas e a biblioteca Leaflet.js para renderizá-las em uma camada do OpenStreetMap.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Your Location on a Map</title>
    <link
      rel="stylesheet"
      href="https://unpkg.com/[email protected]/dist/leaflet.css"
    />
  </head>
  <body>
    <h1>Your Location on a Map</h1>
    <div id="map" style="height: 400px"></div>
    <script src="https://unpkg.com/[email protected]/dist/leaflet.js"></script>
    <script>
      document.addEventListener("DOMContentLoaded", function () {
        if (navigator.geolocation) {
          navigator.geolocation.getCurrentPosition(function (position) {
            const lat = position.coords.latitude;
            const lon = position.coords.longitude;

            const map = L.map("map").setView([lat, lon], 13);
            L.tileLayer("https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png", {
              maxZoom: 19,
              attribution: "© OpenStreetMap contributors",
            }).addTo(map);

            L.marker([lat, lon])
              .addTo(map)
              .bindPopup("You are here!")
              .openPopup();
          });
        } else {
          document.getElementById("map").textContent =
            "Geolocation is not supported by your browser.";
        }
      });
    </script>
  </body>
</html>

Ao carregar a página, ela solicitará imediatamente sua localização e exibirá um marcador no mapa na sua posição com um popup dizendo "You are here!" Essa representação visual ajuda você a entender como os sites podem interagir com dados geográficos para melhorar a experiência do usuário.

Boas práticas

• Sempre faça detecção de recursos e sirva via HTTPS, ou todas as chamadas falharão.
• Solicite localização apenas quando o usuário espera isso — por exemplo, depois que ele clicar em um botão "Encontrar-me" — para que o prompt de permissão tenha contexto claro.
• Trate todos os códigos de erro e exiba um fallback útil (como uma pesquisa de localização manual) quando a permissão for negada.
• Chame clearWatch() assim que não precisar mais de atualizações contínuas para economizar bateria.
• Escolha as opções deliberadamente: alta precisão para navegação, um maximumAge diferente de zero para buscas rápidas de "próximos a mim".

Conclusão

A API de Geolocalização oferece aos aplicativos web uma forma consciente de privacidade para ler a localização do usuário por meio de três métodos: getCurrentPosition() para uma leitura única, watchPosition() para rastreamento ao vivo e clearWatch() para interromper. Combinada com escolhas criteriosas de opções e tratamento adequado de erros, ela possibilita mapas, pesquisas locais e outros recursos com reconhecimento de localização. Para avançar com APIs de navegador relacionadas, explore a API de Orientação de Tela e o capítulo Ambiente do navegador, especificações.

Prática