VIAMICHELIN REST API


Tutorial

Objective

The objective of this tutorial is to guide you in using ViaMichelin REST API, with specific examples made in different computer languages.

Audience

This tutorial is aimed at developers with a good knowledge of basic web principles (client / server architecture, HTTP, XML and / or JSON) and of a development language (PHP, Java, ASP.NET, JavaScript, Flash, Objective-C, etc.).

Prerequisites

  • Although a text editor is sufficient, a software development environment (IDE) is recommended
  • Web browser
  • If the server access mode is used (see next section): a web server (Apache Tomcat, Websphere, JBoss, ...) with a library allowing the execution of HTTP requests (cURL for PHP,...) and requests signing (Hash for PHP ,...).
  • If the hybrid access mode is used (see next section): a web server with a library allowing the execution of HTTPS and HTTP requests (cURL for PHP, ...).

Access modes and authentication

ViaMichelin services can be used with three different access modes: :

  • server mode, if requests to the ViaMichelin REST API are issued by a web server
  • client mode if the same requests are issued by a client station or a mobile phone
  • hybrid mode if the trade is initiated by a web server and then managed directly by the client station or mobile phone

 

Server access mode

This is the most secure access mode to ViaMichelin services therefore it is the most recommended.

 

Workflow in server access mode

 

The trade flow is as follows:

  • (1) The user initiates a call from his client station to your service by calling your web server.
  • (2) Your server calls one or more of the services available through ViaMichelin REST API. For each call,
    • the URL parameter authKey is assigned with your unique customer ID transmitted by ViaMichelin,
    • the URL parameter signature receives the signature (encoded in base 64) of the generated request using the HMAC-SHA1 algorithm (where the key is your password provided by ViaMichelin),
    • and URL parameter expires is valued with the desired expiration date of the request.

     

    URL sample: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 Here the signature corresponds to the encoding of :/apir/1/geocode4F.json?country=FRA&address=rue+des+Edelweiss&city=Annecy&authKey=MY_ID&expires=2010-06-09T16:30:00

    Note: web domain must not be used to sign the request.

  • (3) ViaMichelin returns a workable response if
    • the request comes from your very server (with pre-specified IP)
    • the timeout has not expired
    • the signature is valid
    • your access rights (dependent on your commercial contract) are valid
  • (4) Your server returns the response to the initial request (possibly after processing the raw result returned by ViaMichelin service).
  •  

    The most common languages provide native functions for generating signatures: hash_hmac in hash library for PHP, java.security package in Java.

    Hybrid access mode (server + client)

    This access mode is less secure than the previous one but offers a good compromise between security and flexibility. It is ideal for customers wishing to make a software product just downloaded from the server available before being used, such as JavaScript code or a Flash application in a web page.

     

    Workflow in hybrid access mode

     

    The trade flow is as follows:

  • (1) A user initiates a call from their client station to your service by calling your web server.
  • (2)Your server requests a token from the ViaMichelin token service using your unique customer ID and password provided by ViaMichelin.

     

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

    Note: this service is available only over HTTPS protocol.

  • (3) ViaMichelin confirms that the request comes from your server (using the predefined IP) before returning the token. The token has a limited configurable lifetime (see token service documentation).
  • (4) Your server returns the token to the user directly in the application code or library.
  • (5) Your user calls directly ViaMichelin services directly using the token value to the authKey parameter.
  • (6) ViaMichelin checks the validity of the token and your access rights (depending on your commercial contract) before responding. A billing record is then generated.
  • Client access mode

    This access mode is the least secure but offers the greatest access flexibility for ViaMichelin services. It is mainly designed for customers looking to bypass the costs of maintaining a web server.

     

    Workflow in client access mode

     

    The trade flow is as follows:

  • (0) Your server sends your client identification key previously transmitted by ViaMichelin. This step is optional. If you don't have a server, the key may be embedded directly into the application.
  • (1) The user calls ViaMichelin services directly from their client station or mobile phone, using the identification key as the value for the authKey URL parameter.
  • (2) ViaMichelin checks the validity of the key and your access rights (depending on your commercial contract) before returning the response. A billing record is then generated.
  • API principles

    Resources and unique identifiers

    The ViaMichelin REST API provides access to resources that are all characterized by a unique identifier. Each business domain provides access to a specific type of resources that can sometimes be accepted as input parameters of other business domain functions through their unique identifier.

    Business domainMain resource typeUnique identifier
    Proximity search POI (dbID, poiID) pair
    Geocoding Place locID
    Mapping Map mapID
    Itinerary Route itiID

    None of these identifier resources should be considered sustainable beyond a user session. It is strongly recommended that they are NOT tsaved in a database for later use.

    Parameters

    Access to all ViaMichelin REST API services is performed through URL by setting parameters either in the path or in GET, according to their importance in the definition or in the handling of the resource. There are 4 different parameter types:

    Parameter typeFormatSampleUse
    single-value ...&key=value...
    ou .../value/...
    ...&cityzip=75012...
    .../fra/...
    very common
    Subset ...&key=valueA:valueB...
    ou .../valueA:valueB/...
    ...&center=2.0:48.0...
    .../800:600/...
    • geo-coordinates
    • map dimensions
    multi-value ...&key=value1;value2...
    ou.../value1;value2/...
    .../2.0;48.0;3.0;49.0/...
    • geo-bounds
    multi-value & multi-subset ...&key=value1A:value1B;value2A:value2B...
    ou .../value1A:value1B;value2A:value2B/...
    .../2.0:48.0;12/...
    • Map center
    • Itinerary steps
    • POI lists

    In URL, Service names and parameter names are case insensitive but more often than not parameter values are case sensitive.

    Case studies

    Geocoding + maps

    The example below shows how to retrieve a map centered on a mailing address (10 promenade des Anglais 06000 Nice). This case study enables linking 3 back-to-back queries: the first query to the location service to retrieve the unique id (LocID) of the mailing address; the second to the map service to retrieve the metadata map centered on the previously obtained LocID; and finally the query to access to the map itself.

     

    If the hybrid access mode is used, a server-side technical request is first required to retrieve the token (see previous section). The token can be found in the response stream at response->token. Let's call it MY_TOKEN.

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

    The first query retrieves the locid of the mailing address through the Geocode service. In the response stream, the locid can be found at response->locationList->item[0]->location->id. Let's call it MY_LOCID.

    	//Access in server mode
    	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
    
    	//Access in hybrid mode
    	http://apir.viamichelin.com/apir/1/geocode4f.xml?country=fra&city=nice&address=10%20promenade%20des%20anglais&authkey=MY_TOKEN
    
    	//Access in client mode
    	http://apir.viamichelin.com/apir/1/geocode4f.xml?country=fra&city=nice&address=10%20promenade%20des%20anglais&authkey=MY_KEY
    			

    The second query retrieves metadadata about the 800px*600px map centered on MY_LOCID through the MapOfPlace service. In the response stream, the map url can be found at response->map->url. Let's call it MY_MAP_URL.

    	//Access in server mode
    	http://apir.viamichelin.com/apir/1/mapofplace.xml/MY_LOCID/800:600?authkey=MY_ID&expires=EXPIRATION_DATE&signature=REQUEST_SIGNATURE
    
    	//Access in hybrid mode
    	http://apir.viamichelin.com/apir/1/mapofplace.xml/MY_LOCID/800:600?authkey=MY_TOKEN
    
    	//Access in client mode
    	http://apir.viamichelin.com/apir/1/mapofplace.xml/MY_LOCID/800:600?authkey=MY_KEY
    			

    Note that the generated map has a unique identifier mapID available at response->map->id. This id can be used with XYtoPixels and pixelsToXY services to convert geo-coordinates to pixel coordinates and vice versa. You can then draw complementary geodata on the map.

    The last query retrieves the map as an image and does not require authentication.

    	//Access in server mode
    	MY_MAP_URL
    
    	//Access in hybrid mode
    	MY_MAP_URL
    
    	//Access in client mode
    	MY_MAP_URL
    			

     

    Geocoding + proximity search + map

    This case study is an upgrade of the previous example to display the access map of the nearest POI to a postal address (10 promenade des Anglais 06000 Nice) by linking 4 back-to-back queries: the first query to the location service to retrieve the geocoordinates of the mailing address; the second to the proximity search service to retrieve the (dbid,poiid) pair of the closest POI from the previously found geocoordinates; the third to the mapping service to retrieve the metadata map centered on the previously obtained (dbid,poiid); and finally the last query to access to the map itself.

     

    The first query retrieves the geo-coordinates (latitude, longitude) of a mailing address via the Geocode service. They can be found in the response stream at response->locationList->item[0]->location->lat and ->lon. Let's call them MY_LON:MY_LAT.

    	//Access in server mode
    	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
    
    	//Access in hybrid mode
    	http://apir.viamichelin.com/apir/1/geocode4f.xml?country=fra&city=nice&address=10%20promenade%20des%20anglais&authkey=MY_TOKEN
    
    	//Access in client mode
    	http://apir.viamichelin.com/apir/1/geocode4f.xml?country=fra&city=nice&address=10%20promenade%20des%20anglais&authkey=MY_KEY
    			

    The second query retrieves the closest POI by road (in MY_DB database) from MY_LAT:MY_LON through the FindPOIByRoad service. The POI id can be found in the response stream at response->poiList->item[0]->poi->id. let's call it MY_POIID.

    	//Access in server mode
    	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
    
    	//Access in hybrid mode
    	http://apir.viamichelin.com/apir/1/findpoibyroad.xml?db=MY_DB&lg=FRA&center=MY_LON%3AMY_LAT?authkey=MY_TOKEN
    
    	//Access in client mode
    	http://apir.viamichelin.com/apir/1/findpoibyroad.xml?db=MY_DB&lg=FRA&center=MY_LON%3AMY_LAT?authkey=MY_KEY
    			

    The third query retrieves metadadata relating to the 800px*600px map centered on MY_POIID through the MapOfPOI service. The map url can be found in the response stream at response->map->url. Let's call it MY_MAP_URL.

     

    	//Access in server mode
    	http://apir.viamichelin.com/apir/1/mapofpoi.xml/MY_DB:MY_POIID/800:600/FRA?authkey=MY_ID&expires=EXPIRATION_DATE&signature=REQUEST_SIGNATURE
    
    	//Access in hybrid mode
    	http://apir.viamichelin.com/apir/1/mapofpoi.xml/MY_DB:MY_POIID/800:600/FRA?authkey=MY_TOKEN
    
    	//Access in client mode
    	http://apir.viamichelin.com/apir/1/mapofpoi.xml/MY_DB:MY_POIID/800:600/FRA?authkey=MY_KEY
    			

    The ultimate query is identical to that of the previous case study.

     

    Geocoding + proximity search + route planning + map

    This case study is also an upgrade of the previous one to display the best route between a postal address (100 promenade des Anglais 06000 Nice) and the nearest POI by linking 5 back-to-back queries: the first one to the location service to retrieve the geocoordinates of the mailing address; then the second one to the proximity search service to retrieve the (dbid,poiid) pair of the closest POI from the previously found geocoordinates; then the third one to the route planning service to retrieve data about the best route between the postal address and the POI; then the fourth one to the mapping service to retrieve the metadata of the map with obtained mapId; and finally the last query to access to the very map itself.

     

    Both 2 first requests are identical to that of the previous study.

     

    The third query retrieves both route trace between MY_LOCID and MY_POIID and data about the best map to display it via the Route service. The trace can be found in the response stream at response->iti->itineraryTrace (let's call it MY_ITI_TRACE) and map data at response->header->summaries->summary[0]->fullMapDef (let's call it MY_MAPID, MY_WIDTH and MY_HEIGHT).

    	//Access in server mode
    	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
    
    	//Access in hybrid mode
    	http://apir.viamichelin.com/apir/1/route.xml/FRA/?steps=3:e:MY_LOCID;2:e:MY_DB:MY_POIID&authkey=MY_TOKEN
    
    	//Access in client mode
    	http://apir.viamichelin.com/apir/1/route.xml/FRA/?steps=3:e:MY_LOCID;2:e:MY_DB:MY_POIID&authkey=MY_KEY
    			

    The fourth query retrieves metadata about the map with id MY_MAPID and size MY_WIDTH * MY_HEIGHT containing MY_ITI_TRACE via the mapById service. The map url can be found in the response stream at response->map->url. Let's call it MY_MAP_URL.

    	//Access in server mode
    	http://apir.viamichelin.com/apir/1/mapbyid.xml/MY_MAPID/MY_WIDTH:MY_HEIGHT/fra?authkey=MY_ID&expires=EXPIRATION_DATE&signature=REQUEST_SIGNATURE
    
    	//Access in hybrid mode
    	http://apir.viamichelin.com/apir/1/MY_MAPID/MY_WIDTH:MY_HEIGHT/fra?authkey=MY_TOKEN
    
    	//Access in client mode
    	http://apir.viamichelin.com/apir/1/MY_MAPID/MY_WIDTH:MY_HEIGHT/fra?authkey=MY_KEY
    	
    	//In all 3 cases, iti_trace as POST parameter is valued at MY_ITI_TRACE.
    			

    The ultimate query is identical to that of the first case study.