VIAMICHELIN REST API


Tutoriel

Objectif

L'objectif de ce tutoriel est de vous guider dans l'utilisation de ViaMichelin REST API, grâce à divers exemples de requêtes.

Audience

Ce tutoriel s'adresse à des développeurs connaissant les principes fondamentaux du web comme l'architecture client-serveur, le protocole HTTP, le langage XML et/ou JSON, ainsi qu'un langage de développement (PHP, Java, ASP.NET, JavaScript, Flash, Objective-C,...).

Pré-requis

  • Un éditeur de texte suffit mais un atelier de développement logiciel (IDE) est conseillé
  • Un navigateur web
  • Si le mode d'accès dit serveur est retenu (voir la section suivante): un serveur web (Apache, Tomcat, Websphere, JBoss,...) avec une librairie permettant d'effectuer des requêtes HTTP (cURL pour PHP,...) et la signature de requêtes (Hash pour PHP,...).
  • Si le mode d'accès dit hybride est retenu (voir la section suivante): un serveur web avec une librairie permettant d'effectuer des requêtes HTTPS et HTTP (cURL pour PHP,...).

Modes d'accès aux services et authentification

Il est possible d'utiliser les services ViaMichelin dans 3 modes différents:

  • un mode serveur si les requêtes vers l'API REST de ViaMichelin sont émises par un serveur web,
  • un mode client si ces mêmes requêtes sont émises par un poste client ou un mobile,
  • un mode hybride si les échanges sont initiés par un serveur web puis gérés directement par le poste client ou mobile.

 

Accès en mode serveur

C'est le mode d'accès le plus sécurisé aux services ViaMichelin et donc le plus recommandé.

 

Schéma des échanges

 

Le flux des échanges est le suivant:

  • (1) Depuis son poste client, un utilisateur initie un appel à vos services en appelant votre serveur web.
  • (2) Votre serveur fait appel à un ou plusieurs services disponibles dans ViaMichelin REST API. A chaque appel,
    • le paramètre d'url authKey est valorisé avec votre identifiant client unique transmis par ViaMichelin,
    • le paramètre signature est valorisé avec la signature (encodée en base 64) de la requête générée en utilisant l'algorithme HMAC-SHA1 (où la clef est votre mot de passe transmis par ViaMichelin),
    • et le paramètre expires est valorisé avec la date souhaitée d'expiration de la requête.

     

    Exemple d'URL :http://apir.viamichelin.com/apir/1/geocode4F.json?country=FRA&address=rue+des+Edelweiss&city=Annecy&authKey=MY_ID&expires=2010-06-09T16:30:00&signature=d85aa2ce704bd1b4120069b4d9761592b8cf5ec8
    Dans l'exemple ci-dessus, la signature correspond à l'encodage de :/apir/1/geocode4F.json?country=FRA&address=rue+des+Edelweiss&city=Annecy&authKey=MY_ID&expires=2010-06-09T16:30:00

    Note : le domaine web ne doit pas être considéré dans la chaîne à encoder.

  • (3) ViaMichelin retourne une réponse, en ayant au préalable vérifié que :
    • la requête provient bien de votre serveur (dont l'IP aura été pré-déclarée),
    • le délai d'expiration n'est pas dépassé,
    • la signature est valide,
    • vos droits d'accès (qui dépendent de votre contrat commercial) sont valides.
  • (4) Votre serveur retourne la réponse à la requête initiale (après avoir éventuellement retraité la réponse brute de ViaMichelin).
  •  

    Les languages les plus courants proposent nativement les fonctions de signature de requêtes : hash_hmac de la librairie hash en PHP, Le package java.security en Java.

    Accès en mode hybride (serveur + client)

    Ce mode d'accès est moins sécurisé que le mode serveur, mais qui offre un bon compromis entre sécurisation et souplesse d'utilisation. Il est parfaitement adapté aux clients souhaitant mettre à disposition un produit logiciel qu'un utilisateur vient récupérer sur le serveur avant usage, comme du code JavaScript ou Flash dans une page web.

     

    Schéma des échanges

     

    Le flux des échanges est le suivant :

  • (1) Depuis son poste client ou son mobile, un utilisateur demande le téléchargement de votre application ou librairie en appelant votre serveur web.
  • (2) Votre serveur requête un jeton auprès de ViaMichelin en faisant appel au service token mis à disposition et en transmettant votre identifiant client unique et votre mot de passe préalablement fournis par ViaMichelin.

     

    Exemple d'URL : https://apir.viamichelin.com/apir/1/token.xml?login=MY_ID&password=MY_PASSWORD

    Note : ce service est accessible exclusivement sur le protocole sécurisé HTTPS.

  • (3) ViaMichelin contrôle que la requête provient bien de votre serveur (dont l'IP aura été pré-déclarée) avant de retourner le jeton. Ce dernier a une durée de vie limitée paramétrable (voir documentation du service token).
  • (4) Votre serveur retourne le jeton à l'utilisateur directement dans le code de l'application ou de la librairie.
  • (5) L'utilisateur appelle directement les services ViaMichelin en valorisant le paramètre d'url authKey avec le jeton.
  • (6) ViaMichelin contrôle la validité du jeton et vos droits d'accès (qui dépendent de votre contrat commercial) avant de retourner la réponse. Une trace de facturation est alors générée.
  • Accès en mode client

    Ce mode d'accès est le moins sécurisé, mais il offre la plus grande souplesse d'accès aux services ViaMichelin. Il est destiné aux clients qui veulent s'affranchir des coûts de maintien d'un serveur web.

     

    Schéma des échanges

     

    Le flux des échanges est le suivant :

  • (0) Votre serveur transmet la clef d'identification client unique préalablement transmise par ViaMichelin. Cette étape est optionnelle. Si vous n'avez pas de serveur, la clef peut-être embarquée directement dans l'application.
  • (1) Depuis son poste client ou son mobile, l'utilisateur appelle directement les services ViaMichelin en valorisant le paramètre d'url authKey avec la clef d'identification.
  • (2) ViaMichelin contrôle la validité de la clef et vos droits d'accès (qui dépendent de votre contrat commercial) avant de retourner la réponse. Une trace de facturation est alors générée.
  • Les principes de l'API

    Les ressources et identifiants uniques

    ViaMichelin REST API permet d'accéder à des ressources et de les manipuler. Ces ressources se caractérisent toutes par un identifiant unique. Chaque domaine métier permet d'accéder à une ressource de type spécifique que les fonctions des autres domaines métiers peuvent parfois prendre en paramètre d'entrée au travers de cet identifiant unique.

    Domaine métierRessource principaleIdentifiant unique
    Recherche de proximité POI couple (dbID, poiID)
    Géocodage Lieu locID
    Cartographie Carte mapID
    Itinéraire Itinéraire itiID

    Aucun de ces identifiants de ressources ne doit être considérés comme pérenne au delà d'une session utilisateur. Il est donc fortement recommandé de ne pas les sauvegarder dans une base de données pour un usage ultérieur.

    Les paramètres

    L'accès aux différents services de l'API REST de ViaMichelin se fait au travers d'une url en positionnant les paramètres, soit dans le chemin d'accès, soit en paramètres de type GET suivant leur importance dans la définition ou dans la manipulation de la ressource accédée. Ces paramètres peuvent-être de 4 types différents dés ci-dessous.

    Type de paramètreFormatExemplesExemples d'usages
    mono-valué ...&clef=valeur...
    ou .../valeur/...
    ...&cityzip=75012...
    .../fra/...
    très courant
    multi-sous-paramétré ...&clef=valeurA:valeurB...
    ou .../valeurA:valeurB/...
    ...&center=2.0:48.0...
    .../800:600/...
    • Coordonnées géographiques
    • Tailles de cartes
    multi-valué ...&clef=valeur1;valeur2...
    ou.../valeur1;valeur2/...
    .../2.0;48.0;3.0;49.0/...
    • Emprise de cartes
    multi-valué et multi-sous-paramétré ...&clef=valeur1A:valeur1B;valeur2A:valeur2B...
    ou .../valeur1A:valeur1B;valeur2A:valeur2B/...
    .../2.0:48.0;12/...
    • Centres de cartes
    • Etapes d'itinéraires
    • Listes de POI

    Dans les URL, le nom des services et des paramètres est insensible à la casse, mais le plus souvent la valeur de ces même paramètres est sensible à la casse.

    Exemple d'utilisation

    Géocodeur + carte

    L'exemple ci-dessous présente comment récupérer une carte centrée sur une adresse postale (10 promenade des Anglais 06000 Nice). Ce cas d'étude permet d'enchaîner 3 requêtes métiers : la première au service de géolocalisation pour récupérer l'id unique (LocID) de l'adresse postale; puis la seconde au service de carte pour récupérer les méta-données de la carte centrée sur le LocID précédemment obtenues; enfin la dernière requête permet d'accéder à la carte proprement dite.

     

    Si le mode d'accès est hybride, une requête technique préalable côté serveur est nécessaire pour récupérer le jeton (cf. section précédente). Dans le flux de donné retournées, le jeton se trouve dans le chemin response->token. Nous l'appellerons MY_TOKEN dans la suite.

    	//Appel en mode hybride
    	https://apir.viamichelin.com/apir/1/token.xml?login=MY_ID&password=MY_PASSWORD
    				

    La première requête métier permet de récupérer le locid de l'adresse postale grâce à la fonction Geocode. Dans le flux de données retourné, le locID se trouve dans le chemin response->locationList->item[0]->location->id. Nous l'appellerons MY_LOCID dans la suite.

    	//Appel en mode serveur
    	http://apir.viamichelin.com/apir/1/geocode4f.xml?country=fra&city=nice&address=10%20promenade%20des%20anglais&authkey=MY_ID &expires=EXPIRATION_DATE&signature=REQUEST_SIGNATURE
    
    	//Appel en mode hybride
    	http://apir.viamichelin.com/apir/1/geocode4f.xml?country=fra&city=nice&address=10%20promenade%20des%20anglais&authkey=MY_TOKEN
    
    	//Appel en mode client
    	http://apir.viamichelin.com/apir/1/geocode4f.xml?country=fra&city=nice&address=10%20promenade%20des%20anglais&authkey=MY_KEY
    			

    La deuxième requête métier permet de récupérer l'url de la carte de taille 800px * 600px centrée sur MY_LOCID grâce à la fonction MapOfPlace. Dans le flux de données retourné contenant tout un ensemble de métadonnées sur la carte, l'url se trouve dans le chemin response->map->url. Nous l'appellerons MY_MAP_URL dans la suite.

    	//Appel en mode serveur
    	http://apir.viamichelin.com/apir/1/mapofplace.xml/MY_LOCID/800:600?authkey=MY_ID&expires=EXPIRATION_DATE&signature=REQUEST_SIGNATURE
    
    	//Appel en mode hybride
    	http://apir.viamichelin.com/apir/1/mapofplace.xml/MY_LOCID/800:600?authkey=MY_TOKEN
    
    	//Appel en mode client
    	http://apir.viamichelin.com/apir/1/mapofplace.xml/MY_LOCID/800:600?authkey=MY_KEY
    			

    Notez que la carte générée à un identifiant unique mapID disponible dans le chemin response->map->id. Cet identifiant de carte peut être utilisé avec les fonctions XYtoPixels ou pixelsToXY pour convertir des coordonnées géographiques en coordonnées pixels sur l'image et inversement. Vous pouvez ainsi ajouter des données géographiques complémentaires sur la carte retournée.

    La dernière requête métier permet de récupérer la carte proprement dite sous forme d'une image. Cette requête, comme toutes celles d'accès direct aux cartes, ne nécessite pas d'authentification.

    	//Appel en mode serveur
    	MY_MAP_URL
    
    	//Appel en mode hybride
    	MY_MAP_URL
    
    	//Appel en mode client
    	MY_MAP_URL
    			
    Géocodeur + recherche de proximité + carte

    Ce cas est un enrichissement du précédent : il permet de rechercher le POI le plus proche d'une adresse postale (10 promenade des Anglais 06000 Nice). Ce cas permet d'enchaîner 4 requêtes métiers: la première au service de géolocalisation pour récupérer les coordonnées géographiques de l'adresse postale, la seconde au service de recherche de proximité pour récupérer l'id unique du POI (dbid,poiid) le plus proche par la route de ces coordonnées, la troisième au service de carte pour récupérer les méta-données de la carte centrée sur le POI. Enfin la dernière requête permet d'accéder à la carte proprement dite.

     

    La première requête métier permet de récupérer le couple (latitude, longitude) de l'adresse postale grâce à la fonction Geocode. Dans le flux de données retourné, les coordonées se trouve dans le chemin response->locationList->item[0]->location->lat et ->lon. Nous les appellerons MY_LON:MY_LAT dans la suite.

    	//Appel en mode serveur
    	http://apir.viamichelin.com/apir/1/geocode4f.xml?country=fra&city=nice&address=10%20promenade%20des%20anglais&authkey=MY_ID &expires=EXPIRATION_DATE&signature=REQUEST_SIGNATURE
    
    	//Appel en mode hybride
    	http://apir.viamichelin.com/apir/1/geocode4f.xml?country=fra&city=nice&address=10%20promenade%20des%20anglais&authkey=MY_TOKEN
    
    	//Appel en mode client
    	http://apir.viamichelin.com/apir/1/geocode4f.xml?country=fra&city=nice&address=10%20promenade%20des%20anglais&authkey=MY_KEY
    			

    La deuxième requête métier permet de récupérer, grâce à la fonction FindPOIByRoad, le POI (contenu dans la base MY_DB) le plus proche par la route de MY_LAT:MY_LON. Dans le flux de données retourné l'id du POI se trouve dans le chemin response->poiList->item[0]->poi->id. Nous l'appellerons MY_POIID dans la suite.

    	//Appel en mode serveur
    	http://apir.viamichelin.com/apir/1/findpoibyroad.xml?db=MY_DB&lg=FRA&center=MY_LON%3AMY_LAT?authkey=MY_ID&expires=EXPIRATION_DATE&signature=REQUEST_SIGNATURE
    
    	//Appel en mode hybride
    	http://apir.viamichelin.com/apir/1/findpoibyroad.xml?db=MY_DB&lg=FRA&center=MY_LON%3AMY_LAT?authkey=MY_TOKEN
    
    	//Appel en mode client
    	http://apir.viamichelin.com/apir/1/findpoibyroad.xml?db=MY_DB&lg=FRA&center=MY_LON%3AMY_LAT?authkey=MY_KEY
    			

    La troisième requête métier permet de récupérer l'url de la carte de taille 800px * 600px centrée sur MY_POIID grâce à la fonction MapOfPOI. Dans le flux de données retourné contenant tout un ensemble de métadonnées sur la carte, l'url se trouve dans le chemin response->map->url. Nous l'appellerons MY_MAP_URL dans la suite.

    	//Appel en mode serveur
    	http://apir.viamichelin.com/apir/1/mapofpoi.xml/MY_DB:MY_POIID/800:600/FRA?authkey=MY_ID&expires=EXPIRATION_DATE&signature=REQUEST_SIGNATURE
    
    	//Appel en mode hybride
    	http://apir.viamichelin.com/apir/1/mapofpoi.xml/MY_DB:MY_POIID/800:600/FRA?authkey=MY_TOKEN
    
    	//Appel en mode client
    	http://apir.viamichelin.com/apir/1/mapofpoi.xml/MY_DB:MY_POIID/800:600/FRA?authkey=MY_KEY
    			

    L'ultime requête est identique à celle du cas d'étude précédent.

    Géocodeur + recherche de proximité + calcul d'itinéraire + carte

    Ce cas est également un enrichissement du précédent : il permet de présenter sur une carte l'itinéraire pour rejoindre le POI le plus prêt d'une adresse postale (100 promenade des Anglais 06000 Nice) en enchaînant 5 requêtes métiers: la première au service de géolocalisation pour récupérer les coordonnées géographiques de l'adresse postale, la seconde au service de recherche de proximité pour récupérer l'id unique du POI (dbid,poiid) le plus proche par la route de ces coordonnées, la troisième au service d'itinéraire pour récupérer la trace de l'itinéraire entre l'adresse et le POI, la quatrième au service de carte pour récupérer les méta-données de la carte contenant l'itinéraire. Enfin la dernière requête permet d'accéder à la carte proprement dite.

     

    Les 2 premières requêtes sont identiques à celles du cas précédent.

     

    La troisième requête métier permet de récupérer à la fois la trace de l'itinéraire entre MY_LOCID et MY_POIID et les informations sur la meilleure carte pour l'afficher grâce à la fonction Route. Dans le flux de données retourné contenant tout un ensemble de données sur l'itinéraire, la trace se trouve dans le chemin response->iti->itineraryTrace (nous l'appellerons MY_ITI_TRACE dans la suite) et les informations de carte dans le chemin response->header->summaries->summary[0]->fullMapDef (nous les appellerons MY_MAPID, MY_WIDTH et MY_HEIGHT dans la suite).

    	//Appel en mode serveur
    	http://apir.viamichelin.com/apir/1/route.xml/FRA/?steps=3:e:MY_LOCID;2:e:MY_DB:MY_POIID&authkey=MY_ID&expires=EXPIRATION_DATE&signature=REQUEST_SIGNATURE
    
    	//Appel en mode hybride
    	http://apir.viamichelin.com/apir/1/route.xml/FRA/?steps=3:e:MY_LOCID;2:e:MY_DB:MY_POIID&authkey=MY_TOKEN
    
    	//Appel en mode client
    	http://apir.viamichelin.com/apir/1/route.xml/FRA/?steps=3:e:MY_LOCID;2:e:MY_DB:MY_POIID&authkey=MY_KEY
    			

    La quatrème requête métier permet de récupérer l'url de la carte de taille MY_WIDTH * MY_HEIGHT d'identifiant MY_MAPID et contenant MY_ITI_TRACE grâce à la fonction mapById. Dans le flux de données retourné contenant tout un ensemble de métadonnées sur la carte, l'url se trouve dans le chemin response->map->url. Nous l'appellerons MY_MAP_URL dans la suite.

    	//Appel en mode serveur
    	http://apir.viamichelin.com/apir/1/mapbyid.xml/MY_MAPID/MY_WIDTH:MY_HEIGHT/fra?authkey=MY_ID&expires=EXPIRATION_DATE&signature=REQUEST_SIGNATURE
    
    	//Appel en mode hybride
    	http://apir.viamichelin.com/apir/1/MY_MAPID/MY_WIDTH:MY_HEIGHT/fra?authkey=MY_TOKEN
    
    	//Appel en mode client
    	http://apir.viamichelin.com/apir/1/MY_MAPID/MY_WIDTH:MY_HEIGHT/fra?authkey=MY_KEY
    	
    	//Dans les 3 cas, MY_ITI_TRACE passé en POST dans le paramètre iti_trace.
    			

    L'ultime requête est identique à celle du premier cas décrit.