VIAMICHELIN SOAP API


ReverseGeocoding


Overview

The Reverse Geocoding Web Service allows you to obtain the closest road segment (named or not) for each supplied geographic coordinates (WGS84). In the case that no road segment is available within a radius of 1km for the given geographic coordinates, the returned result is the closest place. In the case that no place is available within a radius of 75 km, the returned result is a «null» value.

WSDL

The WSDL (Web Services Description Language) describes the behaviour of the Web Service and instructs how to interact with it. It appears as an XML formatted file for each VIAMICHELIN SOAP API Service. 

You can consult the «Reverse Geocoding» WSDL file at the following URL: 
http://business-solutions.travel.michelin.fr/dl/api_soap/xml/ReverseGeocoding?wsdl 

This file is also included in the «Ressources\WSDL» sub-directory in the SDK.

Defined methods

getLocationsList

getLocationsList method

Description 

This method takes an array of WGS84 encoded geographic coordinates and finds the corresponding road segment or place. 
Specifications 

  • The maximum number of items in the list of geographical coordinates is 200. Beyond this limit, a SOAP fault is returned.
  • The minimum number of items in the list of geographical coordinates cannot be lower than 1. Otherwise, a SOAP fault is returned.
  • The maximum returned values by geographic coordinates is 1.
  • The geographic coordinates used are WGS84 encoded.

Input Parameters 

 Parameter  Mandatory  Description
request
(ReverseGeocodingRequest)
true Specifies the list of geographical coordinates for which you want to obtain the associated segments of road.
authenticationParams
(String)
true Specifies an authentication identifier for accessing Web Service : login + '|' character + password.

Output Parameter 

 Parameter  Description
FoundLocationList[] An array of found locations. Always an item by supplied geographic coordinates even if no locations are found.

Use 

The Web service allows you to search addresses from several geographic coordinates using the ReverseGeocodingRequest which defines all supplied geographic coordinates in the GeoCoordinates array. 
For each supplied geographic coordinate pair, a FoundLocationList is returned; it contains the address description and the location description matching the supplied geographic coordinates. 
Notes 

This Web service billing is not based on the number of successful requests received, but on the number of individual treatments made by ViaMichelin. 
A treatment is defined as each element in the table named «geoCoordinatesList», per request, even if any elements are not valid.Using this service, you can obtain two types of result:
  • The geographical coordinates match a road segment, therefore the result is accurate.
  • Or, the geographical coordinates do not match a road segment; therefore the result is the closest identified place.
The attribute «distance» of the FoundLocation structure contains the distance 'as the crow flies', between the geographical coordinates specified in the request and the closest road segment ViaMichelin provides. This will help to measure the level of accuracy.
Errors 

 Error code  Description  Possible problems
100 Invalid request value - request value is not defined (null)
101 Invalid geographic coordinates list - the list of geographic coordinates is not defined (null) 
- the list of geographic coordinates is empty 
- the list of geographic coordinates contains more that 200 items.
3 Abnormal service termination - internal problem



Code sample (Java)
// ReverseGeocoding request initialization 
ReverseGeocodingRequest request = new ReverseGeocodingRequest(); 
GeoCoordinates[] coordTab = new GeoCoordinates[2]; 
GeoCoordinates coord = null; 
// specification of the first geographic coordinates pair 
coord = new GeoCoordinates(); 
coord.setLongitude(41.40306); 
coord.setLatitude(2.18511); 
coordTab[0] = coord; 
// specification of the second geographic coordinates pair 
coord = new GeoCoordinates(); 
coord.setLongitude(52.511285); 
coord.setLatitude(13.3902645); 
coordTab[1] = coord; 
request.setGeoCoordinatesList(coordTab); 
// invoke ReverseGeocoding Web Service 
ReverseGeocodingServiceLocator locator = new ReverseGeocodingServiceLocator(); 
ReverseGeocoding service = locator.getReverseGeocoding(); 
FoundLocationList[] result = service.getLocationsList(request, "YOUR_LOGIN|YOUR_PASSWORD");

Code sample (VB.NET)
Will be available in a future version

Code sample (C#.NET)
Will be available in a future version