ViaMichelin Maps & Drive API

ViaMichelin Maps & Drive API vous permet d'insérer directement dans vos propres pages les cartes ViaMichelin ou d'effectuer un calcul d'itinéraire grâce au language de programmation Javascript. Pour pouvoir utiliser ViaMichelin Maps & Drive API, il est nécessaire de s'inscrire avant afin d'obtenir une clé d'identification indispensable à son utilisation.

Quelques informations importantes sur les conditions d'utilisation pour ceux qui ne sont pas familiers avec les termes juridiques :

  • ViaMichelin se réserve le droit d’inclure et d’afficher, à tout moment, toute forme de publicité ou de contenus à caractère publicitaire dans l'offre gratuite ViaMichelin Maps & Drive API, notamment sur les cartes et les itinéraires.
  • L'offre gratuite ViaMichelin Maps & Drive API ne peut être utilisée que sur des sites Internet avec accès public pour les utilisateurs. Toute commercialisation et/ou mise à disposition payante des Services, ou bien en accès privé avec login et mot de passe est strictement interdite.
  • Vous vous engagez à utiliser le service de géocodage uniquement pour une utilisation avec les autres fonctionnalités de ViaMichelin Maps & Drive API.
  • Vous vous engagez à ne pas utiliser des fonctionnalités de calcul d'tinéraires, géocodage et recherche d'hôtels de ViaMichelin avec d'autres services que ceux fournis par l'offre ViaMichelin Maps & Drive API.
  • Vous êtes limités à 10 000 requêtes de cartes ou recherches d'hôtels et 1 000 itinéraires et géocodages sur une période de 24 heures, dans le cadre de l'offre gratuite ViaMichelin Maps & Drive API.
  • Vous devez afficher les Contenus et Services de ViaMichelin exactement de la même façon qu’ils vous sont envoyés et sans modification.
  • ViaMichelin fournit également Maps & Drive API dans une version pour Entreprise, avec plus de contenus et services, sans publicité, un support client local dans 5 pays, en visant toujours l'excellence en terme d'engagement de service. N'hésitez par à contacter ViaMichelin sur le site http://www.viamichelin.fr/business

L'offre ViaMichelin Maps & Drive API est fournie gratuitement. Nous vous recommandons de consulter les conditions d'utilisation de ViaMichelin Maps & Drive API.

Presentation des fonctions principales

La cartographie ViaMichelin

Couvrant plus de 240 pays, vous avez accès à tous les outils et événements pouvant intéragir avec la carte : menus customisés, drag&zoom, zoomin/out, polylines, polygones, layer, cercle, POI markers, info bulle dynamique, avec textes et icônes et plus encore. Sont disponibles à un niveau de précision à la rue plus de 40 pays en Europe, USA , Canada, Brésil, Honk Kong, DomTom, Singapour, soit 90 000 localités cartographiées à la rue et 19 millions de km de route.
Pour plus détails, allez sur la documentation de référence.

Les itinéraires ViaMichelin

Avec étapes, en voiture, à pied, en vélo, les itinéraires ViaMichelin sont devenus une référence. Disponible en Europe et Amérique du nord, le service vous permet de bénéficier des types d'itinéraire suivants : conseillé, court, rapide, économique, agréable, piéton, vélo. Aussi le cout du péage dépend également du type de véhicule sélectionné : voiture, moto, caravane.
De plus, le calcul de la consommation prend en compte la catégorie du véhicule citadine, compacte, familiale, routière, luxe. Pour une intégration parfaite avec votre site, vous pouvez même choisir la couleur, opacité et largeur du tracé sur la carte de l'itinéraire ViaMichelin.
Pour plus détails, allez sur la documentation de référence.

La recherche de plus de 40 000 hôtels en Europe

Basée sur le service de réservation hôtelière du site www.viamichelin.com, cette recherche s'effectue en fonction d'un lieu géographique et de la disponibilité en temps réel des hôtels.

La vérification d'adresse, géocodage et géocodage-inverse sur plus de 40 pays

Géocodage
Cette fonctionnalité vous permet de convertir une adresse en coordonnées géographiques (type WGS84).

Géocodage inverse
Disponible uniquement sur l'offre entreprise ViaMichelin Maps & Drive API
(pour plus d'informations contactez-nous)
Le "géocodage inverse" permet à partir d'une coordonnée géographique de retrouver l'adresse postale.

La possibilité de convertir une coordonnée géographique au format GPS ViaMichelin Navigation.

La recherche de points d'intérêts

Disponible uniquement sur l'offre entreprise ViaMichelin Maps & Drive API
(pour plus d'informations contactez-nous)
A vol d'oiseau, par la route ou par mot clé, selon des critères métiers, cette fonctionnalité offre la possibilité d'effectuer des recherches de proximité directement à partir de vos données hébergées sur les serveurs de ViaMichelin. Les points d'intérêts sont hébergés chez ViaMichelin.

A qui s'adresse ViaMichelin Maps &Drive API?

L'utilisation de ViaMichelin Maps & Drive API nécessite d'avoir des compétences en language Javascript et en programmation orientée objet ainsi que quelques notions dans l'utilisation de services cartographiques.

Comment démarrer?

Pour faire appel aux fonctionnalités de ViaMichelin Maps & Drive API vous devez insérer le tag <script> appelant le fichier javascript de ViaMichelin Maps & Drive API dans votre page HTML (de préférence dans la balise <HEAD></HEAD>).

<script src="http://api.viamichelin.com/apijs/js/api.js"></script>

Il est nécessaire d'obtenir une clé d'identification pour faire appel à l'ensemble des fonctionnalités de ViaMichelin Maps & Drive API. Pour ceci, vous devez aller sur le formulaire d'inscription ou si vous avez déjà un compte Mon ViaMichelin"Mon ViaMichelin" (l'espace personnel du site ViaMichelin.com), connectez-vous ici.

Il est obligatoire d'insérer dans le formulaire d'inscription, le nom de domaine depuis lequel ViaMichelin Maps & Drive API sera appelé. Cela peut être "localhost", "127.0.0.1", "www.monsite.com" ou "admin.monsite.com". Cette information est primordiable pour que ViaMichelin Maps & Drive API puisse fonctionner sinon l'accès sera refusé.
Par exemple si vous développez sur un serveur "en local", que vous appelez par l'URL "http://localhost", vous devez déclarer "localhost" dans les préférences de votre compte ViaMichelin Maps & Drive API.
N.B. Il est impératif d'utiliser ViaMichelin Maps & Drive API sur une page HTML appelée à travers un serveur. Une utilisation hors de ce contexte n'est pas possible. Bien évidemment, il est nécessaire que le javascript soit activé sur le navigateur de l'utilisateur.

Une fois l'inscription validée, nous vous mettons à disposition la clé d'identification unique du type : JSGP20070130151626751375664361

Vous devez insérer cette clé d'identification (de préférence dans la balise <HEAD></HEAD>) dans toutes les pages web qui feront appel à ViaMichelin Maps & Drive API de la manière suivante :

VMAPI.registerKey("JSBS20070130151626751375664361");

La fonctionnalité la plus basique de ViaMichelin Maps & Drive API est d'afficher une carte. Voici le code HTML d'une page permettant d'afficher une carte de largeur 400 pixel et de hauteur 320 pixel centré sur Clermont-Ferrand.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN">
<html>
  <head>
   <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
    <title>ViaMichelin Maps & Drive API</title>
    <script src="http://api.viamichelin.com/apijs/js/api.js" type="text/javascript"></script>
    <script type="text/javascript">
      VMAPI.registerKey("JSBS20070130151626751375664361");
      function affiche() {
        map = new VMMap(document.getElementById("yourmapdiv"));
        map.drawMap(new VMLonLat(1.8996,47.95105),11);
      }	
    </script>
  </head>
  <body onload="affiche()">
    <div id="yourmapdiv" style="width:400px; height:320px"></div>
  </body>
</html>

Vous pouvez copier le code de cet exemple et le tester (pensez à changer la clé d'identification) ou simplement voir le résultat sur cette page : exemple.

Codage, compatibilité

Les navigateurs compatibles avec ViaMichelin Maps & Drive API sont les plus courants et les plus utilisés aujourd'hui. Nous nous efforçons d'apporter le plus de compatibilité possible. Actuellement, les navigateurs sur lesquels nous avons pu tester ViaMichelin Maps & Drive API sont :
- Microsoft Internet Explorer version 6.0 et +
- Firefox 1.5 et +
- Safari 3
- Opera 9 et +

Nous vous conseillons de développer vos pages web contenant ViaMichelin Maps & Drive API conformément aux standards XHTML afin d'avoir le meilleur rendu possible dans les différents navigateurs existants.

De plus pour une meilleure compatibilité avec nos services, il est nécessaire de coder vos pages en UTF-8

Principes de l'API

Composants

Les fonctionnalités de ViaMichelin Maps & Drive API ont été organisées et codées sous forme de composants. Ces composants sont chargés sur votre page automatiquement. Dans la documentation de référence, vous retrouverez l'ensemble des composants de ViaMichelin Maps & Drive API avec les méthodes, les propriétés et les événements associés.

Par exemple, pour afficher une carte, il est nécessaire d'instancier un objet VMMap.

map = new VMMap(document.getElementById("yourmapdiv"));

Ici pour créer un objet de type VMMap (une carte), il est nécessaire d'indiquer en paramètre l'élément du DOM de type <DIV> dans lequel la carte s'affichera.

Méthodes

Les méthodes d'un composant permettent d'effectuer différentes actions ou de récupérer des informations sur l'objet qui a été créé.

map = new VMMap(document.getElementById("yourmapdiv"));
map.drawMap(new VMLonLat(1.8996,47.95105),11);

Dans l'exemple précédent, un objet de type VMMap a été créé. Ici la méthode drawMap() permet d'afficher la carte centrée sur une coordonnée géographique (qui doit toujours être définie dans un objet VMLonLat) et à un certain niveau d'échelle (niveau 11). Les paramètres d'une méthode sont dans la plupart des cas facultatifs avec une valeur par défaut.

Propriétés

Les propriétés d'un objet permettent d'obtenir différentes caractéristiques de ce dernier. Mais dans certain cas, elles permettent aussi de définir certaines de ses caractéristiques. Les propriétés n'ont pas de paramètres.

coords = new VMLonLat(2.334109831366178,48.86142864093333);
latitude_place = coords.lat
longitude_place = coords.lon

Ici les propriétés latitude et longitude de l'objet VMLonLat permettent de récupérer les valeurs de latitude et longitude de ce dernier.

Gestion des événements

La gestion d'événements permet de déclencher des actions (ou fonctions) à un moment déterminé. Les événements sont regroupés par composants et peuvent être initialisés lors de l'appel de certaines méthodes (affichage d'une carte, recherche d'un itinéraire réussie ou non) ou peuvent être liés à un objet.
Si l'événement est lié à une méthode, il est impératif de déclarer l'événement à déclencher avant de lancer la méthode à laquelle la gestion d'événement est liée.

Pour déclarer un événement, il faut utiliser la méthode addEventHandler() avec en paramètre l'action à détecter et la fonction qui doit être réalisée lors de la détection de l'événement.

Dans l'exemple ci-dessous :

map = new VMMap(document.getElementById("yourmapdiv"));
map.drawMap(new VMLonLat(2.334109831366178,48.86142864093333),15);
your_event = map.addEventHandler("onClick",functioneventonclick);

Ici à chaque clic sur la carte, la fonction functioneventonclick() est executée.

Un événement peut être annulé à tout moment grâce à la méthode removeEventHandler().

map.removeEventHandler(your_event);

Détails du fonctionnement des principaux composants

Vous pouvez trouver dans la documentation de référence, la description complète des composants de l'API. Voici rapidement la stuctures et les principes de ces composants.

VMLonLat

Vous utiliserez l'objet VMLonLat très souvent. Il permet de définir une coordonnée géographique avec une latitude et une longitude. L'ensemble des fonctionnalités de ViaMichelin Maps & Drive API doivent être lancées à partir de coordonnées géographiques (afficher une carte, calculer un itinéraire, faire une recherche de proximité etc...).

new VMLonLat(2.334109831366178,48.86142864093333);

Pour d'informations, reportez-vous à la documentation de référence de VMLonLat.

VMMap

Composant principal de l'API, VMMap permet d'afficher et de manipuler une carte ViaMichelin sur votre page.

  • Les cartes ViaMichelin sont organisées sur 17 niveaux d'échelle (de 0 à 16).
  • La méthode principale de cet objet est drawMap(). Elle permet d'afficher une carte à partir de coordonnées géographiques et d'un niveau d'échelle.
    map = new VMMap(document.getElementById("yourmapdiv"));
    map.drawMap(new VMLonLat(2.334109831366178,48.86142864093333),15);
    La taille de la carte sera celle du conteneur HTML dans lequel vous l'insérez.
  • Vous pouvez utiliser des méthodes pour manipuler la carte comme mapZoomIn() qui effectue un zoom sur la carte ou panTo() qui permet d'effectuer un déplacement vers une coordonnée géographique.
    map.mapZoomIn();
    map.panTo(new VMLonLat(2.3387106546572,48.83654657445));
  • Il est aussi possible d'ajouter des outils directement à la carte grâce à la méthode showMapTools() permettant de facilement naviguer sur celle-ci.
    map.showMapTools();
  • La méthode getCenter() permet de connaître les coordonnées géographiques du centre de la carte. 
    map.getCenter();

Pour plus d'informations, reportez-vous à la documentation de référence de VMMap.

VMLayer

Il est nécessaire de créer un objet de type VMLayer pour afficher n'importe quel type d'élément sur la carte. L'objet VMLayer se définit à partir d'une coordonnée géographique pour le positionner sur la carte et de code HTML pour sa représentation. Il existe de nombreux objets héritants du VMLayer, comme :

  • VMIconLayer pour afficher une icône avec une info bulle
  • VMPolyLine pour dessiner une polyligne
  • VMPolygoneShape pour dessiner un polygone
  • VMCircleShape pour dessiner un cercle
  • VMComplexLayer qui est un ensemble de VMLayer

Un VMLayer s'ajoute à une carte en utilisant la méthode de l'objet VMMap, addLayer().

mylayer = new VMCircleShape(new VMLonLat(2.334109831366178,48.86142864093333),150,"#FF0000",3,"#0000FF",0.5);
map.addLayer(mylayer);

Pour plus d'informations, reportez-vous à la documentation de référence de VMLayer.

VMAddress

L'objet VMAddress définit une adresse (rue, ville, code postal...). L'utilisation et la manipulation d'adresse se fait à travers cet objet. Si vous souhaitez afficher la carte correspondant à une adresse, il est nécessaire d'effectuer tout d'abord un géocodage de cette adresse afin d'en obtenir les coordonnées géographiques.

myaddress = new VMAddress();
myaddress.address = "Place des Carmes-Déchaux"; //Adresse
myaddress.zipCode = "63040"; //Code postal
myaddress.city = "CLERMONT-FERRAND"; //Ville
myaddress.country = "FRA"; //Pays

Pour plus d'informations, reportez-vous à la documentation de référence de VMAddress.

VMGeocoder et VMGeosearch

VMGeocoder et VMGeosearch permettent d'effectuer un géocodage d'adresse. Mais une adresse saisie peut être ambiguë, c'est à dire que le moteur de reconnaissance toponymique de ViaMichelin vous propose plusieurs possibilités par rapport à l'adresse entrée.

  • VMGeocoder est un géocodage simple. Seules les coordonnées géographiques du premier résultat trouvé vous sont renvoyées sous forme d'un VMLonLat 
    geocoder = new VMGeocoder();


myaddress = new VMAddress();
    myaddress.address = "Place des Carmes-D?chaux"; //Adresse
    myaddress.zipCode = "63040"; //Code postal
    myaddress.city = "CLERMONT-FERRAND"; //Ville
    myaddress.country = "FRA"; //Pays

geocoder.search(myaddress);

your_coordinates = geocoder.result;
  • VMGeoSearch au contraire vous renvoie l'ensemble des possibilités sous forme d'un tableau de VMAddress. Il est donc possible ensuite de parcourir cette liste afin de pouvoir choisir l'adresse correspondant à sa requête. 
    geocoder = new VMGeocoder();


myaddress = new VMAddress();
    myaddress.city = "Paris"; //Ville
    
geosearch.search(myaddress);

list_of_result = geosearch.results;

Pour plus d'informations, reportez-vous à la documentation de référence de VMGeocoder et VMGeoSearch.

VMItinerary

VMItinerary vous permet d'effectuer des calculs d'itinéraire entre 2 coordonnées géographiques. Il est aussi possible d'y insérer 3 étapes intermédiaires supplémentaires.
Vous pouvez définir de nombreux paramètres au calcul d'itinéraire grâce aux méthodes de l'objet VMItinerary. Ces paramètres doivent bien sûr être définis avant la demande de calcul.

  • addStopOver() : Ajoute un point de passage de votre itinéraire (départ, arrivée ou étape)
  • setItineraryType() : Définit le type d'itinéraire qui sera calculé par ViaMichelin. Les itinéraires disponibles sont "Conseillé", "Court", "Rapide", "Pieton", "Vélo" etc...
  • setItineraryVehiculeType() : Définit si le type de véhicule utilisé est une voiture, une moto ou une voiture avec un caravane.
  • setCarType() : Définit le type de véhicule si ce dernier est une voiture.
  • setFuelType() : Définit le carburant du véhicule si ce dernier est une voiture.
  • setFuelCost() : Vous permet de définir le prix du carburant en Euro. 
    myiti.addStopOver(new VMLonLat(2.334109831366178,48.86142864093333)); //Départ
    myiti.addStopOver(new VMLonLat(2.5488422,46.76554422)); //Etape
    myiti.addStopOver(new VMLonLat(2.45575546,47.456546864)); //Arrivée		
    		
    myiti.setItineraryType(0); //Type d'itinéraire
    myiti.setItineraryVehiculeType(0); //Type de véhicule
    myiti.setCarType(1); //Catégorie de véhicule (si voiture)
    myiti.setFuelType(1); //Type de carburant (si voiture)
    myiti.setFuelCost(1.1); //Coût du carburant en euro
    		
    myiti.search();

Tous ces paramètres sont facultatifs. Ils vous permettront d'avoir un calcul d'itinéraire au plus juste et de connaître une estimation du coût de votre trajet.

Quand l'itinéraire est calculé, vous pouvez récupérer et afficher de nombreuses informations grâce aux méthodes suivantes :

  • getTotalDistance() : Distance totale de l'itinéraire
  • getTotalTime() : Temps total de l'itinéraire
  • getTotalGasConsumption() : Coût du carburant en €
  • getTollCost() : Coût du péage en €
  • roadSheet.getHTML() : Code HTML complet de la feuille de route
  • getItiAsVMComplexLayer() : Objet de type VMLayer pour afficher l'ensemble des informations de l'itinéraire sur une carte
myiti.roadSheet.getHTML(); //Code HTML complet de la feuille de route
myiti.getItiAsVMComplexLayer("#FF0000",7,0.5); //Calque complet de l'itinéraire

myiti.getTotalDistance(); //Distance totale en mètre
myiti.getDistanceOnMotorway(); //Distance parcourue sur autoroute
myiti.getTotalTime(); //Temps total en seconde
myiti.getTimeOnMotorway(); //Temps de parcours sur autoroute
myiti.getTotalGasConsumption(); //Cout consommation carburant
myiti.getTollCost(); //Cout péage autoroute
myiti.getRoadTaxCost(); //Cout vignette

Pour d'informations, reportez-vous à la documentation de référence de VMItinerary.

VMPOI, VMPOISearch

Disponible uniquement sur l'offre entreprise ViaMichelin Maps & Drive API
(pour plus d'informations contactez-nous)

Il est possible d'effectuer une recherche de proximité de POI (Points d'intérêt) à vol d'oiseau, par la route ou par recherche textuelle. Pour ceci, vous devez indexer votre base de POI sur les serveurs de ViaMichelin.

Un POI se définit dans un objet de type VMPOI. Un ensemble ou une liste de VMPOI doit être stocké dans un objet de type VMPOIList.

Pour effectuer une recherche de proximité autour d'un lieu, il est d'abord nécessaire de connaître l'ensemble des informations sur votre base de POI chez ViaMichelin. Donc préalablement vous devez récupérer ces informations (ou "POI Définiton") grâce à la méthode getDefiniton() de l'objet VMPOIDefinition (en passant en paramètre l'identifiant de la base). 

poiDefinition = new VMPOIDefinition();
poiDefinition.getDefiniton("61195");

L'ensembles des critères définissants vos POIs sont insérés dans cet objet dans la propriété criterias qui est un tableau d'objet de type VMCriteria. Si vous souhaitez faire une recherche de proximité en prenant en compte certains critères, il est nécessaire de les définir dans le VMPOIDefinition grâce à la méthode setCriteria().

poiDefinition.setCriteria(1,3,true);
//Ici le sous-critère 3 du critère 1 est sélectionné

Il vous suffit donc ensuite d'instancier un objet VMPOISearch avec la "POI Définition" que vous venez de définir. La méthode search() prennant en paramètre les coordonnées géographiques du centre de la recherche, lance la recherche de proximité.

myPOIsearch = new VMPOISearch(poiDefinition);
myPOIsearch.search(new VMLonLat(2.41544,48.546544));
//La recherche se fait autour de la coordonnée géographique (2.41544,48.546544)

En réponse, vous récupérez dans la propriété results, un objet de type VMPOIList. Ce dernier comporte une propriété pois, qui est un tableau de VMPOI. Plusieurs méthodes vous permettent d'afficher simplement le résultat sous forme HTML ou sur une carte.

myPOIlist = myPOIsearch.result;
POIList_HTML = myPOIlist.getHTML();
POIList_Layer = myPOIlist.getLayer();

Pour d'informations, reportez-vous à la documentation de référence de VMPOI, VMPOISearch et VMPOIDefinition.