[Virtual Earth] Développement Microsoft Virtual Earth Web Services – Part 2 : Géocoding Service

Cet article est une suite de l’article se trouvant ici. Il était question de créer un compte Virtual Earth et se connecter en C# aux différents services Web de Virtual Earth.

Liens des posts sur le sujet sur ce blog :

1. Introduction à Microsoft Virtual Earth (Part 1)
2. Géocoding / Géocoding Inverse (Part 2)
3. Récupération des images satellites (Part 3)
4. Calcul d’itinéraires (Part 4)

L’article courant va parler de l’utilisation de un de ces services : Le Géocoding/Géocoding inverse.

Géocoding

Comme expliqué dans l’article précédent, le Géocoding est le processus permettant de retrouver des coordonnées géographiques d’un lieu à partir d’informations sur celui-ci (nom,adresse postale…). Un service de Virtual Earth est entièrement dédié à cette tache : Le GeocodeService.

Afin d’accéder aux informations de ce service, il faut d’abord générer la classe proxy permettant de communiquer avec ce service. Ce service étant un service WCF, il suffit d’ajouter la référence de service suivante (“Add Service Reference”) à votre projet : http://staging.dev.virtualearth.net/webservices/v1/geocodeservice/geocodeservice.svc (nous travaillons toujours dans l’environnement de test).

Un fois la référence rajoutée, vous devriez avoir accès aux classes suivantes :

• GeocodeServiceClient : Classe proxy principale gérant la connexion avec le service
• GeocodeRequest : Classe permettant de fournir les données pour une requête de Géocoding
• GeocodeResponse : Classe contenant les informations renvoyés par le service suite à un requête de Géocoding ou de Géocoding inverse.
• ReverseGeocodeRequest : Classe permettant de fournir les données pour une requête de Géocoding inverse.

Fonctionnement générale d’une requête de Géocoding

Avant de commencer, il est nécessaire d’avoir un token d’authentification valide (voir le tutorial précédent). Ensuite, on utilise le code suivant :

GeocodeServiceClient geoCodeSvc = new GeocodeServiceClient();
GeocodeRequest geoCodeRequest = new GeocodeRequest();
geoCodeRequest.Credentials = new Credentials();
geoCodeRequest.Credentials.Token = token;
geoCodeRequest.Query = "Paris";
GeocodeResponse result = geoCodeSvc.Geocode(geoCodeRequest);

On crée le proxy vers le service de Géocoding en utilisant le constructeur par défaut. On crée ensuite une requête de Géocoding. On lui fournit les données d’authentification au travers de la propriété Credentials de la requête. On remplit la donnée token afin de prouver notre identité au serveur Virtual Earth. On remplit ensuite les données qui seront utilisées pour la requête (on utilise ici la propriété Query par simplicité, mais nous verrons plus loin qu’il y a beaucoup plus de possibilités). La requête proprement dite se réalise par la méthode Geocode de la classe proxy GeocodeServiceClient en lui fournissant les données de la requête. On récupère le résultat dans une classe GeocodeResponse.

Découverte de la classe GeocodeRequest

Pierre angulaire du système de Géocoding, la classe GeocodeRequest regroupe de nombreuses propriétés permettant d’affiner sa recherche géographique au maximum.

• Query

La propriété la plus simple est la propriété Query. Cette propriété est une chaine de caractères dans laquelle il est possible de rentrer plusieurs mot clés (nom de pays,ville …). Cette propriété sera ensuite comparé par Virtual Earth avec la base de données d’entités géographiques afin de renvoyer les résultats les plus pertinents.

• Options

Il est possible de restreindre ces résultats grâce à la propriété Options. Cette propriété possède une propriété Count permettant de définir le nombre maximal de réponses (5 par défaut). Il est aussi possible de définir des filtres (propriété Filters). Ces filtres permettent de supprimer des réponses en fonction de critères supplémentaires. Ces filtres/critères sont disponible au travers de classes spécialement conçues à cette effet. Ainsi si l’on souhaite n’avoir que les résultats avec une note de confiance forte, on utilisera le code suivant :

GeocodeService.ConfidenceFilter[] filters = new GeocodeService.ConfidenceFilter[1]; 
filters[0] = new GeocodeService.ConfidenceFilter(); 
filters[0].MinimumConfidence = GeocodeService.Confidence.High; 
GeocodeService.GeocodeOptions geocodeOptions = new GeocodeService.GeocodeOptions(); 
geocodeOptions.Filters = filters; 

Le dernier paramètre, ExtensionData, de la propriété Options est lié à WCF et ne concerne pas ce tutorial.

• Culture : Cette propriété permet de définir la langue dans laquelle vous souhaitez que les informations soient retournées. Par défaut, c’est l’anglais (‘en-US’).
• ExecutionOptions : Cette propriété n’a qu’un booléen suppressFault. Par défaut à false, cette variable indique si vous souhaitez récupérer les erreurs Virtual Earth (false = je souhaite récupérer les erreurs).
• UserProfile : Cette propriété permet de définir des informations sur l’utilisateur courant. On peut ainsi donner les informations concernant sa position, son déplacement, s’il est sur un appareil mobile … Cela permet au serveur de choisir les informations à retourner afin qu’elle soit le plus proche possible de ce que souhaite l’utilisateur.
• Address

Après Query, c’est la propriété la plus important de GeocodeRequest. Cette propriété permet de rentrer les informations pour trouver les coordonnées d’une adresse postale en fonction de critères tel que la rue, la ville, le pays, le code postal. Les informations peuvent être incomplètes (fournir le code postal uniquement avec l’adresse suffit à localiser le lieu par exemple). Un tableau sur le site MSDN décrit les données minimales à fournir pour avoir une localisation précise : http://msdn.microsoft.com/en-us/library/cc966788.aspx.

Attention : Au sein d’une requête GeocodeRequest, il faut remplir, au minimum, le champ Query ou le champ Address afin d’obtenir une réponse de la part du serveur. Les autres champs sont optionnels

Afin de tester tout cela, nous allons prendre l’exemple de l’emplacement du siège de ma société Winwise (Winwise – 16 rue Gaillon,75002 PARIS). Je souhaite un seul résultat et je veux qu’il soit “sûr à 100 %”. On écrit donc le code suivant :

GeocodeServiceClient geoCodeSvc = new GeocodeServiceClient();
GeocodeRequest geoCodeRequest = new GeocodeRequest();

geoCodeRequest.Credentials = new VETutorial.GeoCodeService.Credentials();
geoCodeRequest.Credentials.Token = token;
	
ConfidenceFilter[] filters = new ConfidenceFilter[1] { new ConfidenceFilter() { MinimumConfidence = VETutorial.GeoCodeService.Confidence.High } };
geoCodeRequest.Options = new GeocodeOptions() { Count = 1, Filters = filters};

geoCodeRequest.Address = new Address()
{
	AddressLine = "16 rue Gaillon",
	PostalCode = "75002",
	PostalTown = "Paris",
};

GeocodeResponse result = geoCodeSvc.Geocode(geoCodeRequest);

J’obtiens le résultat suivant : Longitude : 2.334231 Latitude : 48.868681 ce qui correspond bien à l’emplacement de notre société comme le montre cette image ci-dessous prise avec le service d’imagerie de Virtual Earth (sujet d’un prochain tutorial).

Analyse  de la classe GeocodeResponse

Nous allons maintenant apprendre à traiter la réponse de Virtual Earth suite à une requête de Géocoding. Cette réponse possède deux propriétés : ResponseSummary et Results.

• ResponseSummary

Cette propriété regroupe les informations sur le déroulement de la requête. On retrouve les informations sur les droits (propriété Copyright), l’identifiant de la requête (propriété TraceId), le statut de la requête (propriété StatusCode) indiquant s’il y a eu une erreur durant la requête. Si c’est le cas, la propriété FaultReason donne l’erreur lancée du coté Virtual Earth. Enfin la propriété AuthentificationResultCode indique si les informations concernant l’authentification sont valide.

• Results

C’est dans cette propriété que l’on retrouve les résultats de la requête proprement dite. Il s’agit d’un tableau de GeocodeResult où chacune des cases représente une réponse possible. La taille du tableau peut varier de 0 jusqu’au nombre fourni dans la propriété Count des options de la requête.

Chacun des GeocodeResult contient les informations suivantes :

• L’adresse du point dans la propriété Address.
• Les deux points géographiques (haut gauche et bas droit) permettant d’avoir la meilleure vue de ce que l’on souhaite voir (Propriété BestView)
• Le niveau de confiance du résultat (Propriété Confidence)
• Un représentation en chaine de caractères de la confiance du résultat (Propriété MatchCode)
• Un nom pour le résultat (propriété DisplayName)
• Le type d’entité ciblé par le résultat sous forme d’une chaine de caractère (propriété EntityType)
• Des positions géographiques possibles pour le résultat (propriété Locations). Cette propriété contient aussi le type de calcul de calcul a été utilisé (généralement “Interpolation”).

Parlons un peu du géocoding inverse : ReverseGeocodeRequest

Bien que beaucoup moins utilisé que le Géocoding classique, le Géocoding inverse est le processus permettant de retrouver une adresse depuis des coordonnées géographiques. Pour cela, on utilise la classe ReverseGeocodeRequest. Celle ci contient les mêmes champs que GeocodeRequest décrit précédemment sauf Query et Address (ce qui est normal vu que ce n’est pas l’objet de la requête). En revanche, on remarque l’apparition d’une propriété Location sur laquelle on peut indiquer la latitude, longitude, altitude désiré.

ReverseGeocodeRequest rgr = new ReverseGeocodeRequest();
rgr.Credentials = new VETutorial.GeoCodeService.Credentials();
rgr.Credentials.Token = token;
	
rgr.Location = new VETutorial.GeoCodeService.Location() { Longitude = 2.334231, Latitude = 48.868681 };

GeocodeResponse result2 = geoCodeSvc.ReverseGeocode(rgr);

Le résultat de la requête est, comme pour le Géocoding, un GeocodeResponse.

La suite au prochain épisode …

Dans le prochain article, nous parlerons de la récupération de cartes (images) au travers du ImageryService. Un autre article est prévu sur le calcul d’itinéraire entre N points.

N’hésitez pas à me faire des commentaires sur ces articles (bons ou mauvais je m’en fiche du moment que c’est constructif et que ça me permet de faire des articles meilleurs à l’avenir).