VIAMICHELIN SOAP API


GetMapByScale

Description 

This method allows a map to be generated from a map definition specified by a geographic position (which specifies the centre of the map) and a scale (expressed by a pixel size). 
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 (MapByScaleRequest) 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 MapDefinitionByScale) specifies the centre of the map (a geographic position), the scale of the map (expressed by a pixel size), and the map size which in turn specifies the width and the height of the map (both values expressed in pixels).
  • 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)
- centre of the map 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.
3 Abnormal service termination - internal problem

Code sample (Java) 

MapByScaleRequest mapRequest = new MapByScaleRequest(); 

// ********************************** 
// set Map definition 
// ********************************** 
MapDefinitionByScale mapDef = new MapDefinitionByScale(); 
mapDef.setPixelSize(400); 
GeoCoordinates center = new GeoCoordinates(); 
center.setLatitude(47.90253160625501); 
center.setLongitude(1.910160025864502); 
mapDef.setCenterPoint(center); 
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