VIAMICHELIN SOAP API


Getbestmapdefinition

Description 

This method takes a map size and a set of locations to compute the best map definition allowing the display of corresponding locations. 
Specifications 

  • The maximum number of locations in the supplied array is 50. Beyond this limit, a SOAP fault is returned.
  • The minimum number of locations in the supplied array cannot be lower than 1. Otherwise, a SOAP fault is returned.
  • Invalid location definitions (e.g. initialised with null) are ignored.

Input Parameters 

 Parameter  Mandatory  Description
request (MapDefinitionRequest) true Specifies a map size and a list of locations to compute the best map definition.
authenticationParams (String) true Specifies an authentication identifier for accessing Web Service: login + '|' character + password

Output Parameter 

 Parameter  Description
MapDefinitionList Contains the best map definition found expressed in several forms.

Use 

The Web service allows you to get the best map definition to display all required locations specified in the MapDefinitionRequest structure.

To have the best map definition, you must specify the following attributes of the request:
  • The locations attribute which contains the list of locations to display. The Web Service will compute the corresponding best map definition.
  • The mapSize attribute defines the width and the height of the map (both expressed values in pixels).
  • The imgFormat attribute defines the format of the picture to generate. The format affects the number of map scale available.
The structure obtained in response (see MapDefinitionList structure) contains a set of attributes which define a particular type of map definition:
  • byRectangle attribute contains the map definition defined by the rectangle bordering the map. This map definition type is for information only.
  • byScale attribute contains the map definition defined by a central point and a scale (expressed by a pixel size). This map definition type can be used to compute conversions (see xyToPixels and pixelsToXY methods) or to generate a map (see getMapByScale method) or to find «road alert» on a map (see findRoadAlert method defined in FindPOI Web Service).
  • byID attribute contains the map definition defined by a unique map identifier. This map definition can be used to compute conversions (see xyToPixels and pixelsToXY methods) or to generate a map (see getMapByID method) or to find «road alert» on a map (see findRoadAlert method defined in FindPOI Web Service).
How to specify a location 

To specify a location, you must initialize one of the following attributes defined in the LocationDefintion structure:
  • locationID: This is the unique location identifier. This specifies a location to be displayed on the map. To obtain a valid value for this attribute, you must invoke the Geocoding Web Service.
  • poiID: This is the unique POI identifier. This specifies a POI position to be displayed on the map. To obtain a valid value for this attribute, you must invoke the FindPOI Web Service.
  • geoCoordinates: WGS84 encoded geographic coordinates. This specifies a geographic point to be displayed on the map.

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

Errors 

 Error code  Description  Possible problems
500 Invalid request value - request value is not defined (null)
501 Invalid locations list - the locations list is not defined (null),
- the locations list is empty,
- all locations in the list are null,
- a supplied location definition is invalid,
- the locations list contains more that 50 items.
502 Invalid image format value - imgFormat attribute value is invalid
503 Invalid map size value - mapsize attribute is not defined (null)
3 Abnormal service termination - internal problem

 

 

Code sample (Java) 

// MapDefinitionRequest initialization 
MapDefinitionRequest mapRequest = new MapDefinitionRequest() ; 
// ********************************** 
// set Locations 
// ********************************** 
LocationDefinition[] locDefList = new LocationDefinition[2]; 
LocationDefinition locDef = null; 

locDef = new LocationDefinition(); 
GeoCoordinates coord = new GeoCoordinates(); 
coord.setLongitude(7.68438727); 
coord.setLatitude(45.07829); 
locDef.setGeoCoordinates(coord); 
locDefList[0] = locDef; 

locDef = new LocationDefinition(); 
locDef.setLocationID("24115jl7690041g4f10532dkvcNDUuMDEzMDY=8Ny44MjY2cNDUuMDEzMDM=
cNy44MjcyMw==cNDUuMDEzMDY=8Ny44MjY20lPiazzetta San Giorgio"); 
locDefList[1] = locDef; 

mapRequest.setLocations(locDefList); 

// ********************************** 
// set MapSize 
// ********************************** 
ImgSize mapsize = new ImgSize(); 
mapsize.setHeight(400); 
mapsize.setWidth(400); 
mapRequest.setMapSize(mapsize); 
// ********************************** 
// set ImgFormat 
// ********************************** 
mapRequest.setImgFormat(0); 

// invoke MapManagement Web Service
MapManagementLocator locator = new MapManagementServiceLocator(); 
MapManagement service = locator.getMapManagement(); 
MapDefinitionList result = service.getBestMapDefinition(mapRequest, "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