VIAMICHELIN SOAP API


findByKeyword method

Description 

This method finds «static» point of interest (Client POI stored in database on ViaMichelin Server) in a specific country according to the value of a list of keywords. 
Input Parameters 

 Parameter  Mandatory  Description
request
(FindByKeywordRequest)
true contains the specifications of the POI search:
- the specification of the dataset on which to perform search,
- the specification of the search parameters (keywords, ...),
- 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» Point Of Interest (Client POI stored in database on ViaMichelin Server) from a list of keywords, you must specify the following attributes in the «request» parameter of the method (see FindByKeywordRequest structure):
  • searchDataset attribute which contains the specification of 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 FindByKeywordsParams) which contains the parameters of the search:
- the parameters defining the search: the definition of the keywords, and the definition of the search area (a country ISO code),
- the parameters limiting the search: the number of POI required.

You can improve the accuracy/the precision 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 FindByKeywordRequest 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 FindByKeywordRequest 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 findByKeyword 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, only one interaction mode between several numeric criteria is available:
  • 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»)

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
- keywords is not valid (null or empty)
- supplied keywords interaction mode is not valid
- supplied keywords search scope is not valid
- country code is not valid (null or empty)
- ...
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
- ...
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