Survol de la GoogleMaps Api v3

Beaucoup d’entre vous ont certainement déjà eu l’occasion de jouer avec l’api javascript de GoogleMaps. Elle est performante, bien documentée, et plutôt instinctive à implémenter. De plus il éxiste énormément de ressources sur le web proposant des exemples d’utilisation.
On trouve cependant encore peu de ressources mentionnant la dernière mouture de l’api, la v3, qui simplifie et éclaircie encore plus son utilisation. Ce petit article va survoler quelques exemples d’utilisation de celle-ci.

La première grosse nouveauté de la v3, c’est la mort de la clé api ! En effet, il n’est plus nécessaire de déclarer un domaine pour récupérer une clé, ou de se battre avec tout un trousseau pour jongler entre des environnements de dev, preprod, prod, test, etc… Maintenant on charge simplement l’api comme n’importe quelle librairie Javascript.
Second changement notoire, plus aucun appel Ajax explicite vers l’api REST n’est nécessaire pour récupérer des données de géolocalisation. Un simple passage de paramètres à des objets Javascript nous rendra les informations voulues en un temps record.

Commençons donc par charger l’api et afficher une map:

?View Code JAVASCRIPT
<div id="gmap-div" style="width: 500px; height: 400px;"></div>
 
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.5.1/jquery.min.js"></script>
<script type="text/javascript" src="http://maps.google.com/maps/api/js?sensor=false" />
<script type="text/javascript">
$(function() {
  //J'utilise dans l'exemple jQuery pour améliorer la lisibilité du code, le focus étant sur GoogleMaps
 
  //tout d'abord on définit le centre de notre map par sa latitude et longitude, par exemple Montpellier: 
  var latLng = new google.maps.LatLng(43.60, 3.88);
  //puis on créé la map
  var gmap = new google.maps.Map(document.getElementById('gmap-div'), {
    zoom: 10, //le zoom de départ
    center: latLng, //le centre de la map au chargement
    mapTypeId: google.maps.MapTypeId.ROADMAP, //le type de map, ROADMAP correspond à la version par défaut des versions précédentes
    streetViewControl: false, //si on souhaite désactiver les contrôle StreetView
    panControl: false //si on souhaite masquer les contrôles de déplacement
  });
});	
</script>

Créons maintenant quelques interactions. Pour commencer un formulaire va nous permettre de rechercher une ville pour ensuite placer un marqueur à son emplacement sur la map:

<form id="search-form" action="#">
  <input type="text" id="search-query" size="20" />
  <input type="submit" value="chercher" />
</form>

Et le code javascript correspondant:

?View Code JAVASCRIPT
//on créé un geocoder qui s'occupera des requètes de géolocalisation
var geocoder = new google.maps.Geocoder();
 
$('#search-form').submit(function(e) {
  e.preventDefault();
 
  //l'objet request que l'on passe au geocoder
  var request = {
    address:    $('#search-query').val(),
    region:     'fr', //pour améliorer la qualité des résultats en précisant que l'on cherche principalement en France
    language:   'fr'
  };
  //aucune requète ajax nécessaire !
  geocoder.geocode(request, function(results, status) {
    if (status == 'OK' && results.length) {
      //on récupère les coordonnées du premier résultat
      var lat = results[0].geometry.location.lat();
      var lng = results[0].geometry.location.lng();
 
      //puis on recentre la map...
      var newCenter = new google.maps.LatLng(lat, lng);
      gmap.setCenter(newCenter);
 
      //...et on pose un marqueur dessus
      new google.maps.Marker({
	position:  newCenter,
        map:       gmap
      });
    } else {
      console.log('aucun résultat');
    }
  });
});

Plutôt simple pour l’instant. Allons un peu plus loin et traçons une ligne qui va relier au fur et à mesure toutes les villes marquées. Il va falloir pour cela utiliser la librairie supplémentaire de GoogleMaps « Geometry ». N’étant pas une librairie chargée par défaut, il faut préciser son utilisation au chargement de GoogleMaps:

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

Profitons-en pour afficher la longueur en kilomètre de notre itinéraire dans une div que l’on va tout de suite rajouter au document:

<div id="total-length"></div>

Pour tracer une ligne reliant des points sur une GoogleMap, il faut utiliser la classe « Polyline ». Déclarons-la juste après la map en début de script:

?View Code JAVASCRIPT
  /* ... */
  var polyline = new google.maps.Polyline({
    strokeColor:   '#2222FF', //on définit la couleur
    strokeOpacity: 0.5,       //l'opacité
    strokeWeight:  3,         //l'épaisseur du trait,
    map:           gmap       //la map à laquelle rattacher la polyline
  });
 
  //on peut extraire un objet renfermant tous les points d'une Polyline
  //cet objet nous sera utile pour calculer la distance de l'itinéraire
  var path = polyline.getPath();

Il faut maintenant étoffer le code de création du marqueur:

?View Code JAVASCRIPT
  /* ... */
  geocoder.geocode(request, function(results, status) {
    if (status == 'OK' && results.length) {
      var lat = results[0].geometry.location.lat();
      var lng = results[0].geometry.location.lng();
 
      var newCenter = new google.maps.LatLng(lat, lng);
      gmap.setCenter(newCenter);
 
      new google.maps.Marker({
        position:  newCenter,
        map:       gmap
      });
 
      //on ajoute le nouveau point à notre path, le Polyline associé se met automatiquement à jour
      path.push(newCenter);
 
      //on affiche la longueur du path dans notre div
      //c'est ici qu'intervient la librairie Geometry, qui va gérer automatiquement tous les calculs nécessaires
 
      var pathLength = parseInt(google.maps.geometry.spherical.computeLength(path)) / 1000;
      //computeLength nous renvoie des mètres que l'on transforme en kilomètres
 
      //on met à jour l'affichage
      $('#total-length').html(pathLength + ' km');
 
    } else {
      console.log('aucun résultat');
    }
  });
  /* ... */

Il a suffi d’une poignée de lignes pour rajouter ces informations, et le résultat est plutôt sympathique.

On remarque tout de même un détail ennuyeux: il faut déplacer et zoomer à la main si on veut avoir une vue globale et centrée de notre itinéraire à chaque nouvel ajout de marqueur. A la manière du « path » qui stocke les informations d’une Polyline, une map possède des « bounds » qui définissent les limites de son affichage. La classe « LatLngBounds » arrive ici en jeu et va nous permettre d’optimiser automatiquement l’affichage de notre itinéraire.

?View Code JAVASCRIPT
  //en début de script avec les déclarations, on créé notre objet bounds
  var bounds = new google.maps.LatLngBounds();
 
  /* ... */
 
  //à la suite de l'ajout d'un nouveau marqueur, on étend la zone "bounds" en lui demandant d'inclure le nouveau point
  bounds.extend(newCenter);
  //on demande en suite à la map de s'adapter à cette zone
  gmap.fitBounds(bounds);
 
  /* ... */

Et c’est tout ! Encore trois malheureuses lignes pour une fonctionnalité relativement puissante. Vous pouvez voir l’exemple tourner sur cette page.

La richesse de cette dernière version de l’api, couplée à la fluidité de son utilisation, rend l’intégration d’une GoogleMap dans une application riche vraiment agréable. Jetez un oeil à la documentation officielle très complète si vous souhaitez en apprendre plus !

Les sources de l’exemple de cet article sont disponibles sur Github.

Partagez cet article