VIAMICHELIN SOAP API


Findnearroute

Description 

This method finds the «static» points of interest (Client POI stored in database on ViaMichelin Server) located at a specified distance and/or at a specified duration from a route. 
Specifications 

  • The method cannot find POI which are more than 30 000 meters (by road) from the specified route.
  • The minimum search radius is 1 000 meters. Under this limit, any value will be treated as equal to 1 000.
  • The method cannot find POI which are more than 2400 seconds away (by road) from the specified route.
  • The maximum number of result is included between 1 and a boundary value depending on a parameter value defined in the customer account (usually 50 are used). Any invalid value will be replaced by the nearest boundary value.

Input Parameters 

 Parameter  Mandatory  Description
request
(FindNearRouteRequest)
true contains the specifications of the POI search:
- the specification of the dataset on which to perform search,
- the specification of the search parameters (route definition, ...),
- the specification of the filter to apply on the search result dataset,
- and the specification of the format of the search result dataset.
authenticationParams
(String)
true Specifies an authentication identifier for accessing Web Service: login + '|' character + password

Output Parameter 

 Parameter  Description
FoundLocationList The complete description of the set of POI found.

Use 

To find «static» points of interest (Client POI stored in database on ViaMichelin Server) located near a specified route, you must specify the following attributes in the "request" parameter of the method (see FindNearRouteRequest structure):
  • searchDataset attribute which contains the dataset on which to perform search. Concretely a characters string corresponding to the identifier of a POI database hosted at ViaMichelin.
  • searchParams attribute (see FindNearRouteParams) which contains the parameters of the search:
- the parameters defining the search: the route specification defined by a stopovers list and the options of route computation (vehicle type, itinerary type, itinerary preferences, ...)
- the parameters allowing limiting the search: the number of POI required and the search area which is defined by the maximum search distance by road to locate POI and the maximum time it takes to reach the POI by road.
You can improve the accuracy of the result dataset by applying a filter. In this case, you must also specify the searchFilter attribute in the «request» parameter of the method (see FindNearRouteRequest structure). The searchFilter attribute (see BasicSearchCriteria) which contains the specification of the filter to apply on the search result dataset according to the value of numerical metadata of the POI.At last, the «request» parameter of the method specifies the information type which has to be in the response structure. This helps with performance and allows you to choose the data returned. 

For that you must also specify the resultFormat attribute in the «request» parameter of the method (see FindNearRouteRequest structure). 

The resultFormat attribute (see FoundLocationListFormat) allows to specify the information types of the found location (all by default) which should be returned, the language (English by default) to which they should be returned and the sort order (implicit order by default) of the search result data set.
Specify a filter according to the value of numerical metadata 

The definition of «static» points of interest (Client POI stored in a database on ViaMichelin Server) can contain a list of numerical metadata which are stored in the form of a list of key-value pair. 
A specific information corresponds to each key and depends on the POI type (e.g. the numerical metadata 1 can contain a price; the numerical metadata 20 can contains the number of rooms of a flat; the numerical metadata 8 can contain the POI category; etc...). 
A maximum of 50 numeric metadata can be defined for a POI type. 

With the findNearRoute method you can apply a filter according to the value of the numerical metadata of the points of interest. For this, you must specify one or more numeric criteria and their interaction mode (see numCriteria attribute of SearchCriteria) in searchFilterattribute defined in the «request» parameter of the method. 

A numeric criterion (see NumCriteria) is defined by:
  • an identifier which allows to specify the numeric metadata you want to check,
  • a value which specifies the value to be compared with the value of the numeric metadata to check,
  • and a comparison operator.

Three interaction modes between several numeric criteria are available for this type of search:
  • AND+OR+ALL: POI search method begins searching for POI corresponding to all the specified criteria. If the number of found POI is insufficient (is equal to 0), it completes the search with corresponding POI that in certain criteria. If the number of found elements is still insufficient (is equal to 0), it completes the POI search without taking into account criteria. To specify this interaction mode, you must set the mode attribute (see NumCriteriaDefinition) to 0.
  • AND+OR: POI search method begins searching for POI corresponding to all the specified criteria. If the number of found POI is insufficient (is equal to 0), it completes the search with corresponding POI having at least one of the specified criteria. To specify this interaction mode, you must set the mode attribute (see NumCriteriaDefinition) to 1.
  • AND ONLY: POI search method searches only for POI corresponding to all the criteria. To specify this interaction mode, you must set the mode attribute (see NumCriteriaDefinition) to 2.

For example, to specify a filter which allows to obtain in the result dataset only the POI which have her numeric metadata 1 equals to 2 (e.g. to select the specific category) you must specify:
  • AND ONLY as interaction mode (select only the POI corresponding to all the numeric criteria).
  • and 1 numeric criteria defined by:
- id attribute initialised to 1 (to check the numeric metadata 1)
- value attribute initialised to 2 (to compare the value of numeric metadata 1 with 2)
- compop attribute initialised to 0 («equals»)

Note: 

The findNearRoute method needs a lot of processing times. This means that the specified limits for the corridor definition (distance and duration) are valid only for routes with a distance which does not exceed 500Km. Beyond this limit, the specification of a corridor with a width of 30Km strongly increases the probability of triggering an error (timeout) during search processing. So, to obtain a result, it is necessary to adapt the width of the corridor to the size of the route : Beyond 500Km the corridor width should not exceed 3 km)
Errors 

 Error code  Description  Possible problems
300 Invalid request parameter - request parameter value is not defined (null)
301 Invalid search dataset - search dataset is not valid (null)
302 Invalid search parameters - search parameters is null
- route specification is not valid
- ...
303 Invalid search filter - supplied interaction mode is not valid
- supplied comparison operator is not valid
- ...
304 Invalid result format - supplied order is not valid
- supplied language is not valid
- ...
305 Itinerary computation error - An error occurs during the itinerary computation
3 Abnormal service termination - internal problem

Code sample (Java) 

Will be available in a future version

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

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