VIAMICHELIN SOAP API


DistanceCalculation

Overview

The DistanceCalculation Web Service allows you to obtain the distance 'as the crow flies' between a central departure point and a set of arrival points. 
For both departure and arrival points, the geographic coordinates (WGS84) are used. 
Note: To calculate the distance by road, you have to use the RouteCalculation Web Service in Synthetic Mode (detailLevel attribute at 0).

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 «DistanceCalculation» WSDL file at the following URL: 
http://webservices.viamichelin.com/ws2/services/AccessManagement?wsdl

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

Defined methods

getDistances

getDistances method


Description 

This method takes a departure point and an array of destination points, and attempts to calculate the distance between the departure point and each of the destination points. 

 

Specifications 

  • The maximum number of items in the GeoCoordinates array is 1000. Beyond this limit, a SOAP fault is returned.
  • The minimum number of items in the array cannot be lower than 1. Otherwise, a SOAP fault is returned.
  • If for a specific destination point the distance can't be calculated then the returned calculated distance is -1. This can occur when destination point is not defined (null).
  • The distance is in Metres.
  • The geographic coordinates used are WGS84 encoded.
Input Parameters 

 Parameter  Mandatory  Description
request (DistanceCalculationRequest) true Specifies a departure point and an array of destination points.
authenticationParams (String) true Specifies an authentication identifier for accessing Web Service: login + '|' character + password

Output Parameter 

 Parameter  Description
long[] An array of calculated distances (in metres) with an item for each destination point. 
If a destination point distance cannot be calculated then the returned distance is -1.
Use 

The DistanceCalculation between a defined departure point and several arrival points is made using the DistanceCalculationRequest which defines one departure point and a set of arrival points in the GeoCoordinates array. 
All the calculated distances are returned in a result array in the same order as GeoCoordinates request input. 
Notes 

The billing for this Web service 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 the calculation for each element in the table named 'arrivalPoints' per request. A treatment still applies even if the calculation fails or the data is not valid.

All DistanceCalculation results are displayed in metres. 

Errors 

 Error code  Description  Possible problems
900 Invalid request or invalid parameter - request value is not defined (null)
- departure point is not defined (null)
- array of arrival point is not defined (null)
- array of arrival point is empty
- array of arrival point contains more that 1000 items
3 Abnormal service termination - internal problem

Code sample (Java)
// DistanceCalculation request initialization 
DistanceCalculationRequest request = new DistanceCalculationRequest(); 
GeoCoordinates[] coordArr = new GeoCoordinates[5]; 
request.setArrivalPoints(coordArr); 
GeoCoordinates coord = null; 
coord = new GeoCoordinates(); 
coord.setLongitude(2.35267); 
coord.setLatitude(48.8564); 
request.setDeparturePoint(coord);

coord = new GeoCoordinates(); 
coord.setLongitude(3.06076); 
coord.setLatitude(50.63793); 
coordArr[0] = coord; 

coord = new GeoCoordinates(); 
coord.setLongitude(7.10484); 
coord.setLatitude(50.73692); 
coordArr[1] = coord; 

coord = new GeoCoordinates(); 
coord.setLongitude(-0.07305); 
coord.setLatitude(51.51617); 
coordArr[2] = coord; 

coord = new GeoCoordinates(); 
coord.setLongitude(-3.69295); 
coord.setLatitude(40.41767); 
coordArr[3] = coord; 
coord = new GeoCoordinates(); 
coord.setLongitude(139.8092); 
coord.setLatitude(35.68306); 
coordArr[4] = coord; 

// invoke DistanceCalculation Web Service
DistanceCalculationServiceLocator locator = new DistanceCalculationServiceLocator(); 
DistanceCalculation service = locator.getDistanceCalculation(); 
long[] result = service.getDistances(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