VIAMICHELIN SOAP API


GetMapById

Description 

This method allows a map to be generated from a unique map identifier obtained from a previous invocation of the MapManagement Web Service. 
Specifications 

  • 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 (MapByIdRequest) true Specifies a map definition, map options and a list of graphic items to generate a map.
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 

To have a map generated, you must at least specify the following attributes of the request:

  • The mapDefinition attribute (see MapDefinitionByID) specifies unique identifier of the map and the map size which in turn defines the width and the height of the map (both expressed values in pixels). You obtain a valid map identifier from getBestMapgetBestMapDefinition or getMapByScale method of the MapManagement Web Service.
    • The options attribute contains the options to specify the image format (required) and the possible actions on the map (optional).
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 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)
    601 Invalid map definition - map definition is not defined (null)
    - mapsize attribute is not defined (null)
    - map identifier is not defined (null)
    - map identifier is invalid.
    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.
    3 Abnormal service termination - internal problem

    Code sample (Java)
    MapByIdRequest mapRequest = new MapByIdRequest(); 

    // ********************************** 
    // set Map definition 
    // ********************************** 
    MapDefinitionByID mapDef = new MapDefinitionByID(); 
    mapDef.setMapId("-t64x77veem7abp"); 
    ImgSize mapsize = new ImgSize(); 
    mapsize.setHeight(400); 
    mapsize.setWidth(400); 
    mapDef.setMapSize(mapsize); 

    mapRequest.setMapDefinition(mapDef); 

    // ********************************** 
    // 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[1]; 

    // 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); 
    PixelPoint pos = new PixelPoint(); 
    pos.setX(200); 
    pos.setY(200); 
    PinLogoPosDef pinlogoPos = new PinLogoPosDef(); 
    pinlogoPos.setGeoCoordinates(null); 
    pinlogoPos.setPixelPoint(pos); 
    pinLogo.setPosition(pinlogoPos); 
    pinLogo.setReturnHotArea(true); 
    pinLogos[0] = 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.getMapByScale(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