[JavaScript] L’API Géolocalisation de HTML 5

Le fonctionnement

L’API HTML 5 de géolocalisation s’utilise en Javascript, côté client. C’est le navigateur qui se charge de récupérer la position à partir des moyens suivants (par ordre de précision décroissante) :

1. Coordonnées GPS (si la machine cliente dispose d’un capteur, par exemple les smartphones)
2. Triangulation sur réseau mobile ou Wi-Fi
3. Traceroute sur l’adresse IP
4. Données entrées par l’utilisateur

Suivant la technique utilisée, le navigateur arrivera à déterminer la position avec un degré de précision variable. Quand un traceroute donne rarement une précision meilleure que la distance entre l’utilisateur et le DSLAM (parfois quelques kilomètres), un capteur GPS pourra donner une précision de l’ordre de quelques mètres).

La fonction principale

Pour obtenir les données de géolocalisation, il faut passer par la fonction getCurrentPosition qui peut s’utiliser de trois manières :

navigator.geolocation.getCurrentPosition(function success);

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

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

Les paramètres sont :

Paramètre	Type	Description
success	function(Position )	Une fonction appelée en cas de succès de la géolocalisation. Le paramètre contient les données de géolocalisation. Pour plus de détails, voir cette section.
error	function(PositionError)	Une fonction appelée en cas d'erreur lors du processus de géolocalisation. Pour plus de détails, voir cette section.
options	PositionOptions	Un objet contenant la configuration. Pour plus de détails, voir cette section.

Faire la demande de géolocalisation

Comment obtenir la position courante de l'utilisateur ? C'est très simple. Tout d'abord, on vérifie que l'API Geolocation est bien disponible sur le navigateur. Ensuite, on demande la position (en même temps, le navigateur va demandera la permission à l'utilisateur qui doit accepter). En cas de succès ou en cas d'erreur, des fonctions (callback) seront appelées.

Voici un petit exemple très rapide :

// On vérifie que l'API soit disponible
if (navigator.geolocation) {

	// On demande l'obtention de l'emplacement actuel.
	// Si la demande n'a jamais été faite, un popup s'affichera à l'utilisateur
	// pour lui proposer d'autoriser cet échange d'information.
	// Si l'utilisateur accepte et que le périphérique hôte dispose d'au moins
	// une méthode pour déterminer son emplacement, la callback success est appelée.
	navigator.geolocation.getCurrentPosition(
		function (position) {
			// En cas de succès
		},
		function (error) {
			// En cas d'erreur
		}
	);

}

Lecture des données

Quand la callback success est appelée, elle reçoit en paramètre un objet de type Position qui contient - entre autre - les données sur l'emplacement géographique de l'utilisateur.

Attribut	Type	Description
coords	PositionCoords	Un objet contenant la position géographique.
timestamp	int	Le moment où la position a été acquise.

L'objet PositionCoords

Cet objet contient les données géolocalisée de l'utilisateur :

Attribut	Type	Description
latitude	double	La latitude de la position, en dégrés décimaux.
longitude	double	La longitude de la position, en dégrés décimaux.
altitude	double	L'altitude de la position, en mètres par rapport à l'ellipsoïde WGS84.
accuracy	double	Delta de précision des mesures de latitude et de longitude, en mètres.
altitudeAccuracy	double	Delta de précision de la mesure d'altitude, en mètres.
heading	double	L'angle de déplacement (en degré) par rapport au nord, entre 0° (inclus) et 360° (exclus). Note: si la vitesse est nulle, le déplacement est nul lui aussi, donc cette propriété prends la valeur NaN.
speed	double	La vitesse actuelle de déplacement de la position (en mètre par secondes).

Voici un petit exemple d'utilisation :

// On vérifie que l'API soit disponible
if (navigator.geolocation) {

	// On demande l'obtention de l'emplacement actuel.
	navigator.geolocation.getCurrentPosition(function (position) {

		// En cas de succès, on recupère les données de l'emplacement
		var lat = position.coords.latitude;
		var lng = position.coords.longitude;
		var alt = position.coords.altitude;

		// Et on l'affiche dans une popup
		alert("Lat: "+lat+"Lng: "+lng+"Alt: "+alt);

	});
}

La configuration

Il est possible de spécifier certains variables de configuration avant que l'API de géolocalisation ne fasse son travail. Cette configuration se fait dans un objet de type PositionOptions.

Voici les attributs de cet objets :

Attribut	Type	Description
enableHighAccuracy	boolean	Activer le mode « précision améliorée ». En gros, il s'agit de demander au périphérique d'obtenir la position la plus précise possible. Cela peut entrainer une augmentation du temps de réponse, et de la consommation électrique du périphérique. Valeur par défaut: false
timeout	long|Infinity	Délai maximale (en millisecondes) entre la demande à l'API et la réponse. En gros, le TTL. Notez que le temps pris pour obtenir l'autorisation de l'utilisateur n’est pas pris en compte. Par défaut: Infinity
maximumAge	long|Infinity	Délai maximale (en millisecondes) de la mise en cache de la position courante. Quand le cache est expiré, une nouvelle acquisition de la position est lancée. Si maximumAge vaut 0 la position sera toujours renouvelée. Valeur par défaut: 0

Voici un petit exemple d'utilisation de l'objet PositionOptions :

navigator.geolocation.getCurrentPosition(
	function (position) {
		// Traitement normal
	},
	function (error) {
		// Traitement de l'erreur
	},
	{
		maximumAge: 5000,
		timeout: 2000
	}
);

La gestion des erreurs

La fonction de callback d'erreur est appelée lorsque le navigateur ne parviens pas à déterminer son emplacement géographique. Cette fonction doit avoir un paramètre, qui contiendra un objet de type PositionError permettant de récupérer le code et le message d'erreur expliquant pourquoi le processus n'a pas fonctionné.

Voici les attributs de cet objets :

Attribut	Type	Description
code	int	Le code de l'erreur, parmi les valeurs suivantes : error.UNKNOWN_ERROR error.PERMISSION_DENIED error.POSITION_UNAVAILABLE error.TIMEOUT
message	string	Le message d'erreur.

Voici comment utiliser cette callback pour réaliser un traitement spécifique en cas d'erreur :

navigator.geolocation.getCurrentPosition(
	function (position) {
		// Traitement normal
	},
	function (error) {
		// Traitement de l'erreur
		switch (error.code) {
			case error.UNAVAILABLE :
				alert("Impossible de déterminer votre emplacement géographique");
				break;
			default :
				alert("Erreur : " + error.message);
		}
	},
	{
		maximumAge: 60000,
		timeout: 2000
	}
);

Suivi de la position

Si vous le souhaitez, l'API permet aussi de suivre les actualisations de la position si le périphérique hôte se déplace. En gros, il s'agit de devenir listener du changement d'emplacement géographique. Pour ce faire, on utilise la méthode watchPosition qui s'utilise de la même façon que getCurrentPosition.

Pour résilier cet abonnement, il faut récupérer un identifiant renvoyé par la méthode watchPosition et l’utiliser avec la méthode clearWatch.

Un petit exemple :

// On s'inscrit avec watchPosition. Quand la position aura changé, l'API
// appelera la callback.
var id = navigator.geolocation.watchPosition(
	function (position) {
	}
);

// On désinscrit la callback : elle ne sera plus appelée quand la position
// de l'utilisateur sera mise à jour.
navigator.geolocation.clearWatch(id);

Pour plus de détails sur cette méthode, consulter le guide de référence du W3C.

Exemple

Voici un petit exemple qui montre comment on peut coupler l'utilisation de cette API avec une application de catrographie comme Google Map.

Voici le code source de l'exemple ci-dessus. Première partie, le code HTML :

<input type="button" onclick="testGeoloc();"
	value="Cliquer sur ce bouton pour lancer la démonstration" />

<div id="demoGeoloc"></div>

<script type="text/javascript"
	src="http://maps.google.com/maps/api/js?sensor=true"></script>

Et la seconde partie, le code Javascript :

<script>
function testGeoloc() {
	var div = document.getElementById("demoGeoloc");
	if (!navigator.geolocation) {
		div.innerHTML = 'Erreur : votre navigateur ne supporte pas l\'API
			de Géolocalisation HTML 5';
		return;
	}
	div.innerHTML = 'Demande en cours...';
	navigator.geolocation.watchPosition(
		// Succès
		function (position) {
			var lat = position.coords.latitude;
			var lng = position.coords.longitude;
			div.innerHTML = 'Lat: '+lat+'  Lng: '+lng;
			div.style.height = '500px';
			var options = {
				zoom: 13,
				center: new google.maps.LatLng(lat, lng),
				mapTypeId: google.maps.MapTypeId.ROADMAP
			};
			var map = new google.maps.Map(div, options);
			var marker = new google.maps.Marker({ position: options.center });
			marker.setMap(map);
		},
		// Erreur
		function (error) {
			div.innerHTML = 'Erreur : ' + error.message;
		},
		// Configuration
		{
			maximumAge: 60000,
			timeout: 2000
		}
	);
}
</script>

Compatibilité

Comme toujours avec le HTML 5, se pose la question de la compatibilité de l'API :

• Chrome : versions 5 et + (ou grâce au plugin Gears)
• Firefox : versions 3.5 et +
• IE : 9 et + (ou grâce au plugin Gears)
• Opera : version 10.6 et +
• Safari : 5 et +

A l'heure actuelle (fin 2011), certains navigateurs n'implémentent que partiellement les données décrites plus haut. Le plus souvent, les données latitude, longitude sont fournies. Si une valeur n’existe pas, elle retournera null.

• La spécification de l'API Geolocation sur le site du W3C
• Article sur l'API Canvas de HTML 5 avec la création d'une petite petite application type paint.