VIAMICHELIN SOAP API


GetRouteNonMotorized

getRouteNonMotorized method


Description 

This method allows to compute a route with a non motorized vehicle (on foot or by bike) and provides either the list of the instructions associated to this route, or the graphic representation of this route, or both. 

Specifications

  • The maximum number of intermediate stages is 8. Beyond this limit, a SOAP fault is returned.
  • The maximum distance for a route on foot is 30 km. Beyond this limit, a SOAP fault is returned.
  • The maximum distance for a route by bike is 200 km. Beyond this limit, a SOAP fault is returned.
  • Itinerary steps can be defined by geographic coordinates, location identifier or POI identifier.
  • This service allows you to calculate a route in Europe or in the United-States.
Input Parameters 

 Parameter  Mandatory  Description
request
(NonMotorizedItineraryRequest)
true Contains the route calculation request specification, allows you to specify the itinerary steps list and itinerary options.
authenticationParams
(String)
true Specifies an authentication identifier for accessing Web Service: login + '|' character + password

Output Parameter 

 Parameter  Description
ItineraryResult Contains either the list of the driving instructions associated to this route, or the graphic representation of this route, or both.

 

Use 

To calculate a route, you must specify the following attributes in the main parameter of the method (see NonMotorizedItineraryRequest structure):

  • The itinerarySteps attribute contains the stopovers list of the route. A itinerary stopover is defined by a name and a location definition. The name is used to establish a link between the route stopover which is specified in the request and the route stopover which is really used by the route calculation. You must at least specify two stopovers which will define the departure and arrival points of the route.
  • The itineraryOptions attribute specifies the parameters which will influence the computation method of the route.
  • The presentationOptions attribute allows specifies the parameters which will influence the presentation style of the list of the driving instructions which is associated to the calculated route (the detail level, the language, or the formatting of the instructions).
  • The responseOptions attribute specifies the elements which will must be produced by the route calculation (either the graphic route representation, the list of driving directions, or both) as well as the map definitions.
In the response structure (see ItineraryResult) you can access three major sets of information:
  • itinerarySummary attribute contains the route summary, which in turn contains the general information of the calculated route : total distance, total duration, the definition of stages really used, and the best map definition to display the graphic representation of the entire route.
  • itineraryItems attribute contains the list of the driving directions and the associated information like the level of the driving direction (either main or secondary), the gathering (a gathering is defined by a main instruction and the list of the secondary instructions which are associated with it), the associated pictogram, the partial distances, the partial durations, and the best map definition to display a portion of the graphic representation corresponding to the level 1 instruction.
  • itineraryTrace attribute contains the graphic representation of the calculated route.

 

Note: Roadmap representation 

itineraryItems attribute contains the list of the driving directions which corresponds to the line representation on the roadmap. Therefore, the simplest way to generate a roadmap from the response structure is to add a new line of the roadmap for each element/items contained in the itineraryItems attribute. Each roadmap line being able to contain a driving instruction (in the specified format) and the set of related information which you want to display.The driving instructions/directions can be supplied either as a text without formatting, or as a text with HTML formatting. In this last case, you must define in your html page the following styles for presentation of direction panels:

 

<style> 
.pan1 {margin: 5px 5px 5px 0px; padding: 5px; width: 200px; text-align: center;font-family : Arial;padding:2px; margin-bottom:2px; border:1px solid #006; width:200px; text-align:center; font-size:11px; font-weight:bold; color:#FFF ; background-color:#009834} 
.pan2 {margin: 5px 5px 5px 0px; padding: 5px; width: 200px; text-align: center;font-family : Arial;padding:2px; margin-bottom:2px; border:1px solid #006; width:200px; text-align:center; font-size:11px; font-weight:bold; color:#FFF ; background-color:#00F} 
.pan3 {margin: 5px 5px 5px 0px; padding: 5px; width: 200px; text-align: center;font-family : Arial;padding:2px; margin-bottom:2px; border:1px solid #006; width:200px; text-align:center; font-size:11px; font-weight:bold; color:#000 ; background-color:#FFF} 
.pan4 {margin: 5px 5px 5px 0px; padding: 5px; width: 200px; text-align: center;font-family : Arial;padding:2px; margin-bottom:2px; border:1px solid #006; width:200px; text-align:center; font-size:11px; font-weight:bold; color:#FFF ; background-color:#069} 
.pan5 {margin: 5px 5px 5px 0px; padding: 5px; width: 200px; text-align: center;font-family : Arial;padding:2px; margin-bottom:2px; border:1px solid #006; width:200px; text-align:center; font-size:11px; font-weight:bold; color:#FFF ; background-color:#F00} 
.pan6 {margin: 5px 5px 5px 0px; padding: 5px; width: 200px; text-align: center;font-family : Arial;padding:2px; margin-bottom:2px; border:1px solid #006; width:200px; text-align:center; font-size:11px; font-weight:bold; color:#000 ; background-color:#FF0} 
.pan7 {margin: 5px 5px 5px 0px; padding: 5px; width: 200px; text-align: center;font-family : Arial;padding:2px; margin-bottom:2px; border:1px solid #006; width:200px; text-align:center; font-size:11px; font-weight:bold; color:#FEE21D ; background-color:#396} 
.pan8 {margin: 5px 5px 5px 0px; padding: 5px; width: 200px; text-align: center;font-family : Arial;padding:2px; margin-bottom:2px; border:1px solid #006; width:200px; text-align:center; font-size:11px; font-weight:bold; color:#FFF ; background-color:#0F0; display:none} 
.pan9 {margin: 5px 5px 5px 0px; padding: 5px; width: 200px; text-align: center;font-family : Arial;padding:2px; margin-bottom:2px; border:1px solid #006; width:200px; text-align:center; font-size:11px; font-weight:bold; color:#FFF ; background-color:#0F0; display:none}
</style>

Note: How to specify a route stopover 

To specify a stopover, you must initialize one of the following attributes defined in the LocationDefinition structure (type of the location attribute defined in the ItineraryStep structure):
  • locationID: unique location identifier. Specifies a location using an ID string (city, place or address) that will be considered as a stopover of the route. To obtain a valid value for this attribute, you must invoke the Geocoding Web Service.
  • poiID: unique POI identifier. Specifies a POI using the Poi ID that will be considered as a stopover of the route. To obtain a valid value for this attribute, you must invoke the FindPOI Web Service.
  • geoCoordinates: WGS84 encoded geographic coordinates. Specifies the closest road segment for the supplied geographic point that will be considered as a stopover of the route.
In case there is a conflict between any of these properties, the geographic property has priority, then the location unique identifier and finally the POI identifier.
Note: How to draw graphic route representation on a map 

To draw on a map a portion or the entire graphic representation of a calculated route, you must specify in the route calculation request (see NonMotorizedItineraryRequest) that you want to obtain in the response structure the graphic representation of the calculated route and the map definitions allowing to display the entire, or portions of the graphic representation of the calculated route:
  • You can specify in the responseOptions attribute (see NonMotorizedItineraryRequest) the route elements definitions that the getRoute method has to return: set responseElements attribute to 1 (to obtain only the graphic representation of the calculated route) or 3 (to obtain the graphic representation of the calculated route and the list of driving directions).
  • You can specify in the responseOptions attribute (see NonMotorizedItineraryRequest) the map definitions that the getRoute method has to compute: set mapDefinitionCalculated attribute to 1 (to compute the map definitions allowing to display the entire calculated route on a map), 2 (to compute the map definitions list allowing to display a portion of the calculated route on the maps) or 3 (to compute both).


The graphic representation (see ItineraryTrace) and the map definitions returned can be used by the MapManagement Web Services.

Errors 

 Error code  Description  Possible problems
400 request parameter is not valid
  • request parameter is not defined (null).
401 Itinerary step list is not valid
  • itinerary step list is not defined (null).
  • number of itinerary steps is insufficient (minimum two : departure and arrival).
  • too many itinerary stages specified.
  • an itinerary step is not correctly defined.
402 Itinerary parameter are not valid
  • itinerary options are not valid: itinerary options are not defined(null), supplied itinerary date is not defined, supplied vehicle type value is not valid, ...
  • presentation options are not valid: presentation options are not defined (null), supplied language value is not valid, supplied detail level value is not valid, supplied instructions format is not valid, ...
  • response options are not valid: response options are not defined (null), supplied mapDefinitionCalculated value is not valid, supplied responseElements value is not valid, ...
403 Specific calculation error
  • the distance exceeds that allowed for this type of vehicle.
404 Specific calculation error
  • incoherent request parameters (e.g. avoid frontier crossed option is incompatible with stopovers defined in different countries).
405 Specific calculation error
  • incompatible road network.
406 Specific calculation error
  • road network not available.
407 Specific calculation error
  • invalid itinerary step.
408 Specific calculation error
  • invalid itinerary date.
409 Specific calculation error
  • itinerary step not reachable.
410 Specific calculation error
  • itinerary arrival not reachable.
411 Calculation error
  • Other itinerary calculator error.
3 Abnormal service termination
  • internal problem.
Code sample (Java) 
NonMotorizedItineraryRequest result = new NonMotorizedItineraryRequest(); 
// ********************************** 
// set Itinerary step 
// ********************************** 
ItineraryStep[] itinerarySteps = new ItineraryStep[2]; 
LocationDefinition locDef = null; 
ItineraryStep step = null; 

locDef = new LocationDefinition(); 
locDef.setLocationID("24115ews800042vtg1053h5dycNDguODUwNDU=cMi4zOTA1OQ== 
cNDguODUxNzg=cMi4zODkzNA==cNDguODUwNDU=cMi4zOTA1OQ==0fRue des Boulets"); 
step = new ItineraryStep(); 
step.setName("Step0"); 
step.setLocation(locDef); 
itinerarySteps[0] = step; 

locDef = new LocationDefinition(); 
locDef.setLocationID("24115ez7ne0042wxj1053dtrpcNDguNzAzOTQ=cMi4wMjkwMQ== 
cNDguNzA1NzY=cMi4wMzI2OQ==cNDguNzA1NzY=cMi4wMzI2OQ==0gRue de Dampierre"); 
step = new ItineraryStep(); 
step.setName("Step1"); 
step.setLocation(locDef); 
itinerarySteps[1] = step; 

request.setItinerarySteps(itinerarySteps); 

// ********************************** 
// set Itinerary options 
// ********************************** 
BasicItineraryOptions options = new BasicItineraryOptions(); 
options.setDate(new GregorianCalendar()); 
options.setVehicleType(3); // Bike 
result.setItineraryOptions(options); 

// ********************************** 
// set Itinerary response options 
// ********************************** 
ResponseOptions responseOptions = new ResponseOptions(); 
responseOptions.setResponseElements(3); // Itinerary trace and Itinerary roadMap 
responseOptions.setMapDefinitionCalculated(3); // All map definition 
ImgSize mainMapSize = new ImgSize(); 
mainMapSize.setWidth(600); 
mainMapSize.setHeight(600); 
responseOptions.setMainMapSize(mainMapSize); 
ImgSize blocMapSize = new ImgSize(); 
blocMapSize.setWidth(200); 
blocMapSize.setHeight(200); 
responseOptions.setBlocMapSize(blocMapSize); 
request.setResponseOptions(responseOptions); 

// invoke RouteCalculation Web Service
RouteCalculationServiceLocator locator = new RouteCalculationServiceLocator(); 
RouteCalculation service = locator.getRouteCalculation(); 
ItineraryResult result = service.getRouteNonMotorized(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