VIAMICHELIN SOAP API


FindNearbyPOI

Description 

This method allows to find a list of «static» Points of Interest (client POI stored in a Database on ViaMichelin Server) located near a defined central point. 
Specifications 

  • The maximum search radius is 200 000 metres. Any value beyond this limit will be treated as 200 000 metres.
  • The minimum search radius is 1 000 metres. Any value below this limit will be treated as 1 000 metres.
  • 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
(FindNearbyPOIRequest)
true The specifications of the POI search:
- the dataset on which to perform search,
- the search parameters (search central point, ...),
- the filter(s) to apply on the search result dataset,
- 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 

In order to search for «static» points of interest (client POI stored in a Database on ViaMichelin Server) located around a central point, you must specify the following attributes in the «request» parameter of the method (see FindNearbyPOIRequest 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 FindNearbyParams) which contains the parameters of the search composed of:
- the central point of the search (expressed as a geographical coordinates),
- the search area limits such as the number of POI required and the search radius.
It is also possible to limit the results by applying a filter. In this case, you must specify thesearchFilter attribute in the «request» parameter of the method (see FindNearbyPOIRequest structure). 

The searchFilter attribute (see SearchCriteria) contains the specification of the filter to apply on the search result dataset. This attribute allows you to apply two types of filter:
  • One enables you to filter according to the value of numerical metadata of the POI
  • the other allows you to query keywords in some textual fields of the POI.

The «request» parameter of the method also allows you to choose what information which has to be in the response structure. This allows you to optimize the data exchange receiving only the information you require. 

You are able to define what information should be returned (all by default), the language (English by default), and the sort order (implicit order by default) of the resulting data set. 

To do this you must specify the resultFormat attribute (see FoundLocationListFormat) in the «request» parameter of the method (see FindNearbyPOIRequest structure).

 

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 findNearbyPOI 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 or 3 (e.g. to select the flats with 2 or 3 rooms), and her numeric metadata 5 not equals to 0 (e.g. to select the flats which are not at the ground floor), you must specify:
  • AND ONLY as interaction mode (select only the POI corresponding to all the numeric criteria).
  • and 3 numeric criteria :
1) a 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»)
2) a numeric criterion defined by :
- id attribute initialised to 1 (to check the numeric metadata 1)
- value attribute initialised to 3 (to compare the value of numeric metadata 1 with 3)
- compop attribute initialised to 0 («equals»)
3) a numeric criterion defined by :
- id attribute initialised to 5 (to check the numeric metadata 5)
- value attribute initialised to 0 (to compare the value of numeric metadata 5 with 0)
- compop attribute initialised to 1 ("not equals")
Specify a filter according to the value of keywords 

To specify a filter according to the value of a set of keywords, you must specify one or more keywords and their interaction mode (see textCriteria attribute of SearchCriteria) insearchFilter attribute defined in the «request» parameter of the method. 

This type of filter is valid if at least the following attributes of the TextCriteriaDefinition structure are specified:
  • keywords attribute which specifies the set of the keywords. A keyword is defined as a character string separated by the space character.
  • mode attribute which specifies the interaction mode between several keywords.
  • scope attribute which specifies the scope of the keywords search (the set of textual POI fields where the keywords should be searched).

Two interaction modes between several keywords are available:
  • AND: POI search method searches for POI which contains all the specified keywords.
  • OR: POI search method searches for POI which contains at least one of specified keywords.

For the «static» points of interest (client POI stored in a Database on ViaMichelin Server) the search scope is limited to the name of the POI.
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
- ...
303 Invalid search filter - supplied interaction mode is not valid
- supplied comparison operator is not valid
- supplied search scope is not valid
- ...
304 Invalid result format - supplied order is not valid
- supplied language is not valid
- ...
3 Abnormal service termination - internal problem

Code sample (Java) 

FindNearbyPOIRequest request = new FindNearbyPOIRequest(); 

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

// *********************** 
// init search params 
// *********************** 
FindNearbyParams searchParams = new FindNearbyParams(); 
searchParams.setSearchCenter(new GeoCoordinates(48.85045, 2.39059); // centre of Paris 
searchParams.setMaxDistance(20000); 
searchParams.setMaxResult(20); 
request.setSearchParams(searchParams); 

// *********************** 
// init search filter 
// *********************** 
SearchCriteria searchCriteria = new SearchCriteria(); 
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); 

TextCriteriaDefinition textCriteria = new TextCriteriaDefinition(); 
textCriteria.setKeywords("Auberge"); 
textCriteria.setMode(0); 
textCriteria.setScope(0); 
searchCriteria.setTextCriteria(textCriteria); 

request.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); 

resultFormat.setOrderBy(0); // implicit order 
request.setResultFormat(resultFormat); 

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