VIAMICHELIN SOAP API


findNearbyPOIByRoad method

Description 

This method finds a list of «static» points of interest (Client POI stored in database on ViaMichelin Server) located around a central point. This method uses the road to search for POI unlike the findNearbyPOI method, which is as the crow flies.
Specifications 

  • The method cannot find POI which are more than 200 000 meters (by road) from the origin point.
  • The method cannot find POI which are more than 7200 seconds away from the origin point.
  • The maximum number of result is between 1 and a boundary value depending on a parameter value defined in the customer account (usually 50 is used). Any invalid value will be replaced by the nearest boundary value.

Input Parameters 

 Parameter  Mandatory  Description
request
(FindNearbyPOIByRoadRequest)
true contains the specifications of the POI search:
- the specification of the dataset on which to perform search,
- the specification of the search parameters (search central point, ...),
- the specification of the filter to apply on the search result dataset,
- 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 search by road a list of «static» points of interest (Client POI stored in database on ViaMichelin Server) located around a central point, you must at least specify the following attributes in the «request» parameter of the method (see FindNearbyPOIByRoadRequest 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 FindNearbyByRoadParams) which contains the parameters of the search:
- the parameters defining the search: the central point of the search (expressed as a geographic point), and the search mode, and the options of route computation,
- the parameters 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 FindNearbyPOIByRoadRequest structure). The searchFilter attribute (see BasicSearchCriteria) 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 FindNearbyPOIByRoadRequest 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 findNearbyPOIByRoad 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 BasicSearchCriteria) in searchFilter attribute 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. For this type of search (by road) only the «equals» operator is available.

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 criterion 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: 

Two search modes are now available.
  • One mode (normal mode) allows to search the nearest «static» Point of Interest (Client POI stored in database on ViaMichelin Server) which can be reached from the central point of the search.
  • The other mode (reverse mode) allows to search nearest «static» Point of Interest (Client POI stored in database on ViaMichelin Server) allowing to reach the central point of the search.

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
- search center is null
- search center is defined with invalid geographic coordinates
- invalid itinerary option
- ...
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) 

FindNearbyPOIByRoadRequest result = new FindNearbyPOIByRoadRequest(); 

// *********************** 
// init search dataset 
// *********************** 
searchdataset.setDatabaseId("50875"); 
request.setSearchDataset(searchdataset); 

// *********************** 
// init search params 
// *********************** 
FindNearbyByRoadParams searchParams = new FindNearbyByRoadParams(); 
searchParams.setSearchCenter(new GeoCoordinates(48.85045, 2.39059); // centre of Paris 
searchParams.setMaxDistance(20000); 
searchParams.setMaxDuration(720); 
searchParams.setMaxResult(20); 
searchParams.setMode(0); // Normal search mode 

ItineraryOptions itiOpt = new ItineraryOptions(); 
itiOpt.setDate(new GregorianCalendar()); 
itiOpt.setItineraryType(0); // recommended 
itiOpt.setVehicleType(0); // light motorized vehicle 
ItineraryPreferences itiPref = new ItineraryPreferences(); 
itiPref.setAvoidCrossingBorders(false); 
itiPref.setAvoidMountainPass(false); 
itiPref.setAvoidOffroadConnections(false); 
itiPref.setAvoidRoadTaxAreas(false 
itiPref.setAvoidTolls(false); 
itiPref.setFavourMotorways(false); 
itiOpt.setPreferences(itiPref); 
searchParams.setItineraryOptions(itiOpt); 
result.setSearchParams(searchParams); 

// *********************** 
// init search filter 
// *********************** 
BasicSearchCriteria searchCriteria = new BasicSearchCriteria(); 
NumCriteriaDefinition numCriteria = new NumCriteriaDefinition(); 
numCriteria.setMode(2); // select only the POI corresponding to all the numeric criteria 
NumCriteria[] numCriteriaList = new NumCriteria[1]; 
numCriteria.setCriteriaList(numCriteriaList); 
numCriteriaList[0] = new NumCriteria(1, 2, 0); // select POI where num-metadata 1 equals 2 
searchCriteria.setNumCriteria(numCriteria); 
result.setSearchFilter(searchCriteria); 

// *********************** 
// init result format 
// *********************** 
FoundLocationListFormat resultFormat = new FoundLocationListFormat(); 
resultFormat.setLanguage("eng"); 
resultFormat.setWithAddress(true); 
resultFormat.setWithAddressDetails(false); 
resultFormat.setWithMetanumList(true); 
resultFormat.setWithMetastringList(false); 
resultFormat.setWithDescriptionList(false); 
resultFormat.setWithCategoryList(false); 
resultFormat.setWithPhotoList(false); 
resultFormat.setWithDatasheet(true); 

String[] datasheetContentSpecification = new String[4]; 
datasheetContentSpecification[0] = "tel"; 
datasheetContentSpecification[1] = "fax"; 
datasheetContentSpecification[2] = "email"; 
datasheetContentSpecification[3] = "iconId"; 
resultFormat.setDatasheetContent(datasheetContentSpecification); 

// invoke FindPOI Web Service 
FindPOIServiceLocator locator = new FindPOIServiceLocator(); 
FindPOI service = locator.getFindPOI(); 
FoundLocationList result = service.findNearbyPOIByRoad(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