VIAMICHELIN JAVASCRIPT API


Exemples

Introduction

Le composant

Le composant de géocodage se trouve dans l'APIJS sous l'appelation ViaMichelin.Api.Geocoding

Lorsque vous lancez le composant, il effectue une requête de géocodage pour le lieu spécifié via le paramètre de configuration.

Les résultats du géocodage sont communiqués via l'événement onSuccess. La méthode attachée à cet événement sera appelée avec 1 seul paramètre, une liste de points géographiques correspondants à la demande.

Le résultat

Le résultat du géocoding est une liste de ViaMichelin.Api.Model.GeoLocation.

Chaque ViaMichelin.Api.Model.GeoLocation se présentera sous la forme :

{
  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 : ""
}
		

Les différents types de géocodage

1 champ

Le géocodage sur un champ se fait en spécifiant la propriété singlefieldSearch dans la configuration du composant. 
La valeur de ce champ est une adresse.

Si vous ne l'avez pas lu, vous pourrez retrouver cet exemple de façon plus détaillée dans le 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);
		

Obtenu dans la console :

Longitude :  2.23354
Latitude :  48.82696
		

Consultez la page de démonstration.

3 champs

Le géocodage sur 3 champs se fait en spécifiant l'adresse, la ville/code postal et le pays.

Les propriétés associées sont respectivement address, cityZip et countryISOCode.

L'adresse et la ville/code postal sont des chaînes libres, le pays est un code iso 3 lettres.

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

Obtenu dans la console :

Longitude : 2.24474
Latitude : 48.83554
		

Consultez la page de démonstration.

4 champs

Le géocodage sur 4 champs s'effectue comme le géocodage 3 champs, mais en séparant ville et code postal.

Les propriétés associées sont address, city, zip et countryISOCode.

L'adresse, la ville et le code postal sont des chaînes libres, le pays est un code iso 3 lettres.

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

Obtenu dans la console :

Longitude : 2.24474
Latitude : 48.83554
		

Consultez la page de démonstration.

Par location ID

Le géocodage peut également se faire à partir du location ID. Il suffit de le spécifier avec id dans la configuration du composant

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

Obtenu dans la console :

Adresse : Place de Lavalette
Ville : 38000 Grenoble
		

Consultez la page de démonstration.

Inverse

Le géocodage inverse se fait en spécifiant les coordonnées de latitude et de longitude du lieu recherché. Elles sont spécifiées avec la propriété coords dans la configuration du composant. 
coords est un objet avec 2 propriétés : lon et lat. (respectivement longitude et 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);
		

Obtenu dans la console :

Adresse : Place de Lavalette
Ville : 38000 Grenoble
		

Consultez la page de démonstration.

 

Le géocodage multiple

Le géocodage multiple permet de faire plusieurs recherches de lieux avec un seul appel au composant. 
Dans ce cas, ce n'est plus un objet de configuration qui définit pour le composant, mais une liste de configurations. 
En conséquence, le résultat ne sera plus une liste de ViaMichelin.Api.Model.GeoLocation, mais autant de listes que de configurations, chacune contenant 1 ou plusieurs résultats.

Il est possible de mélanger des configurations de plusieurs types de géocodage.

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 : ", results.length);
  }
};
VMLaunch("ViaMichelin.Api.Geocoding", conf, callbacks);
		

Obtenu dans la console :

Nombre de résultats : 2
		

Consultez la page de démonstration.

Favoriser un pays

Il est possible de favoriser un pays dans une recherche de Geocodage. Cela donnera plus de poids aux résultats de ce pays.

La propriété à ajouter pour favoriser un pays est favoriteCountry.

Les 2 exemples ci-dessous font une recherche de géocodage sur "Paris". Le premier exemple sans favoriser de pays, le second en favorisant les résultats aux Etats-Unis. 
Vous pouvez observer que Paris en France sort toujours en premier dans les 2 cas, car favoriser les résultats d'un pays leur donne plus de poids, mais d'autres critères donnent du poids à un résultat, et dans ce cas une ville beaucoup plus importante restera toujours devant.

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

Obtenu dans la console :

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

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

Obtenu dans la console :

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

Consultez la page de démonstration.

Gécodage Multiple et option "favoritecountry"

Lorsque vous faites du géocodage multiple, le paramètre favCountry est à spécifier pour chaque objet de 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);
		

Obtenu dans la console :

Nombre de résultats : 2
		

Traiter les réponses multiples

Lors de l'utilisation du géocodage, il arrive que les données envoyées ne soit pas assez précises et que plusieurs lieux correspondent à la recherche.

Les résultats sont ordonnés par pertinence. Il y a de grandes chances que le premier résultat soit le bon, celui recherché par votre utilisateur. Mais il veut mieux lui demander confirmation. 
Vous pouvez pour cela utiliser le composant de levée d'ambiguïté.

Le composant de levée d'ambiguïté

Ce composant va afficher la liste des résultats à l'utilisateur dans un overlay et lui permettre de choisir celui qui correspond à sa recherche.

Vous le trouvez dans l'API sous le nom ViaMichelin.Api.UI.Overlay.Geocoding.Ambiguity.

Configuration

Il prend 3 paramètres en entrée :

  • title : Le titre que vous voulez donner à l'overlay de levée d'ambiguïté
  • search : La recherche qui a été effectuée
  • items : La liste des propositions faites à l'utilisateur comme résultat à sa recherche
var conf = {
  title : "Levée d'ambiguïté",
  search : "Brest",
  items : [
    "29200 Brest, France",
    "Brest, Belarus",
    "21698 Brest, Germany"
  ]
};
		
Evénements

L'utilisateur verra une liste s'afficher et pourra cliquer sur un élément de cette liste. Lorsqu'il le fera, un événement onLocationChoosen sera déclenché.

La méthode liée à cet événement recevra un seul paramètre, l'index de la réponse dans la liste de proposition. 
Par exemple si l'utilisateur clique sur le premier, la méthode recevra 0, s'il clique sur le 5ème, la méthode recevra 4.

Remarque : comme pour tout composant de l'API, les événements onInit et onInitError peuvent aussi être écoutés.

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

Le composant s'appelle lui aussi avec un VMLaunch.

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

Cas pratique

Dans ce cas pratique, nous allons supposer que l'utilisateur effectue une recherche sur "Brest" pour connaître ses coordonnées. A cette recherche, il y a 12 résultats, ils seront affichés à l'utilisateur afin qu'il en choisisse un.

Commençons par créer une méthode effectuant le géocodage.

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

Dans cette méthode, nous avons utilisé 2 autres méthodes : displayResult qui affichera le résultat et handleAmbiguity qui traitera les réponses multiples.

Définissons displayResult.

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

Et 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);
};
		

Les méthodes sont prêtes, il ne reste qu'a lancer la recherche.

doGeocoding("Brest");
		

Obtenu dans la console en cliquant sur le dernier élément :

Object {lon: 21.72915, lat: 43.27988}
		

Consultez la page de démonstration.