Overview of features

ViaMichelin mapping

By choosing ViaMichelin’s geolocation offerings, you automatically benefit from the quality and wealth of information offered by ViaMichelin maps: Exclusive mapping coverage of 238 countries, including 32 in detail, from national road maps to town and district plans, up to 21 levels of scales for accurate locating and easy navigation, 90,000 places mapped down to street level and 19 million kms of road in 44 countries (including 8 million in Europe and 12 million in North America), clear differentiation of road types and surfaces.

The map API gives you access to all the tools and events that interact with the map: customized menus, drag & zoom, zoom in/out, polylines, polygons, layers, circles, POI (Point of Interest) markers, dynamic tooltips, with text and icons.

For more details, please visit documentation

ViaMichelin itineraries

With their capability to include stopovers and to calculate for vehicle, foot or bike traffic, ViaMichelin itineraries have become a key player for routing, a world-class specialist with 100 years of experience on the road. In Europe and North America, you can choose among customized itineraries: recommended by Michelin, shortest, quickest, economical, scenic, on foot, by bike. The toll costs are automatically calculated for automobile, motorcycle or caravan. Petrol costs are also computed, based on the consumption of a hatchback, compact, family car, sedan or luxury car.
You can assure a perfect integration with your site's existing graphics by customizing the colour, opacity and stroke width of the itinerary path displayed on the ViaMichelin map. A full range of time and distance information is easily accessible.

For more details, please visit documentation

Search a database of over 40,000 hotels in Europe

Based on the www.viamichelin.com hotel reservations service, the hotel booking search engine provides real-time availability data for hotel rooms in proximity to a specified location. It also provides the quality ratings from the Michelin Guide, a guarantee of security for your users and must be used with the ViaMichelin maps.

Address verification, geocoding and reverse geocoding for over 40 countries

Geocoding
This functionality allows you to convert an address into geographical coordinates using the WGS84 reference frame.

Reverse Geocoding
"Reverse geocoding" allows conversion of geographical coordinates into a postal address.

Geographical coordinates can be transferred to ViaMichelin GPS Personal Navigation Devices.

Search for Points of Interest (POI)

Using straight-line distance, road network distance or keywords, parameterized according to criteria defined by ViaMichelin, this functionality allows direct execution of proximity searches on your POI database, which is hosted on ViaMichelin's servers.

Prerequisites for using the API

In order to use the ViaMichelin Maps & Drive API, you must have notions of object oriented programming and JavaScript, as well as an understanding of the use of mapping services.

Quick start guide

To make use of the ViaMichelin Maps & Drive API functionalities on a web page, you must insert the <script> tag in your HTML (preferably in the HEAD section) to call the API's JavaScript file.

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

You must obtain your personal ID code, which is required in order to call the API. To obtain your code, you must register or if you already have a "My ViaMichelin" account (a user ID on ViaMichelin.com), login here.

The registration form requires that you specify the domain from which you will access the ViaMichelin Maps & Drive API. The domain may be entered in the forms "localhost", "127.0.0.1", "www.mysite.com" or "admin.mysite.com". This information is required for the operation of the ViaMichelin Maps & Drive API. Otherwise, access will be refused.
For example, if you are developing a server offline, and you have given it the URL "http://localhost", you must declare "localhost" in the preferences of your ViaMichelin Maps & Drive API account.
Important: You must use the ViaMichelin Maps & Drive API from an HTML page hosted on a server. This is the only context in which it will work. Also, the user's browser must have JavaScript enabled.

Once your registration has been approved, we will send you a unique ID code in the format: JSGP20070130151626751375664361

You must insert this code in each web page that calls the ViaMichelin Maps & Drive API (preferably in the HEAD section), as follows:

VMAPI.registerKey("JSBS20070130151626751375664361");

The most basic function of the ViaMichelin Maps & Drive API is to display a map. Here is the HTML code for a page that displays a map of dimensions 400 x 320 pixels, centred on the city of Clermont-Ferrand in France.

<!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>

You can copy this sample code for testing purposes (don't forget to change the ID code), or view the results on this page: example.

Text encoding, browser compatibility

The ViaMichelin Maps & Drive API is compatible with today's most widely used browsers. We do our utmost to extend its compatibility. At this time, the API has been tested with the following browsers:
- Microsoft Internet Explorer version 6.0 and higher
- Firefox 1.5 and higher
- Safari 3
- Opera 9 and higher

ViaMichelin Maps & Drive API is compatible with those javascript frameworks:
- jQuery
- Mootools
- Prototype & Script.aculo.us
- Yahoo! UI

We recommend that you develop your web pages containing the ViaMichelin Maps & Drive API in conformance with XHTML standards in order to have the best possible results on the widest range of browsers.

Also, for the best compatibility with our services, you should encode your pages using UTF-8

API principles

Components

The functionalities of the ViaMichelin Maps & Drive API have been organized and coded in the form of components. These components are loaded automatically onto your page. The reference documentation explains all of the ViaMichelin Maps & Drive API components, with their associated methods, properties and events.

For example, to display a map, you need to instantiate a VMMap object.

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

When creating an object of type VMMap (a map), you must pass a parameter containing the element of the DOM of type <DIV> in which the map will be displayed.

Methods

The methods of a component carry out certain functions or get data from the object that was created.

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

In the example above, an object of type VMMap was created. Here, the drawMap() method will allow us to display the map, centred on geographical coordinates (which must be defined in an object of type VMLonLat) and using a specified scale factor (11). In most cases, the parameters of a method are optional. A default value is used if the parameter is not specified.

Properties

The properties of an object allow us to obtain its characteristics. In certain cases, they also allow setting of these characteristics. The properties do not have parameters.

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

Here, the latitude and longitude properties of the VMLonLat object allow us to get its latitude and longitude values.

Event management

Event management allows firing of actions (or functions) in response to real time events. Events are grouped by component and may be initialized by a call to certain methods (map displayed, itinerary search completed or failed, etc.) or can be linked to an object.
If the event is linked to a method, you must declare the event to fire before calling the method linked to the management of the event.

To implement event management, use the method addEventHandler() passing as parameters the event to detect and the function that will be fired when the event is detected.

In the following example:

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

For every click on the map, the function functioneventonclick() is executed.

Event handling may be cancelled at any time using the method removeEventHandler().

map.removeEventHandler(your_event);

Functional overview of the main components

A complete description of the API components can be found in the reference documentation. Here is an overview of the structures and the principles of the main components.

VMLonLat

The VMLonLat object is used very frequently. It defines a pair of geographical coordinates: a latitude and a longitude. All of the ViaMichelin Maps & Drive API functions are based on geographical coordinates (displaying a map, calculating an itinerary, carrying out a proximity search, etc.).

new VMLonLat(2.334109831366178,48.86142864093333);

For more information, see the reference documentation of VMLonLat.

VMMap

The main component of the API, VMMap displays and manipulates a ViaMichelin map on your web page.

• ViaMichelin maps are organized on the basis of 17 scale factors (from 0 to 16).
• The main method in this object is drawMap(). It displays a map centred on geographical coordinates and using a scale factor.
  

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

  The displayed map is the size of the HTML container in which you placed it.
• You can use methods to manipulate the map, such as mapZoomIn() to zoom in, or panTo() to pan the map toward a geographical coordinate.
  

  map.mapZoomIn();
  map.panTo(new VMLonLat(2.3387106546572,48.83654657445));

• It is also possible to add enhanced navigation tools directly to the map using the method showMapTools() permettant de facilement naviguer sur celle-ci.
  

  map.showMapTools();

• The getCenter() method allows you to obtain the geographical coordinates of the centre of the map.

  map.getCenter();
  

For more information, see the reference documentation of VMMap

VMLayer

In order to display any type of element on a map, you must create an object of type VMLayer. TheVMLayer object is defined based on geographical coordinates that position it on the map, associated with HTML code for its visual presentation. Numerous objects inherit from VMLayer, including :

• VMIconLayer to display an icon with a tooltip
• VMPolyLine to draw a polyline
• VMPolygoneShape to draw a polygon
• VMCircleShape to draw a circle
• VMComplexLayer to hold multiple layers

A VMLayer can be added to a map using VMMap, addOverlay().

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

For more information, see the reference documentation of VMLayer.

VMAddress

The VMAddress object defines an address (with street, city, postcode, country, etc.). The use and manipulation of the address are managed by this object. To display a map corresponding to a text-based address, you must first geocode the address to obtain its geographical coordinates.

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

For more information, see the reference documentation of VMAddress.

VMGeocoder and VMGeosearch

VMGeocoder and VMGeosearch both implement geocoding of addresses. However, an address entered by a user may be ambiguous, in the sense that the ViaMichelin toponymic (name-based) search engine may find several possible geographical points that seem to correspond to the address data.

• VMGeocoder is a simple geocoder. Only the geographical coordinates of the first result found by the search engine are returned, in the form of a 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 on the other hand, returns all the possibilities found by the search engine, in the form of an array of VMAddress. This allows the possibility of traversing the list to choose the address that is considered to best correspond to the request.

  geocoder = new VMGeocoder();
  
  
  myaddress = new VMAddress();
  myaddress.city = "Paris"; //Ville
  
  geosearch.search(myaddress);
  
  list_of_result = geosearch.results;

For more information, see the reference documentation of VMGeocoder and VMGeoSearch.

VMItinerary

VMItinerary performs itinerary calculations between two geographical points. It also allows insertion of up to three intermediate steps.
You can define many parameters of the itinerary calculation using the methods of the VMItinerary object. The parameters must be set before the itinerary calculation is started.

• addStopOver() : Adds an itinerary point (departure, destination or stopover) to the object.
• setItineraryType() : Sets the type of itinerary that will be calculated by ViaMichelin. The itinerary types available are: “Recommended by Michelin”, “Shortest”, “Quickest”, “Economical”, “Discovery”, “On foot”, “By bike”.
• setItineraryVehiculeType() : Sets the type of vehicle: Automobile, Motorcycle, Automobile with caravan.
• setCarType() : Sets the type of vehicle (in the case of an automobile).
• setFuelType() : Sets the type of fuel (in the case of a motor vehicle).
• setFuelCost() : Sets the price of fuel in € (euros) per litre.

  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(); 

All of these parameters are optional. They allow you to have a more precise itinerary calculation, and to obtain an estimate of the costs for the trip.

When the itinerary is calculated, you can obtain and display numerous pieces of information using the following methods:

• getTotalDistance() : Total distance for the itinerary
• getTotalTime() : Total time for the itinerary
• getTotalGasConsumption() : Cost of fuel in € (euros)
• getTollCost() : Cost of tolls in € (euros)
• roadSheet.getHTML() : Complete route plan in HTML
• getItiAsVMComplexLayer() : An object of type VMLayer that displays all itinerary information on a map

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

For more information, see the reference documentation of VMItinerary.

VMPOI, VMPOISearch

Proximity searches for POI (points of interest) can be executed based on straight-line distance (as the crow flies), road network distance or keyword search. To enable this, your POI database must be indexed by the ViaMichelin servers.

A POI is defined by an object of type VMPOI. A set or list of VMPOIs is contained in an object of type VMPOIList.

To carry out a proximity search around a geographical point, you must first obtain a set of data derived from your POI database, which is hosted by ViaMichelin. So as a first step you must obtain this information (called a "POI Definition") using the method getDefiniton() of the object VMPOIDefinition, and passing the database ID as a parameter.

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

All of the criteria defining your POIs will then be loaded into this object, in the criterias property, which is an array of objects of type VMCriteria. If you want to carry out a proximity research that takes certain criteria into account, you must define them in the VMPOIDefinition object using the setCriteria() method.

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

After that, all that's left is to instantiate a VMPOISearch object with the POI Definition that you have just obtained. The search() method is called with the geographical coordinates of the search point as parameters, and the search is executed.

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)

When the search finishes, you obtain the results from the result property, which is an object of type VMPOIList. This object contains a property VMPOIs, which is an array of VMPOI. Several methods allow you to easily display the results in HTML format or on a map.

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

For more information, see the reference documentation of VMPOI, VMPOISearch and VMPOIDefinition.