VIAMICHELIN SOAP API


References Guide 01

 

  PixelPoint

Description

This Structure defines the coordinates of a pixel on a map image.

Attributes

Name (type)

Description

x
(integer)

The pixel offset from the upper-left corner of an image along the horizontal axis.

y
(integer)

The pixel offset from the upper-left corner of an image along the vertical axis.

 GeoCoordinates

Description

This Structure defines a geographic point in longitude and latitude values.

The geographic coordinates are encoded in WGS84.

Attributes

Name (type)

Description

longitude
(double)

Contains the longitude value of the geographic point (a decimal degree in WGS84 encoded system).

latitude
(double)

Contains the latitude value of the geographic point (a decimal degree in WGS84 encoded system).

 GeoRectangle

Description

This Structure contains a rectangle definition where the corner positions are expressed in geographic coordinates (in WGS84 encoded system).

Attributes

Name (type)

Description

southEastPoint
GeoCoordinates )

Contains the geographic coordinates of the south-east point.

northWestPoint
GeoCoordinates )

Contains the geographic coordinates of the north-west point.

 PixelRectangle

Description

This Structure contains a rectangle definition where the corner positions are expressed in pixels.

Attributes

Name (type)

Description

lowerRightPoint
PixelPoint )

Contains the pixel coordinates of the lower-right point.

upperLeftPoint
PixelPoint )

Contains the pixel coordinates of the upper-left point.

 

 Cost

Description

This Structure contains a cost definition.                                                                     

Attributes

Name (type)

Description

currency
(String)

Contains the currency in which the price is expressed.

price
(double)

Contains a price value.

 

 ImgSize

Description

This Structure allows defines the size in pixels of an image.                                         

Attributes

Name (type)

Description

width
(integer)

Contains the width in pixels of the image (picture/icon/map)

height
(integer)

Contains the height in pixels of the image (picture/icon/map)

 

 LocationDefinition

Description

This Structure defines any type of location (city/place, POI, geographic coordinates).

Use

This structure is used in many request parameters to define a specific location.

In the 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.

Attributes

Name (type)

Description

geoCoordinates
(GeoCoordinates)

Contains the geographic coordinates (in WGS84 encoded system) of a location.

locationID
(String)

Contains the unique identifier of a location. This information can represent either address or a city, and it can be obtained fromGeocoding or ReverseGeocoding ViaMichelin SOAP API.

poiID
POIId )

Contains the unique identifier of a Michelin POI or of a "static POI" (client POI stored in Database on ViaMichelin Server). It can be obtained from one of the search POI methods defined in FindPOI orFindMichelinPOI ViaMichelin SOAP API.

 

 InputMapDefinitionList

Description

This structure contains a set of the map definitions.

Use

This structure was designed to be sent as input parameters to some methods of ViaMichelin SOAP API which need a map definition to work.

This structure contains the map definitions which can be used by the following methods:
  • pixelsToXY method defined in MapManagement Web Services (seemapDefinition attribute defined in PixelsToXYRequest structure)
  • xyToPixels method defined in MapManagement Web Services (seemapDefinition attribute defined in XYToPixelsRequest structure)
  • findRoadAlert method defined in FindPOI Web Services (see mapDefinitionattribute defined in FindRoadAlertParams structure)

Attributes

Name (type)

Description

byID(MapDefinitionByID)

Contains the map definition defined by a unique map identifier.

Optional attribute

byScale(MapDefinitionByScale)

Contains the map definition defined by a central point and a scale.

Optional attribute

 

 InputAddress

Description

This Structure contains the specification of an address to geocode.

Use

Used in the GeocodingRequest structure to define an address to geocode.

Attributes

Name (type)

Description

address
(String)

Contains an address (defined by street number and/or street name) or landmark.

This attribute must be initialised with a valid value (not null and a value different from empty string) if any valid value are defined for cityName attribute and for postalCode attribute.

cityName
(String)

Contains the city label.

This attribute must be initialised with a valid value (not null and a value different from empty string) if any valid value are defined for address attribute and for postalCode attribute.

postalCode
(String)

Contains a postal code.

This attribute must be initialised with a valid value (not null and a value different from empty string) if any valid value are defined for cityName attribute and for address attribute.

stateName
(String)

Contains an administrative area denomination.

countryCode
(String)

Contains the ISO country code.

Required attribute (not null, not empty, initialised with valid value)

 GeocodingRequest

Description

This Structure defines the addresses list to geocode and the geocoding method which should be used.

Use

Sent as main parameter to the getLocationsList method of the Geocoding ViaMichelin SOAP API, this structure specifies the addresses list to geocode and the the geocoding method which should be used.

Attributes

Name (type)

Description

addressesList
(Array of InputAddres)

Contains an array of InputAddress , which define the addresses list to geocode.

This list can contain up to 50 addresses. Beyond this limit a SOAP fault is returned.

Required attribute (not null & not empty)

mode
(integer)

Allows specifying the geocoding mode to use.

Available values are:
  • : "Classic" geocoding mode.
  • : "Extended" geocoding mode. This mode is especially suitable for mobile devices, because it allows to geocode "input addresses" defined with a reduced number of characters. In fact,when a characters string will exceeds the first three characters, the application will consider the remaining characters as if they are "Wildcards". (e.g. geocoding of the input address "Welli, Westm, GBR" returns all the addresses having in his street label a word starting by "Welli" and in his city label a word starting by "West" like "Wellington Close, Westminster" and "Duke Of Wellington Place, Westminster" ...)

Required attribute


 ReverseGeocodingRequest

Description

This structure defines the list of geographical coordinates for which you want to obtain the associated segments of road.

Use

Sent as main parameter to the getLocationsList method of the ReverseGeocodingViaMichelin SOAP API, this structure specifies the geographical coordinates for which you want to obtain the associated segments of road.

Attributes

Name (type)

Description

geoCoordinatesList
(Array of GeoCoordinates )

Contains the list of geographic coordinates used to search locations.

This list can contain up to 200 geographic coordinates. Beyond this limita SOAP fault is returned.

Required attribute (not null, not empty)

 DistanceCalculationRequest

Description

This structure contains the departure point and a set of arrival points for which you want to obtain the distance (as the crow flies) separating them.

Use

Sent as main parameter to the getDistances method of the DistanceCalculationViaMichelin SOAP API, thisstructure specifies the departure point and a set of arrival points for which you want to obtain the distance (as the crow flies) separating them.

Attributes

Name (type)

Description

departurePoint
(GeoCoordinates)

Contains the geographic coordinates (in WGS84 encoded system) of the departure point.

Required attribute (not null, initialised with valid coordinates)

arrivalPoints
(Array of GeoCoordinates)

Contains the list of geographic coordinates (in WGS84 encoded system) of arrival points.

This list can contain up to 1000 geographic coordinates. Beyond this limita SOAP fault is returned.

Required attribute (not null, not empty)


 FoundLocationList

Description

This Structure contains the description of all locations/POIs matching search criteria as well as information about the search (search status & number of found elements)

Use

This structure is used to store the results list corresponding to a POI search, a geocoding or a reverse-geocoding.

Attributes

Name (type)

Description

searchStatus
(integer)

Contains the status flag of the search.

Possible values are:
  • 0: One or more locations or POIs have been found.
  • 1: No location/POI found as no known location corresponds to the search request.
  • 2: No location/POI found as supplied geographic coordinates are invalid. (This occurs when the "geographic coordinates" in supplied reverseGeocoding request is null or invalid)
  • 3: No location/POI found as supplied address is invalid (This occurs when the "input address" in supplied geocoding request is null).
  • 4: No location found as some required fields of input address are missing. (This occurs when an insufficient number of attributes is specified in the "input address" in supplied geocoding request).
  • 5: No location found as supplied country value in input address is invalid. (This occurs when supplied countryCode field value of input address is null or equal to empty string or equal to unsupported country code).
  • 8: search not computed, item out of bound. (This occurs when the number of input address in supplied geocoding request or the number of geographic coordinates in supplied reverse geocoding request exceed the defined limits).
  • 9: No location found as an unexpected error occurs (the treatment will not be taken into account).
  • 10: No location found as the supplied scale is not valid (findRoadAlert only)

size
(integer)

Contains the number of locations/POIS found matching a location search or a POI search.

foundLocations
(Array of FoundLocation)

Contains a range of FoundLocation , which defines the list of locations/POIs corresponding to the search.


 FoundLocation

Description

This Structure contains the complete description of a found location/POI as well as information about the accuracy of this result relative to the search.

Use

This structure is defined/used in FoundLocationList structure.

Attributes

Name (type)

Description

distance
(integer)

Contains the distance from the search centre or from the route.

duration
(integer)

Contains the duration from the search centre or from the route.

locationDesc
Location )

Contains the complete description of the location/POI found.


 Location

Description

This Structure contains the complete description of a found location/POI

Use

This structure is defined/used in FoundLocation structure.

Attributes

Name (type)

Description

id
(String)

Contains a unique identifier of found location (It is initialised with null value for a POI search).

type
(integer)

Contains the found location type.

Available values are:

  • 0: if the location describes a city level address (a city or a place).
  • 1: if the location describes an administrative area (region, state, country...) ( For future use )
  • 2: if the location describes a POI.
  • 3: if the location describes a street level address.

geoCoordinates
(GeoCoordinates)

Contains the geographic coordinates (in WGS84 encoded system) of the found location.

address
Address )

Contains the address description.

poi
POI )

Contains the POI description.


 Address

Description

This Structure contains the complete address description of a found location/POI

Use

This structure is defined/used in Location structure.

Attributes

Name (type)

Description

coherenceDegree
(CoherenceDegreeInfo)

Contains the coherent level of the found result compared the supplied request.

formattedCityLine
(String)

Contains the correctly formatted value of the city address line (e.g.: "Westminster SW1X 9PY").

It can be initialised with "null" value.

formattedStreetLine
(String)

Contains the correctly formatted value of the street address line.

It can be initialised with "null" value.

details
AddressDetails )

Contains more detailed information of address description.


 CoherenceDegreeInfo

Description

This Structure contains the coherent level of the found result compared the supplied request.

This information is only significant after an invocation of "Geocoding" or "ReverseGeocoding" Web Services.

Use

This structure is defined/used in Address structure.

Attributes

Name (type)

Description

 

streetCoherence(integer)

Contains the coherent level of the found result compared to the street fields values of the supplied request.

Available values are:

  • : For "Geocoding" Web Services, this means that all supplied fields are used to find the result. For "ReverseGeocoding" Web Service, this means that the service has found a road segment.
  • : For "Geocoding" Web Services, this means that the street number is an approximation - the nearest known number is selected (e.g. geocoding of the input address "260 rue de Rivoli, Paris" returns the geographic coordinates of "258 rue de Rivoli, Paris")
  • : For "Geocoding" Web Services, this means that the supplied street number is unknown - this street number is ignored and a point in the street is selected (e.g. geocoding of the input address "20 rue de la paix, Neufchateau" returns the geographic coordinates of a point in the street "rue de la paix" in Neufchateau)
  • : For "Geocoding" Web Services, this means that the supplied street name is unknown ? this street name is ignored and the town centre is selected (e.g. geocoding of the input address "Unknown street, London" returns the geographic coordinates of "London centre"). For ReverseGeocoding Web Service, this means that the service has not found a road segment but a city/place.
 

cityCoherence
(integer)

Contains the coherent level of the found result compared to the city fields values of the supplied request.

Available values are:

  • 0: For "Geocoding" Web Services, this means that all supplied fields are used to find the result.
  • 1: For "Geocoding" Web Services, this means that some supplied fields values are not coherent, therefore all supplied data are not taken into account (e.g. geocoding of the input address "Paris, 92150" ignores the city label and returns the geographic coordinates of "Suresnes, 92150").


 Address

Description

This Structure contains the detailed address information of a found location/POI

Use

This structure is defined/used in Address structure.

Attributes

Name (type)

Description

streetNumber
(String)

Contains the street number associated with the address.

It can be initialised with "null" value if no street number is associated with the found location.

streetLabel
(String)

Contains the street denomination associated with the address.

It can be initialised with "null" value if no street denomination is associated with the found location (the location describes a town or a place).

district
(String)

Contains the district denomination associated with the address (e.g.: "Paris 01").

It can be initialised with "null" value if no district is associated with the found location.

city
(String)

Contains the city denomination associated with the address.

gathering
(String)

Contains the gathering denomination associated with the address (e.g.: "La Défense";"Bruxelles Métropole").

It can be initialised with "null" value if no gathering is associated with the found location.

state
(String)

Contains the major administrative area denomination (region, state ...) associated with the address (e.g.: "Hauts de Seine"; "Schleswig-Holstein"; "Westminster"; "Tennessee").

It can be initialised with "null" value if no administrative area is associated with the found location.

zipCode
(String)

Contains the postcode associated with the address (e.g.: "92150"; "SW1X 9PY").

countryCode
(String)

Contains the ISO country code associated with the address (e.g.: "DEU"; "USA"; "GBR").

officialCountryCode
(String)

Contains the official country code associated with the address (e.g.: "D" for Germany).

countryLabel
(String)

Contains the country denomination associated with the address (e.g.: "Deutschland"; "United States").


 POI   

Diagrams

 

Description

This Structure contains the complete description of a POI.

Use

This structure is defined/used in Location structure.

Attributes

Name (type)

Description                         

id (POIId)

Contains a structure which defines a unique POI identifier.

name
(String)

Contains the name of the POI.

datasheet
(Array of KeyValuePair)

Contains a set of information/data items associated with the POI in the form of a list of key-value pair.

In the key-value pair, the key is a characters string which defines the type of the information/data stored in the value.

The list content is defined in the supplied request.

Available values for the key and associated information:

 

Key

Value

 
 

"iconId"

The icon identifier linked to the POI

 
 

"TranslatedName"

The name of the POI in the language specified in the supplied request.

 
 

"level"

Contains the level of geocoding.

Available values are:
  • 1: city level
  • 2: Street level
  • 3: Street number level
  • 4: arbitrary level
 
 

"tel"

The main phone number associated with the POI.

 
 

"intlTel"

The main phone number associated with the POI in international format.

 
 

"tel2"

The secondary phone number associated with the POI.

 
 

"intlTel2"

The secondary phone number associated with the POI in international format.

 
 

"fax"

The fax number associated with the POI.

 
 

"intlFax"

The fax number associated with the POI in international format.

 
 

"email"

The email address associated with the POI.

 
 

"web"

The web site URL associated with the POI.

 
       

metanumList
(Array of NumericPair)

Contains the list of numeric metadata associated with the POI in the form of a list of key-value pair.

Thislist which stores up to 50 pairs. The meaning of each value is defined by the client and depends on themetadata identifier and onthe type of the POI.

In the key-value pair, the key is an integer which defines the numeric metadata identifier. And the value is an integer which contains the value associated to this numeric metadata.

 

metastringList
(Array of AlphanumPair)

Contains the list of alphanumeric metadata associated with the POI in the form of a list of key-value pair.

Thislist which stores up to 15 pairs. The contents and the meaning of each value are defined by the client and depend on the metadata identifierand on the type of the POI.

In the key-value pair, the key is an integer which defines the alpha-numeric metadata identifier. The value is a characters string which contains the value associated to this alpha-numeric metadata.

 

descriptionList
(Array of AlphanumPair )

Contains the list of descriptions associated with the POI in the form of a list of key-value pair.

Thislist which stores up to 30 pairs. The contents and the meaning of each are defined by the client and depend on themetadata identifier (e.g. metadata 1 stores different information that metadata 2) andon the type of the POI.

In the key-value pair, the key is an integer which defines the description identifier. The value is a characters string which contains the value associated to this description.

 

photoList
(Array of String)

Contains a list of URL of the pictures/photos associated with the POI.

 

categoryList
(Array of String)

Contains the list of category codes to which belongs the POI.