API de Geolocalización de JavaScript

La API de Geolocalización permite que una página web le pregunte al navegador dónde se encuentra el dispositivo del usuario. Con el permiso del usuario, se obtienen coordenadas (latitud y longitud) que pueden usarse para mostrar resultados cercanos, centrar un mapa o etiquetar contenido con una ubicación. Esta guía cubre la API completa: cómo verificar el soporte, leer la posición actual una sola vez, observar cambios de posición a lo largo del tiempo, las opciones que controlan la precisión y el tiempo, y cómo manejar errores y permisos correctamente.

Introducción a la API de Geolocalización

La API de Geolocalización forma parte del entorno del navegador (el objeto navigator), no del lenguaje JavaScript en sí. Si no estás familiarizado con la diferencia entre las características del lenguaje y las API proporcionadas por el navegador, consulta el capítulo Entorno del navegador, especificaciones para obtener contexto.

La API expone tres métodos en navigator.geolocation:

• getCurrentPosition() — obtiene la posición una sola vez.
• watchPosition() — obtiene la posición repetidamente a medida que el dispositivo se mueve.
• clearWatch() — detiene una suscripción de watchPosition().

Dos requisitos que no puedes omitir

1. Contexto seguro. Los navegadores solo exponen la geolocalización en páginas servidas mediante HTTPS (o localhost durante el desarrollo). En una página http:// simple, navigator.geolocation puede estar ausente o todas las llamadas fallarán. Esto es una medida de privacidad y seguridad.
2. Permiso del usuario. El navegador muestra un aviso la primera vez que una página solicita la ubicación. No ocurre nada hasta que el usuario hace clic en Permitir. Si elige Bloquear, tu callback de error se activa con un código PERMISSION_DENIED.

Verificación de disponibilidad de la API

Siempre detecta la función antes de usar la API, ya que los navegadores antiguos y las páginas no seguras pueden no proporcionarla.

Obtención de la posición actual

Para obtener la ubicación del dispositivo una sola vez, llama a getCurrentPosition(success, error, options). Solo el primer argumento es obligatorio.

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);

El objeto de posición

El callback de éxito recibe un objeto GeolocationPosition con dos campos:

• position.timestamp — cuándo se tomó la lectura (milisegundos desde el epoch).
• position.coords — un objeto GeolocationCoordinates que contiene:

Los campos heading y speed generalmente solo se rellenan en dispositivos que están en movimiento y cuentan con los sensores adecuados.

El objeto de opciones

Las tres opciones son opcionales. Elige según tu caso de uso:

Una compensación habitual: establece enableHighAccuracy: false y un maximumAge distinto de cero cuando un resultado aproximado y rápido es suficiente (por ejemplo, "tiendas cerca de mí"); usa enableHighAccuracy: true con maximumAge: 0 para navegación paso a paso.

Manejo de errores

Cuando una solicitud falla, el callback de error recibe un GeolocationPositionError. Su propiedad code indica exactamente qué salió mal:

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) — el usuario bloqueó el acceso a la ubicación, o la página no es un contexto seguro.
• POSITION_UNAVAILABLE (2) — el dispositivo no pudo determinar su ubicación (sin señal GPS/Wi-Fi, etc.).
• TIMEOUT (3) — no se obtuvo ninguna posición dentro del timeout establecido.

Verificación del permiso con antelación

Puedes inspeccionar el permiso de geolocalización sin activar un aviso mediante la Permissions API. Esto es útil para adaptar tu interfaz de usuario (por ejemplo, ocultar un botón "Encuéntrame" si el acceso ya está bloqueado).

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

Monitoreo continuo de la posición

Para el rastreo en tiempo real, watchPosition() llama a tu callback de éxito cada vez que cambia la posición del dispositivo. Devuelve un ID de seguimiento numérico que pasas a clearWatch() para detener el rastreo; no limpiarlo mantiene la ubicación activa y agota la batería.

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);

Si tu rastreo depende de que la pantalla gire entre modo vertical y horizontal, la API de Orientación de Pantalla se complementa bien con la geolocalización en aplicaciones de mapas.

Un ejemplo completo: muestra tu ubicación en un mapa

Este ejemplo usa la API de Geolocalización para obtener tus coordenadas y la biblioteca Leaflet.js para renderizarlas en una capa de 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>

Cuando cargues la página, solicitará inmediatamente tu ubicación y luego mostrará un marcador en el mapa en tu posición con un popup que dice "You are here!". Esta representación visual te ayuda a entender cómo los sitios web pueden interactuar con datos geográficos para mejorar la experiencia del usuario.

Buenas prácticas

• Detecta siempre la función y sirve mediante HTTPS, o todas las llamadas fallarán.
• Solicita la ubicación solo cuando el usuario lo espera — por ejemplo, después de que haga clic en un botón "Encuéntrame" — para que el aviso de permiso tenga contexto claro.
• Maneja cada código de error y muestra una alternativa útil (como una búsqueda de ubicación manual) cuando se deniega el permiso.
• Llama a clearWatch() tan pronto como ya no necesites actualizaciones continuas para ahorrar batería.
• Elige las opciones deliberadamente: alta precisión para navegación, un maximumAge distinto de cero para búsquedas rápidas de "cerca de mí".

Conclusión

La API de Geolocalización ofrece a las aplicaciones web una forma respetuosa con la privacidad para leer la ubicación del usuario a través de tres métodos: getCurrentPosition() para una lectura única, watchPosition() para rastreo en tiempo real, y clearWatch() para detenerlo. Combinada con opciones bien elegidas y un manejo adecuado de errores, potencia mapas, búsquedas locales y otras funciones con conciencia de ubicación. Para profundizar en API relacionadas del navegador, explora la API de Orientación de Pantalla y el capítulo Entorno del navegador, especificaciones.

Práctica