VIAMICHELIN JAVASCRIPT API


Examples

The component

The geocoding component's name is « ViaMichlin.Api.Geocoding in the APIJS guide. When you launch the component, it executs a geocoding request for a specific place, (input) through the configuration parameter.
The geocoding result will be transmitted through the onSuccess event. The  method  related to the event will be called with one parameter. The result is a list of geographic coordinates.

The result 

The result of geocoding is a list of ViaMichelin.Api.Model.GeoLocation.

Each ViaMichelin.Api.Model.GeoLocation response is like the example below:

 

{
  id : "34MTE1YndkcXIyODgyODg0MzBpeTEyNTIyMDIzY05EZ3VPREkyTXpFPWNNaTR5TXpJMk9RPT1jTkRndU9ESTJPVFk9Y01pNHlNek0xTkE9PWNORGd1T0RJMk9UWT1jTWk0eU16TTFOQT09MGxDb3VycyBkZSBsJ0lsZSBTZWd1aW4=",
    type : 3,
  coords : {
    lon : 2.23354,
    lat : 48.82696
  },
  formattedAddressLine : "42 Cours de l'Ile Seguin",
  formattedCityLine : "92100 Boulogne-Billancourt",
  streetNumber : "42",
  streetLabel : "Cours de l'Ile Seguin",
  city : "Boulogne-Billancourt",
  postalCode : "92100",
  reflexId : 140650,
  area : "Hauts-de-Seine",
  formattedAmbiguityLine : "- F - Hauts-de-Seine - Boulogne-Billancourt (92100) : 42 Cours de l'Ile Seguin",
  countryISO : "FRA",
  countryOfficial : "F",
  countryLabel : "France",
  significance : 6,
  ambiguityLine : "- F - Hauts-de-Seine - Boulogne-Billancourt (92100) : 42 Cours de l'Ile Seguin",
  jalon : 6,
  coherenceDegree : {
    street : 1,
    city : 0
  },
  areaLabel : "",
  singleFieldSearch : "",
  locId : ""
}
                 

The different type of geocoding

 

1 field

The geocoding with one field requires the singlefieldSearch property within the configuration of the component.
 The  field's value is an address.
You can find more details of this example on the quickstart guide.

var conf = {
  singleFieldSearch : "88 cours de l'ile seguin, 92100 Boulogne-billancourt"
};
var callbacks = {
  onSuccess : function (results) {
    var coords = results[0].coords;
    console.log("Longitude : ", coords.lon);
    console.log("Latitude : ", coords.lat);
  }
};
VMLaunch("ViaMichelin.Api.Geocoding", conf, callbacks);

Result on the console :

 

Longitude :  2.23354
Latitude :  48.82696
                 

Consult the page démonstration.

3 fields

The geocoding functionality with 3 fields launch the result  by mentionning the address, the town, the zipcode and the country. Their respective properties are address, cityZip and countryISOCode.
The address, the town and zipcode expect a string value. The country value is an “ISO” code of 3 letters.

var conf = {
  address : "100 Avenue Victor Hugo",
  cityZip : "92100 Boulogne-Billancourt",
  countryISOCode : "FRA"
};
var callbacks = {
  onSuccess : function (results) {
    var coords = results[0].coords;
    console.log("Longitude : ", coords.lon);
    console.log("Latitude : ", coords.lat);
  }
};
VMLaunch("ViaMichelin.Api.Geocoding", conf, callbacks);

Result on the console :

Longitude : 2.24474
Latitude : 48.83554
                 

Consult the page demonstration.

4 fields

The geocoding on 4 fields is carried out like the previous example, with 3 fields, but only by dissociating the town and the zipcode. Their relative properties are address, city, zip, and countryISOCode.
The address, town and zipcode expect a string value. The country value is an ISO code of 3 letters.

var conf = {
  address : "100 Avenue Victor Hugo",
  city : "Boulogne-Billancourt",
  zip : "92100",
  countryISOCode : "FRA"
};
var callbacks = {
  onSuccess : function (results) {
    var coords = results[0].coords;
    console.log("Longitude : ", coords.lon);
    console.log("Latitude : ", coords.lat);
  }
};
VMLaunch("ViaMichelin.Api.Geocoding", conf, callbacks);

Result on the console :

 

Longitude : 2.24474
Latitude : 48.83554
                 

Consult the page demonstration.

The location ID

The location ID is a set of alphanumeric characters, delivered by ViaMichelin and used to locate a place.
 The geocoding can also be executed from this location id. You have to specify it on the configuration of the component.

 

var conf = {
  id : "35MTE1OWswMzA2Mjhob2ZlNjMya3ZsczQyaTJ0MTAxMGNORFV1TVRrME1Eaz1jTlM0M016RTROQT09"
};
var callbacks = {
  onSuccess : function (results) {
    var geoLoc = results[0];
    console.log("Adresse : ", geoLoc.formattedAddressLine);
    console.log("Ville : ", geoLoc.formattedCityLine);
  }
};
VMLaunch("ViaMichelin.Api.Geocoding", conf, callbacks);
                 

Result on the console :

 

Adresse : Place de Lavalette
Ville : 38000 Grenoble
                 

Consult the page demonstration.

 

The reverse option

The geocoding reverse option is executed by indicating the latitude and the longitude of the place required.
It requires a coords property on the configuration of the component. “coords” is an object containing 2 properties : lon et lat (longitude and latitude).


var conf = {
  coords : {
    lon : "5.73184",
    lat : "45.19409"
  }
};
var callbacks = {
  onSuccess : function (results) {
    var geoLoc = results[0];
    console.log("Adresse : ", geoLoc.formattedAddressLine);
    console.log("Ville : ", geoLoc.formattedCityLine);
  }
};
VMLaunch("ViaMichelin.Api.Geocoding", conf, callbacks);
                 

Result on the console

Adresse : Place de Lavalette
Ville : 38000 Grenoble
                 

Consult the page demonstration.

The multiple geocoding

It enables you to execute several requests by calling the component at the same time.
In this case, the configuration is not an object but a list of configurations.
So, the result won't be a single list of ViaMichelin.Api.Model.GeoLocation, but as much as lists of configuration, each one containing one or several results.
It is also possible to use different types of request (reverse, 3 fields...) at the same time. You have to specify all datas required on the "conf" variable, like the example below.

var conf = [
  {
    coords : {
      lon : "5.73184",
      lat : "45.19409"
    }
  },
  {
    address : "100 Avenue Victor Hugo",
    cityZip : "92100 Boulogne-Billancourt",
    countryISOCode : "FRA"
  }
];
var callbacks = {
  onSuccess : function (results) {
    console.log("Nombre de résultats (quantity of results): ", results.length);
  }
};
VMLaunch("ViaMichelin.Api.Geocoding", conf, callbacks);
                 

Result on the console :

 

Nombre de résultats : 2
Quantity of result 
                 

Consult the page demonstration.

 

Prioritize a country

It is possible to prioritize a country on a request of geocoding. It means that the first suggestions of the result will be from the country you chose on priority.
Then you have to put the favoriteCountry property on the configuration.
The 2 examples below illustrate a geocoding search in Paris. The first example, without the favoriteCountry option, the second example prioritizes USA on the result.
You can notice that Paris in France appears always on the first position in the two cases, because it prioritizes a country you chose. But others criterions can influence the result.

 

Without favoriteCountry :

var conf = {
  singleFieldSearch : "Paris"
};
var callbacks = {
  onSuccess : function (results) {
    var i, geoLoc;
    for (i = 0; i < results.length && i < 5; i++) {
      geoLoc = results[i][0];
      console.log(geoLoc.formattedCityLine + " - " + geoLoc.countryLabel);
    }
  }
};
VMLaunch("ViaMichelin.Api.Geocoding", conf, callbacks);

Results on the console :

75000 Paris - France
Paris TX - United States
Paris ON - Canada
Paris IL 61944 - United States
Paris KY - United States
                 

With favoriteCountry = USA :

 

var conf = {
  singleFieldSearch : "Paris",
  favoriteCountry : "USA"
};
var callbacks = {
  onSuccess : function (results) {
    var i, geoLoc;
    for (i = 0; i < results.length && i < 5; i++) {
      geoLoc = results[i];
      console.log(geoLoc.formattedCityLine + " - " + geoLoc.countryLabel);
    }
  }
};
VMLaunch("ViaMichelin.Api.Geocoding", conf, callbacks);
                 

Result on the console :

75000 Paris - France
Paris TX - United States
Paris IL 61944 - United States
Paris KY - United States
Paris TN 38242 - United States
                 

Consult the page demonstration.

 

Multiple geocoding and « favoriteCountry » option

 

When you use the multiple geocoding, the parameter « favoriteCountry » has to be specified in each object of the configuration.

var conf = [
  {
    singleFieldSearch : "Brest",
    favoriteCountry : "FRA"
  },
  {
    singleFieldSearch : "Laval",
    favoriteCountry : "FRA"
  }
];
var callbacks = {
  onSuccess : function (results) {
    console.log("Nombre de résultats : ", results.length);
  }
};
VMLaunch("ViaMichelin.Api.Geocoding", conf, callbacks);
                 

Result of the console :

 

Quantity of result : 2


                 

Manage the multiple responses 

 

When you use the geocoding functionnality, the datas you sent can be imprecise, so several places correspond to the request.
So results are ordered by revelance. The first result you get may be the right. But it is better to use a confirmation by displaying a window.
You can do this by using the  ambiguity component.

The ambiguity component (data checking component)

The component presents a list of results in an modal window and allows you to choose the result corresponding better to your search.
The name’s component is ViaMichelin.Api.UI.Overlay.Geocoding.Ambiguity.

Configuration

At first, it contains 3 parameters:

  • title : the modal's name
  • search : the data search
  • items : the list of suggestions 
var conf = {
  title : "Levée d'ambiguïté" (ambiguty removal),
  search : "Brest",
  items : [
    "29200 Brest, France",
    "Brest, Belarus",
    "21698 Brest, Germany"
  ]
};
                 
Events

When a list of suggestions is displayed on a modal window, you can click on the right address. Then, at the click, a “onLocationChoosen” event is triggered.
The method linked to the event contains one parameter which represents the index of the suggestion selected.
For example, if the user selects the first suggestion, the response will be 0, and 4 for the 5th suggestion.

Note : the events onInit and onInitError can be mention on the callbacks like any component.

var callbacks = {
  onLocationChoosen : function (index) {
    console.log("L'utilisateur a cliqué sur l'élément numéro " + (index + 1));
  }
};
                 
Execution


The component is called also by the VMLaunch method to work.

 

VMLaunch("ViaMichelin.Api.UI.Overlay.Geocoding.Ambiguity", conf, callbacks);
                 

Pratical case

In this case, the user is searching the geographic coordinates of “Brest”. He gets 12 results which are displayed, and one of it have to be chosen.

Let’s start by building a geocoding method .

var doGeocoding = function (search) {
  var conf = {
    singleFieldSearch : search
  };
  var callbacks = {
    onSuccess : function (results) {
      if (results.length === 0) {
        displayResult();
      } else if (results.length === 1) {
        displayResult(result[0]);
      } else {
        handleAmbiguity(search, results);
      }
    }
  };
  VMLaunch("ViaMichelin.Api.Geocoding", conf, callbacks);
};
                 

In the example, we use 2 others methods : displayResult which displays the results, and handleAmbiguity  which returns a choice of several suggestions.
Let’s define displayResult.

var displayResult = function (result) {
  if (result) {
    console.log(result.coords);
  } else {
    console.log("Pas de résultat.");
  }
};
                 

And handleAmbiguity.

var handleAmbiguity = function (search, results) {
  var conf = {
      title : "Levée d'ambiguïté",
      search : search,
      items : []
    },
    i, result, callbacks;
  for (i = 0; i < results.length; i++) {
    result = results[i];
    conf.items.push(result.formattedCityLine + ", " + result.countryLabel);
  }
  callbacks = {
    onLocationChoosen : function (index) {
      displayResult(results[index]);
    }
  };
  VMLaunch("ViaMichelin.Api.UI.Overlay.Geocoding.Ambiguity", conf, callbacks);
};

Then, the methods are ready, we can launch the request.

doGeocoding("Brest");

Result on the console by clicking on the last element :

Object {lon: 21.72915, lat: 43.27988}
                 

Consult the page demonstration.