ViaMichelin - JavaScript API V2 - Tutoriel

Objectif

Ce tutoriel vous guide dans l'utilisation de ViaMichelin JavaScript API V2 à travers la création de votre première carte.

Audience

Ce tutoriel s'adresse à des développeurs connaissant les principes fondamentaux du web, comme l'architecture client-serveur et les pages web, et les langages HTML et JavaScript.

Les utilisateurs de ViaMichelin JavaScript API V1 sont également invités à lire ce tutoriel car la syntaxe de ViaMichelin JavaScript API V2 est sensiblement différente de celle de la V1 (Paramétrage, fonction de lancement VMLaunch, etc).

Pré-requis

  • Un éditeur de texte suffit mais un atelier de développement logiciel (IDE) est conseillé
  • Un serveur web (comme Apache)
  • Un navigateur web (mobile). ViaMichelin JavaScript API V2 est compatible avec Microsoft Internet Explorer 6.0+, Mozilla Firefox 3.6+, Apple Safari 5+ et Google Chrome 6+. L'API prend en charge les évènements spécifiques aux mobiles pour l'Apple iPhone et les appareils à base de Google Android 2.2+.

Etape 1 : Créez votre compte ViaMichelin

Rendez-vous sur la page d'inscription puis remplissez et validez le formulaire pour ouvrir un compte d'essai ViaMichelin JavaScript API V2. Vous recevez alors votre clef d'utilisation (JSKey) dans la boîte mail que vous avez indiqué dans le champs Email professionnel.

Etape 2 : Présenter une carte

Créer la page (document web statique) qui contient la carte. Cette page respecte le format XHTML 1.0 Strict et doit-être encodée en UTF-8. Pour correctement fonctionner dans Internet Explorer, il ne faut pas oublier d'indiquer l'usage du VML.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en" xmlns:v="urn:schemas-microsoft-com:vml">
	<head>
		<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
		<meta name="viewport" content="initial-scale=1.0, user-scalable=no"/>
		<title>ViaMichelin JavaScript API V2</title>
	</head>
	<body>
	</body>
</html>

 

Le chargement de ViaMichelin JavaScript API V2 se fait par l'inclusion d'une balise script. Celle-ci peut-être positionnée dans le header de la page ou en fin de body.

<script src="http://apijsv2.viamichelin.com/apijsv2/api/js?key=YOUR_JSKEY&lang=eng" type="text/javascript"></script>

 

L'API accepte 2 paramètres dans l'URL d'appel:

  • key: obligatoire, votre clef d'authentification JSKey récupérée dans l'étape 1.
  • lang: facultatif, la langue à utiliser pour les menus de carte et les feuilles de route. Par défaut, il s'agit de l'anglais. Les valeurs possibles sont deu (Allemand), eng (Anglais), fra (Français), ita (Italien), nld (Néerlandais), pol (Polonais), por (Portugais), et spa (Espagnol).

Pour charger une carte, il faut au préalable déclarer son élément conteneur qui est un div et lui associer un nom. Dans notre tutoriel, nous souhaitons présenter une carte en pleine écran (fullscreen). Nous réglons donc le CSS en conséquence. Notez que le choix de la police est répercuté dans les menus de la carte.

<!-- CSS code -->
<style type="text/css">
	html { height: 100% }
	body { height: 100%; margin: 0px; padding: 0px}
	#map_container{ width: 100%; height: 100%; font-family:Arial}
</style>
(...)
<!-- HTML code -->
<body>
	<div id="map_container"></div>
</body>

 

Puis nous ajoutons le code JavaScript qui va charger la carte dans notre conteneur. Ce code est exécuter lorsque la page est chargée. Nous le déclarons donc dans une fonction qui est le gestionnaire d'évènement du onload de la page. La fonction fondamentale est VMLaunch() car elle sert à instancier tous les services de l'API (l'usage du new est restreint à l'instanciation des objets graphiques). $_id est une fonction utilitaire de l'API permettant de récupérer un élément DOM à partir de son ID.

<!-- HTML code -->
<body onload="fLoadMap();">
(...)
<script type="text/javascript">
  function fLoadMap(){
    VMLaunch("ViaMichelin.Api.Map",{//Service parameters
      //Map container (DOM element)
      container : $_id("map_container"),
      //Initial geographical coordinates of the map center
      center : { coords : {lon: 8.53, lat: 47.38}},	
      //Initial zoom level
      zoom : 11,
      //Display map type selector
      mapTypeControl : true,
      //Display situation map
      situationMapControl : true,
      //Display service POIs selector
      menuPoiControl : true,
     //Display all available service POIS layers
     menuPoiControlOptions:{mode:ViaMichelin.Api.Constants.Map.POI.MODE.ALL}
    }, {//Callbacks
      onInitError: function(){
        alert('Whoops!La carte ne peut pas être chargée!');
      }});
  }
</script>

 

Pour pouvoir fonctionner, votre page doit être présente sur le domaine correspondant à votre clef sinon vous êtes rerouté vers la page d'accueil du site B2C ViaMichelin.

 

Exécuter le tutoriel (tutorial.htm)

 

Pour pouvoir ensuite manipuler la carte, il vous faut récupérer l'instance de la carte dans une variable globale (dans l'exemple: myFirstMap). Pour cela ajoutez un gestionnaire d'évènement sur le onInit. Dans l'exemple ci-dessous nous en profitons pour ajouter également une gestion du click droit sur la carte (onRightClick) en affichant les coordonnées géographiques courantes sous le pointeur de souris.

  var myFirstMap = null;

  function fLoadMap(){
    VMLaunch("ViaMichelin.Api.Map",{
      (...)
    }, {//Callbacks
      onInit: function(serviceMap){
        myFirstMap = serviceMap;
      },
      //Event listener on the right click of the mouse
      onRightClick: function(event){
        //Display current mouse coordinates
        alert("Current coordinates are (" + event.lon.toFixed(5)  + ', ' + event.lat.toFixed(5) + ')');
      }, 
      onInitError: function(){
        alert('Whoops!Map cannot be created!');
    }});
  }
</script>

 

Etape 3 : Créer une application de cartographie web

Jusqu'à présent nous n'avons utilisé que le service de carte de ViaMichelin JavaScript API V2. Nous allons maintenant l'enrichir avec les services de géocodage et de calcul d'itinéraires en écrivant une petite application qui permet de saisir 2 noms de ville en Suisse et de présenter l'itinéraire entre les deux sur la carte.

 

Nous ajoutons d'abord un formulaire qui permet de saisir les noms de nos villes suisses et d'appeler la fonction fLaunchSearchIti() par l'intermédiaire d'un boutton Search.

(...)
<!-- CSS code -->
input{width:150px}
#iti_params{background-color:#fff; position:absolute; top: 35px;left:35px; padding: 5px; opacity:0.6;filter: Alpha(Opacity=60)}
#iti_params:hover{opacity:1.0;filter: Alpha(Opacity=100)}
#iti_distance{font-weight:bold}
.title{text-align:center; font-weight:bold}
(...)	
<!-- HTML code -->	
<div id='iti_params'>
  <div class='title'>Itinerary in Switzerland</div>
  <table>
    <tr><td><label for="departure_city">Departure city:</label></td><td><input type="text" id="departure_city" value="Zurich" /></td></tr>
    <tr><td><label for="arrival_city">Arrival city: </label></td><td><input type="text" id="arrival_city" value="Luzern" /></td></tr>
    <tr><td> </td><td><input type="button" value="Search" onClick="fLaunchSearchIti();"/></td></tr>
</table>
  Distance: <span id="iti_distance"></span>
</div>

 

Le calculateur d'itinéraires prend en entrée uniquement des coordonées géographiques, il est donc nécessaire de géocoder les villes saisies dans un premier temps. Le géocodeur de ViaMichelin JavaScript API V2 accepte de traiter des tableaux d'adresses et appelle le gestionnaire de onSuccess qu'une fois tous les géocodages terminés. On récupère alors un tableau de tableaux respectant l'odre des adresses initiales et permettant la levée d'ambiguité si besoin est.

function fLaunchSearchIti(){
  //reinitialization
  myFirstMap.removeAllLayers();
  document.getElementById("iti_distance").innerHTML = '';
  //Geocode both departure and arrival cities in a same request
  VMLaunch("ViaMichelin.Api.Geocoding", [//Array of address to geocode
      {city: document.getElementById("departure_city").value, countryISOCode: "CHE"},
      {city: document.getElementById("arrival_city").value, countryISOCode: "CHE"}
    ],{//Callbacks
     //Is called when all geocoding have been performed
     onSuccess : function (results) {
       //Store geo coordinates
       var departure_city_coords = results[0][0].coords;
       var arrival_city_coords= results[1][0].coords;
     },
     onError : function (error) {
       alert('Whoops! ' + error);
    }});	
}//fLaunchSearchIti

 

La derniere étape est l'appel au calculateur d'itinéraires en lui passant nos 2 géo-coordonnées comme étapes. Nous transmettons également l'élément DOM de la carte pour présenter le tracé de l'itinéraire. En complément, nous affichons la distance de ce dernier dans le gestionnaire du onSuccess. focus:true ajuste la carte au mieux pour présenter le tracé de l'itinéraire.

//Launch standard itinerary computation (recommanded by VM for cars)
VMLaunch("ViaMichelin.Api.Itinerary", {//Service parameters
    steps:[//Array of Geo coodinates
      {coords: departure_city_coords}, 
      {coords: arrival_city_coords}
    ],
    //Map to display itinerary trace with automatic redraw to fit iti geobounds
    map:{container: $_id("map_container"), focus: true}
  },{//Callbacks
    onSuccess : function (result) {
      //Display distance in Km
      document.getElementById("iti_distance").innerHTML = result.header.summaries[0].totalDist/1000 + 'Km';
    },
    onError : function (error) {
      alert('Whoops! ' + error);
    }});

 

Exécuter le tutoriel (tutorial_2.htm)

 

Vous devriez obtenir un résultat comparable à celui l'image ci-dessous.

tutorial screenshot

 

Et voilà! :) Vous connaissez maintenant les points essentiels de ViaMichelin JavaScript API V2.

Etape 4 : Allez au-delà...

ViaMichelin JavaScript API V2 offre bien d'autres fonctionnalités que vous pouvez explorer au travers des différents exemples et de la documentation de référence.