VIAMICHELIN SOAP API


GetBestMap

Description 

This method generates the best map (the map with the best scale) which can display the set of supplied 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. initialized with null) are ignored.
  • The maximum number of «pin-logos» is 100. Beyond this limit, a SOAP fault is returned.
  • The maximum number of points to define an InputTrace is 300. Beyond this limit, a SOAP fault is returned.
Input Parameters 

 Parameter  Mandatory  Description
request (BestMapRequest) true This structure contains the necessary parameters to generate the map from a list of specific locations :
- the map size, 
- the list of locations which should be to displayed on the map, 
- the map options,
- the list of graphic items.
authenticationParams (String) true Specifies an authentication identifier for accessing Web Service: login + '|' character + password

 

Output Parameter 

 Parameter  Description
GeneratedMap Contains the complete description of the generated map.

Use 

The Web service allows you to get the best map (the map with the best scale) to display all the locations specified in the request (see BestMapRequest structure).To generate a map 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 according to this list.
  • The mapSize attribute which defines the width and the height of the map (both values expressed in pixels).
  • The options attribute which contains the options to specify the image format (required) and the possible actions on the map (optional). The image format affects the number of map scale available.

Using this method you can also specify the graphic elements which can be drawn on the generated map. The graphicItems attribute (see GraphicItems) contains the specification of these graphic elements. Three types of graphic elements are available:

  • The graphic representation of a calculated route (see itineraryTrace attribute defined in GraphicItems). To obtain a valid ItineraryTrace you must invoke the RouteCalculation Web Service.

The graphic representation of a route defined by a list of geographic points or a list of pixels points (see inputTraceList defined in GraphicItems).

 

The graphic representation of a location (see pinLogos attribute defined in GraphicItems).

 

In addition to the URL for the generated map, the response structure also contains the map definition corresponding to the generated map (this information can be used to implement interactions with the generated map), the copyright you have to associate with the generated map, and information about the "pin-logos" drawn on the map (their positions and their hot areas).

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.
How to specify a map action 

The main parameter of the method (see BestMapRequest structure) defines actions which have to be applied on map corresponding to the specification to obtain the generated map. 

To specify such actions, you must initialise the actionsOnMap attribute defined in MapOptions structure (see options attribute of BestMapRequest structure). 

You can specify up to 5 consecutive actions, initialising for each one the following attributes:
  • type attribute defines the type of action to be realised. Available values (integer) are 0 (horizontal shift) / 1 (vertical shift) / 2 (zoom in) / 3 (zoom out).
  • value attribute defines the value associated with the specified action type. Values are as follows:
Action Value
Horizontal shift Shifting factor.
Shifting factor < 0 = West shift
Shifting factor > 0 = East shift
Vertical shift Shifting factor.
Shifting factor < 0 = South shift
Shifting factor > 0 = North shift
Zoom in / Zoom out Not taken into account

How to use your own icons 

It is possible to use your own icons to clearly identify personal or corporate elements to be displayed on the generated map. 
In this case, you have to conform to the following procedure:
  •  
    • you send to ViaMichelin the images you want to use as personalised icons. These are png 8 bytes encode image files with maximum size 30*30 pixels.
    • The ViaMichelin support service uploads your images in specific folders.
    • to use your personalised icons you have to specify as icon name the file name without extension of the personal icon you want to use.

  • Errors 

     Error code  Description  Possible problems
    600 Invalid request value - request value is not defined (null)
    602 Invalid map options - map options is not defined (null).
    - specified image format is invalid.
    603 Invalid graphic elements - the pin-logo list contains more that 100 items.
    - the definition of the InputTrace contains more that 300 points.
    604 Invalid map size value - mapsize attribute is not defined (null)
    605 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.
    3 Abnormal service termination - internal problem

    Code sample (Java)
    // BestMapRequest initialization 
    BestMapRequest mapRequest = new BestMapRequest(); 

    // ********************************** 
    // 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 MapOptions 
    // ********************************** 
    MapOptions options = new MapOptions(); 
    options.setImgFormat(0); // GIF normal palette. 
    options.setWithCopyright(false); // The copyright not drawn on the map. 
    options.setActionsOnMap(null); 
    mapRequest.setOptions(options); 

    // ********************************** 
    // set GraphicItems 
    // ********************************** 
    graphicItems = new GraphicItems(); 
    PinLogo pinLogo; 
    pinLogos = new PinLogo[2]; 

    // specification of the icon have to be associated with the pin-logos 
    IconDef icon = new IconDef(); 
    icon.setName("myIcon"); // name of png file without extension 
    ImgSize iconSize = new ImgSize(); 
    iconSize.setHeight(20); 
    iconSize.setWidth(20); 
    icon.setSize(iconSize); 

    pinLogo = new PinLogo(); 
    pinLogo.setId(0); 
    pinLogo.setDisplayMode(1); // a point + Logo 
    pinLogo.setIcon(icon); 
    GeoCoordinates coord = new GeoCoordinates(); 
    coord.setLatitude(45.07829); 
    coord.setLongitude(7.68438727); 
    PinLogoPosDef pinlogoPos = new PinLogoPosDef(); 
    pinlogoPos.setGeoCoordinates(coord); 
    pinlogoPos.setPixelPoint(null); 
    pinLogo.setPosition(pinlogoPos); 
    pinLogo.setReturnHotArea(true); 
    pinLogos[0] = pinLogo; 

    pinLogo = new PinLogo(); 
    pinLogo.setId(1); 
    pinLogo.setDisplayMode(1); // a point + Logo 
    pinLogo.setIcon(icon); 
    GeoCoordinates coord = new GeoCoordinates(); 
    coord.setLatitude(45.07822); 
    coord.setLongitude(7.6846); 
    PinLogoPosDef pinlogoPos = new PinLogoPosDef(); 
    pinlogoPos.setGeoCoordinates(coord); 
    pinlogoPos.setPixelPoint(null); 
    pinLogo.setPosition(pinlogoPos); 
    pinLogo.setReturnHotArea(true); 
    pinLogos[1] = pinLogo; 

    graphicItems.setPinLogos(pinLogos); 
    graphicItems.setInputTraceList(null); 
    graphicItems.setItineraryTrace(null); 
    mapRequest.setGraphicItems(graphicItems); 

    // invoke MapManagement Web Service
    MapManagementLocator locator = new MapManagementServiceLocator(); 
    MapManagement service = locator.getMapManagement(); 
    GeneratedMap result = service.getBestMap(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