API de Géolocalisation JavaScript

L'API de Géolocalisation permet à une page web de demander au navigateur où se trouve l'appareil de l'utilisateur. Avec la permission de l'utilisateur, vous obtenez des coordonnées (latitude et longitude) que vous pouvez utiliser pour afficher des résultats à proximité, centrer une carte ou associer du contenu à un emplacement. Ce guide couvre l'intégralité de l'API : vérification du support, lecture de la position courante en une seule fois, surveillance des changements de position dans le temps, les options qui contrôlent la précision et le délai, ainsi que la gestion correcte des erreurs et des permissions.

Introduction à l'API de Géolocalisation

L'API de Géolocalisation fait partie de l'environnement navigateur (l'objet navigator), et non du langage JavaScript lui-même. Si vous débutez avec la différence entre les fonctionnalités du langage et les API fournies par le navigateur, consultez le chapitre Environnement navigateur, spécifications pour plus de contexte.

L'API expose trois méthodes sur navigator.geolocation :

• getCurrentPosition() — obtenir la position une seule fois.
• watchPosition() — obtenir la position de façon répétée à mesure que l'appareil se déplace.
• clearWatch() — arrêter un abonnement à watchPosition().

Deux prérequis incontournables

1. Contexte sécurisé. Les navigateurs n'exposent la géolocalisation que sur les pages servies via HTTPS (ou localhost pendant le développement). Sur une page http:// simple, navigator.geolocation peut être absent ou chaque appel peut échouer. Il s'agit d'une mesure de confidentialité et de sécurité.
2. Permission de l'utilisateur. Le navigateur affiche une invite la première fois qu'une page demande la localisation. Rien ne se passe tant que l'utilisateur ne clique pas sur Autoriser. S'il choisit Bloquer, votre callback d'erreur est déclenché avec le code PERMISSION_DENIED.

Vérification de la disponibilité de l'API

Effectuez toujours une détection de fonctionnalité avant d'utiliser l'API, car les anciens navigateurs et les pages non sécurisées peuvent ne pas la fournir.

Obtenir la position actuelle

Pour récupérer la position de l'appareil une seule fois, appelez getCurrentPosition(success, error, options). Seul le premier argument est obligatoire.

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

L'objet position

Le callback de succès reçoit un objet GeolocationPosition avec deux champs :

• position.timestamp — moment où la lecture a été effectuée (millisecondes depuis l'époque Unix).
• position.coords — un objet GeolocationCoordinates contenant :

Les champs heading et speed ne sont généralement renseignés que sur les appareils qui se déplacent réellement et disposent des capteurs appropriés.

L'objet options

Les trois options sont toutes facultatives. Choisissez-les en fonction de votre cas d'usage :

Un compromis courant : définissez enableHighAccuracy: false et un maximumAge non nul quand un résultat approximatif et rapide suffit (par exemple, « commerces près de moi ») ; utilisez enableHighAccuracy: true avec maximumAge: 0 pour la navigation tour par tour.

Gestion des erreurs

Lorsqu'une requête échoue, le callback d'erreur reçoit un GeolocationPositionError. Sa propriété code vous indique exactement ce qui s'est mal passé :

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) — l'utilisateur a bloqué l'accès à la localisation, ou la page n'est pas un contexte sécurisé.
• POSITION_UNAVAILABLE (2) — l'appareil n'a pas pu déterminer sa position (absence de signal GPS/Wi-Fi, etc.).
• TIMEOUT (3) — aucune position n'a été obtenue dans le délai timeout défini.

Vérifier la permission à l'avance

Vous pouvez inspecter la permission de géolocalisation sans déclencher d'invite, en utilisant l'API Permissions. Cela est utile pour adapter votre interface (par exemple, masquer un bouton « Me localiser » si l'accès est déjà bloqué).

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

Surveillance continue de la position

Pour le suivi en temps réel, watchPosition() appelle votre callback de succès chaque fois que la position de l'appareil change. Il renvoie un identifiant de surveillance numérique que vous passez à clearWatch() pour arrêter le suivi — ne pas l'appeler maintient la localisation active et épuise la batterie.

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 votre suivi dépend de la rotation de l'écran entre portrait et paysage, l'API Screen Orientation se combine bien avec la géolocalisation dans les applications cartographiques.

Un exemple complet : afficher votre position sur une carte

Cet exemple utilise l'API de Géolocalisation pour obtenir vos coordonnées et la bibliothèque Leaflet.js pour les afficher sur une couche 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>

Lorsque vous chargez la page, elle demande immédiatement votre localisation, puis affiche un marqueur sur la carte à votre position avec une popup indiquant « You are here! ». Cette représentation visuelle vous aide à comprendre comment les sites web peuvent interagir avec des données géographiques pour enrichir l'expérience utilisateur.

Bonnes pratiques

• Effectuez toujours une détection de fonctionnalité et servez via HTTPS, sinon tous les appels échoueront.
• Demandez la localisation uniquement quand l'utilisateur s'y attend — par exemple, après avoir cliqué sur un bouton « Me localiser » — afin que l'invite de permission ait un contexte clair.
• Gérez tous les codes d'erreur et affichez un repli utile (par exemple, une recherche de localisation manuelle) lorsque la permission est refusée.
• Appelez clearWatch() dès que vous n'avez plus besoin de mises à jour continues pour économiser la batterie.
• Choisissez vos options délibérément : haute précision pour la navigation, un maximumAge non nul pour les recherches rapides de type « près de moi ».

Conclusion

L'API de Géolocalisation offre aux applications web un moyen respectueux de la vie privée pour lire la position de l'utilisateur à travers trois méthodes : getCurrentPosition() pour une lecture unique, watchPosition() pour le suivi en direct, et clearWatch() pour arrêter. Combinée à des choix d'options réfléchis et une gestion appropriée des erreurs, elle permet de créer des cartes, des recherches locales et d'autres fonctionnalités géolocalisées. Pour aller plus loin avec les API navigateur associées, explorez l'API Screen Orientation et le chapitre Environnement navigateur, spécifications.

Pratique