Geolocation API

Link copiato negli appunti

Le Geolocation Api non sono contenute all’interno dell’HTML5 ma fanno parte di quell’insieme di documenti che gravitano attorno alle specifiche; la loro funzionalità è abbastanza semplice, definire una struttura dati atta a contenere vari dati geospaziali e impostare alcune funzioni di accesso a tali dati. Nessuna menzione viene fatta in merito ai meccanismi che il browser deve utilizzare per recuperare questi dati, ogni piattaforma è infatti tenuta ad utilizzare al meglio le informazioni provenienti dal device. Su di un dispositivo mobile di ultima generazione avremo quindi un set di coordinate provenienti dal sensore GPS, mentre su di un portatile potremo avvalerci del posizionamento legato all’ip della connessione internet.

Per proteggere la privacy dell’utente è inoltre fatto divieto di utilizzo delle suddette informazioni senza preventivo consenso esplicito.

Le specifiche

Esistono praticamente solo due metodi a disposizione, fra l’altro entrambi utili allo stesso scopo: ottenere la posizione corrente. La differenza tra i due, getCurrentPosition e watchPosition, va ricercata nella loro periodicità, mentre il primo metodo fornisce il dato una sola volta, il secondo si attiva automaticamente ogniqualvolta la posizione cambi, ad esempio perché l’utente sta passeggiando.

La sintassi per invocare questi metodi è la seguente:

navigator.geolocation.getCurrentPosition(inCasoDiSuccesso, opzInCasoDiErrore, opzioni);
navigator.geolocation.watchPosition(inCasoDiSuccesso, opzInCasoDiErrore, opzioni);

Il primo argomento contiene i riferimenti ad una funzione da eseguire al corretto recupero delle informazioni geospaziali, il secondo argomento, opzionale, punta invece ad una funzione che verrà invocata in caso di errore. L’ultimo parametro, anch’esso facoltativo, può essere utilizzato per specificare alcune opzioni utilizzando una struttura {opzione1: valore1, ...}. Le opzioni disponibili sono 3:

enableHighAccuracy (true/false): questo flag può essere utilizzato per notificare allo user-agent la necessità o meno di ottenere dati il più accurati possibile. L’opzione è stata introdotta in quanto il recupero di informazioni più dettagliate richiede di solito maggiore dispendio di tempo ed energia e, in particolare su device mobile, potrebbe risultare fastidiosa per l’utente;
timeout (millisecondi): l’opzione rappresenta il tempo massimo concesso al browser per recuperare la posizione dell’utente. In caso di fallimento verrà invocata la funzione associata al secondo argomento;
maximuAge (millisecondi): indica al browser di effettuare una ricerca preventiva nella cache di un dato geospaziale non più vecchio dei millisecondi specificati. Se disponibile tale dato verrà restituito come posizione corrente, altrimenti verrà eseguita la procedura classica.

La funzione invocata in caso di successo deve accettare un singolo argomento, un oggetto di tipo Position che contiene tutte le informazioni recuperate così come un timestamp delle data e ora di recupero.

inCasoDiSuccesso = function(position){
  alert( "Posizione delle: " + position.timestamp.getHours() + ":" +
  position.timestamp.getMinutes() + "n" +
  "Accuratezza delle coordinate: " + position.coords.accuracy + " mt; n" +
  "Latitudine: " + position.coords.latitude + " gradi; n" +
  "Longitudine: " + position.coords.longitude + "gradi; n" +
  "Accuratezza dell'altezza: " + position.coords.altitudeAccuracy + " mt; n" +
  "Altezza: " + position.coords.altitude + " mt; n" +
  "Direzione: " + position.coords.heading + " gradin " +
  "(0 = Nord, 90 = Ovest, 180 = Sud, 270 = Est);n" +
  "Velocita: " + position.coords.speed + " m/s;"
  );
}

Nel frammento di codice appena illustrato possiamo vedere tutte le informazioni estraibili dalla struttura Position; chiaramente, a seconda del device sul quale viene effettuata l’interrogazione, non tutte saranno sempre disponibili; in tal caso il loro valore sarà impostato a null. Nell’immagine seguente il risultato dell’interrogazione eseguita dal mio portatile domestico (notate l’accuratezza!):

Figura 1 - (click per ingrandire)

In caso invece si verifichi un errore la funzione preposta deve accettare anch’essa un parametro, un oggetto di tipo PositionError contenente un codice di errore ed un messaggio ad uso di debug, rispettivamente nei metodi code e message.

opzInCasoDiErrore = function(error){
  alert( "Errore " + error.code + ": " + error.message);
}

In ultimo ricordiamo che un invocazione del metodo watchPosition può essere successivamente interrotta utilizzando la funzione clearWatch, come nell’esempio seguente:

<!doctype html>
<html>
<head>
  <title> Un esempio di watchPosition</title>
  <script>
  var id_watch = null;
  inCasoDiSuccesso = function(position){
    document.getElementById("posizione_corrente").insertAdjacentHTML('beforeend',
    "<li> Lat: " + position.coords.latitude + ", Lon: " + position.coords.longitude + );
    "</li>"
    );
  }
  sospendiLaRicezione = function(){
    navigator.geolocation.clearWatch(id_watch);
  }
  window.onload = function(){
    id_watch = navigator.geolocation.watchPosition(inCasoDiSuccesso);
  }
</script>
</head>
<body>
  <h1>La tua posizione attuale</h1>
  <menu type="toolbar">
    <button type="button" onclick="sospendiLaRicezione()">
      sospendi la ricezione di dati geospaziali
    </button>
  </menu>
  <ul id="posizione_corrente">
  </ul>
</body>
</html>

Sono disponibili le demo per il primo e per il secondo esempio.

Conclusioni

Come avete potuto notare questo set di API è contemporaneamente facilissimo da utilizzare ed estremamente potente. Le possibilità offerte si dilatano enormemente se ci si concentra sul mercato mobile dove la stragrande maggioranza dei device di ultima generazione è equipaggiata con ottimi sensori GPS e bussole.