API di Geolocalizzazione JavaScript

La Geolocation API consente a una pagina web di chiedere al browser la posizione del dispositivo dell'utente. Con il consenso dell'utente, si ottengono le coordinate (latitudine e longitudine) che è possibile utilizzare per mostrare risultati nelle vicinanze, centrare una mappa o associare contenuti a una posizione. Questa guida copre l'intera API: verifica del supporto, lettura della posizione corrente una volta sola, monitoraggio delle variazioni di posizione nel tempo, le opzioni che controllano precisione e tempi di risposta, e come gestire correttamente errori e permessi.

Introduzione alla Geolocation API

La Geolocation API fa parte dell'ambiente browser (l'object navigator), non del linguaggio JavaScript in sé. Se non conosci ancora la differenza tra le funzionalità del linguaggio e le API fornite dal browser, consulta il capitolo Ambiente browser, specifiche per approfondire il contesto.

L'API espone tre metodi su navigator.geolocation:

• getCurrentPosition() — ottieni la posizione una volta sola.
• watchPosition() — ottieni la posizione ripetutamente man mano che il dispositivo si sposta.
• clearWatch() — interrompi una sottoscrizione a watchPosition().

Due requisiti che non puoi ignorare

1. Contesto sicuro. I browser espongono la geolocalizzazione solo nelle pagine servite tramite HTTPS (oppure localhost durante lo sviluppo). Su una pagina con http:// semplice, navigator.geolocation potrebbe essere assente o ogni chiamata potrebbe fallire. Si tratta di una misura di privacy e sicurezza.
2. Consenso dell'utente. Il browser mostra una richiesta la prima volta che una pagina richiede la posizione. Non accade nulla finché l'utente non fa clic su Consenti. Se l'utente sceglie Blocca, il callback di errore viene invocato con un codice PERMISSION_DENIED.

Verifica della disponibilità dell'API

Esegui sempre il rilevamento delle funzionalità prima di utilizzare l'API, poiché i browser datati e le pagine non sicure potrebbero non fornirla.

Ottenere la posizione corrente

Per recuperare la posizione del dispositivo una sola volta, chiama getCurrentPosition(success, error, options). Solo il primo argomento è obbligatorio.

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'object posizione

Il callback di successo riceve un object GeolocationPosition con due campi:

• position.timestamp — quando è stata effettuata la lettura (millisecondi dall'epoch).
• position.coords — un object GeolocationCoordinates contenente:

I campi heading e speed sono di solito popolati solo su dispositivi che si stanno effettivamente muovendo e dispongono dei sensori appropriati.

L'object opzioni

Tutte e tre le opzioni sono facoltative. Sceglile in base al tuo caso d'uso:

Un compromesso comune: imposta enableHighAccuracy: false e un maximumAge diverso da zero quando va bene un risultato approssimativo e veloce (ad esempio "negozi vicino a me"); usa enableHighAccuracy: true con maximumAge: 0 per la navigazione turn-by-turn.

Gestione degli errori

Quando una richiesta fallisce, il callback di errore riceve un GeolocationPositionError. La sua proprietà code indica esattamente cosa è andato storto:

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'utente ha bloccato l'accesso alla posizione, oppure la pagina non è un contesto sicuro.
• POSITION_UNAVAILABLE (2) — il dispositivo non è riuscito a determinare la propria posizione (nessun segnale GPS/Wi-Fi, ecc.).
• TIMEOUT (3) — non è stata ottenuta alcuna posizione entro il timeout impostato.

Verificare il permesso in anticipo

Puoi ispezionare il permesso di geolocalizzazione senza attivare una richiesta utilizzando la Permissions API. Questo è utile per adattare la UI (ad esempio, nascondere un pulsante "Trovami" se l'accesso è già stato bloccato).

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

Monitoraggio continuo della posizione

Per il tracciamento in tempo reale, watchPosition() chiama il tuo callback di successo ogni volta che la posizione del dispositivo cambia. Restituisce un ID numerico di watch che passi a clearWatch() per interrompere il tracciamento — non cancellarlo mantiene la posizione attiva e scarica la batteria.

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 il tuo tracciamento dipende dalla rotazione dello schermo tra orientamento verticale e orizzontale, la Screen Orientation API si abbina bene alla geolocalizzazione nelle app di mappatura.

Un esempio completo: mostrare la tua posizione su una mappa

Questo esempio usa la Geolocation API per ottenere le tue coordinate e la libreria Leaflet.js per visualizzarle su un layer 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>

Quando carichi la pagina, questa richiederà immediatamente la tua posizione e visualizzerà un segnaposto sulla mappa in corrispondenza della tua posizione, con un popup che indica "You are here!" Questa rappresentazione visiva ti aiuta a capire come i siti web possono interagire con i dati geografici per migliorare l'esperienza degli utenti.

Best practice

• Esegui sempre il rilevamento delle funzionalità e servi il sito tramite HTTPS, altrimenti ogni chiamata fallirà.
• Richiedi la posizione solo quando l'utente se lo aspetta — ad esempio, dopo che ha fatto clic su un pulsante "Trovami" — affinché la richiesta di consenso abbia un contesto chiaro.
• Gestisci ogni codice di errore e mostra un'alternativa utile (come una ricerca manuale della posizione) quando il permesso viene negato.
• Chiama clearWatch() non appena non hai più bisogno di aggiornamenti continui per risparmiare la batteria.
• Scegli le opzioni con cura: alta precisione per la navigazione, un maximumAge diverso da zero per ricerche rapide "vicino a me".

Conclusione

La Geolocation API offre alle web app un modo rispettoso della privacy per leggere la posizione dell'utente attraverso tre metodi: getCurrentPosition() per una lettura singola, watchPosition() per il tracciamento in tempo reale e clearWatch() per interrompere. Unita a scelte ponderate delle opzioni e a una corretta gestione degli errori, alimenta mappe, ricerche locali e altre funzionalità basate sulla posizione. Per approfondire le API browser correlate, esplora la Screen Orientation API e il capitolo Ambiente browser, specifiche.

Pratica