The objective of this tutorial is to guide you in using ViaMichelin REST API, with specific examples made in different computer languages.
- 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.
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.
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 hashlibrary for PHP, java.security package in Java.
Hybrid access mode (server + client)
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.
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 authKeyparameter.
- (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.
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.
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 domain||Main resource type||Unique identifier|
|Proximity search||POI||(dbID, poiID) pair|
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.
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:
|multi-value & multi-subset||…&key=value1A:value1B;value2A:value2B…
In URL, Service names and parameter names are case insensitive but more often than not parameter values are case sensitive.
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.
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->location->id. Let’s call it MY_LOCID.
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.
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.
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 Geocodeservice. They can be found in the response stream at response->locationList->item->location->lat and ->lon. Let’s call them MY_LON:MY_LAT.
The second query retrieves the closest POI by road (in MY_DB database) from MY_LAT:MY_LONthrough the FindPOIByRoad service. The POI id can be found in the response stream at response->poiList->item->poi->id. let’s call it MY_POIID.
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.
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->fullMapDef (let’s call it MY_MAPID, MY_WIDTH and MY_HEIGHT).
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.
The ultimate query is identical to that of the first case study.