GoogleMap3rd, la géolocalisation facile

GoogleMap3rd, la géolocalisation facile

GoogleMap3rd est une API javascript qui vient se greffer par dessus l’API Google MAP et qui permet d’insérer facilement une map Google sur un site et y ajouter tout un tas d’information.L’exemple que je vais vous présenter est la géo-localisation des membres d’un site, en l’occurrence celui de mon escadrille virtuelle, la 3rd-wing (d’où le nom de l’API). Le résultat à obtenir : une carte de france Google Map qui affiche un point cliquable pour chaque membre/pilote inscris à la 3rd-wing, c’est à dire ça :

3rd-wing Google MAP API

Télécharger l’API GoogleMap3rd

Comment ça marche ?

1. L’API GOOGLEMAP3RD ET L’AFFICHAGE D’UNE CARTE GOOGLE MAP

Pour commencer nous allons juste afficher une carte GoogleMap et pour cela les quelques lignes suivantes suffisent :

[codesyntax lang="html4strict" lines="no" container="pre"]

<html>
	  <head>
	    <title>Google Map 3rd-wing API TEST</title>

	  </head>
	<body>
	  <div id="map" style="border: 1px solid #979797; background-color: #e5e3df; width: 400px; height: 300px; margin: auto; margin-top: 2em; margin-bottom: 2em"><div style="padding: 1em; color: gray">Loading...</div></div>
	  <script src="http://maps.google.com/maps?file=api&v=2&key=ABQIAAAAKEkhLXAmUgVZUeqISfZbphSWroGu0Oj_7cv9kCxYXauzniP-MhRuQTAcjPeM8vM2tPWvp7Jm1t9z4w"     type="text/javascript"></script>

	  <script src="http://monsite.net/googleMap3rd.js" type="text/javascript"></script>
	  <script type="text/javascript">
	      gmap = new gMap3rd("map");
	  </script>
	</body>
	</html>

[/codesyntax]

Petite explication :
- la balise div ayant pour id map est la balise dans laquelle nous afficheront la carte
- la première balise script permet l’insertion de l’API Google MAP, n’oubliez pas de générer une clé pour votre site (c’est gratuit)
- la deuxième balise script permet l’insertion de l’API GoogleMap3rd (vous pouvez héberger ce script sur votre site et remercier son auteur )
- et enfin nous générons l’affichage de la carte en appelant le constructeur de l’API de cette façongmap = new gMap3rd(”map”);

Ce premier script permet donc l’affichage d’une simple carte google map. La classe GoogleMap3rd publie également quelques fonctions qui permettent d’ajouter quelques fonctions pratique à la carte, par exemple :

[codesyntax lang="javascript" lines="no" container="pre"]

gmap.addLargeMapControl();

[/codesyntax]

Ajout d’un contrôle permettant de se déplacer dans la carte et gérer le niveau de zoom.

[codesyntax lang="javascript" lines="no" container="pre"]

gmap.enableScrollWheelZoom();

[/codesyntax]

Active le réglage du zoom avec la molette de la souris.

[codesyntax lang="javascript" lines="no" container="pre"]

gmap.centerMapToFrance(5);

[/codesyntax]

Ou encore cette fonction qui permet de centrer la carte sur la France avec en paramètre le niveau de zoom (allant de 1 à 12). Il existe bien d’autres fonctions, je vous laisse les découvrir en parcourant le source de l’API.

2. AJOUTER DES DONNÉES À NOTRE CARTE

Maintenant que nous avons une carte, nous allons y ajouter quelques informations. Pour cela nous allons nous baser sur les données d’un fichier XML. Dans le cadre de cet exemple, le fichier XML utilisé est généré depuis un script PHP. Le script PHP récupère la localité de chaque membre et retourne un flux de ce type :

[codesyntax lang="xml" lines="no" container="pre"]

	<data>
	  <markers>
	    <marker>
	      <name>Wats</name>

	      <locality>Strasbourg</locality>
	    </marker>
	    <marker>
	      <name>Wilbur</name>
	      <locality>Dampierre sur Avre</locality>

	    </marker>
	  </markers>
	</data>

[/codesyntax]

Chaque marker définit ici sera donc représenté par une petite bulle/point sur la carte. Pour placer ces bulles, deux possibilités :
- soit on renseigne une balise <locality> contenant le nom d’une rue, d’une ville, d’une localité ou même une adresse complète
- soit on renseigne les balises <lat> et <long> pour placer le point en fonction de la latitude et la longitude saisies

Reste maintenant à appeler la fonction qui va analyser ce flux XML et utiliser les API Google pour placer les points sur la carte. Pour cela, insérez la ligne de code suivante :

[codesyntax lang="javascript" lines="no" container="pre"]

gmap.loadMarkers("http://monsite.net/monflux.xml");

[/codesyntax]

L’unique paramètre étant l’URL permettant d’accéder au flux XML de données.

Au final nous avons donc le code source suivant :

[codesyntax lang="html4strict" lines="no" container="pre"]

<html>
	  <head>
	    <title>Google Map 3rd-wing API TEST</title>
	  </head>
	<body>

	  <div id="map" style="border: 1px solid #979797; background-color: #e5e3df; width: 400px; height: 300px; margin: auto; margin-top: 2em; margin-bottom: 2em"><div style="padding: 1em; color: gray">Loading...</div></div>
	<div id="debug"></div>
	<script src="http://maps.google.com/maps?file=api&v=2&key=ABQIAAAAKEkhLXAmUgVZUeqISfZbphSWroGu0Oj_7cv9kCxYXauzniP-MhRuQTAcjPeM8vM2tPWvp7Jm1t9z4w"     type="text/javascript"></script>
	<script src="http://monsite.net/googleMap3rd.js" type="text/javascript"></script>

	<script type="text/javascript">
	cacheManager = "http://monsite.net/googleMap3rdCache.php";
	debugInfo = false;
	debugError = true;
	gmap = new gMap3rd("map");
	gmap.addLargeMapControl();
	gmap.enableScrollWheelZoom();
	gmap.centerMapToFrance(5);
	gmap.loadMarkers("http://monsite.net/monflux.xml");
	</script>
	</body>
	</html>

[/codesyntax]

Ce code source vous permet d’obtenir le résultat mis en lien au début de ce tutorial (cliquez sur l’image en haut de page).

Voilà déjà de quoi vous amuser. Si vous avez des questions, n’hesitez pas à laisser vos commentaires et pour les plus courageux je vous invite à lire le chapitre suivant pour en découvrir d’avantage !

3. MIEUX COMPRENDRE LE SCRIPT

Gestion du cache de données

Vous aurez sans doute remarqué dans l’exemple précédent le code suivant :

[codesyntax lang="javascript" lines="no" container="pre"]

cacheManager = "http://monsite.net/googleMap3rdCache.php";
	debugInfo = false;
	debugError = true;

[/codesyntax]

GoogleMap3rd intègre un système de cache des données de géolocalisation afin de contourner les limitations de l’API GoogleMAP. La limitation principale étant le nombre de demandes de géolocalisation en un temps restreint. En d’autres termes, si vous devez géolocaliser une centaine d’adresse à la suite, l’API GoogleMAP n’en traitera probablement qu’une vingtaine. Ceci permet à Google de limiter le flood sur leur service GoogleMap en évitant qu’un site envoie des milliers de requête dans la même seconde.

GoogleMap3rd va donc stocker les adresses déjà géolocalisées dans un fichier de données “GoogleMap3rd.dat” sur le serveur hébergant l’API. Pour utiliser le système de cache et assurer le bon fonctionnement de l’API, vous devez donc renseigner le paramètre suivant :

cacheManager : URL du script PHP de gestion du cache. Ce script est à héberger sur votre site, n’oubliez donc pas d’adapter l’URL en fonction.

Les paramètres debugInfo et debugError sont optionnelles mais permettent d’afficher entre autre les éventuelles erreurs de géolocalisation. Pour cela une balise div portant l’ID “debug” doit existé dans votre page HTML.

D’autres choses à venir….