Render Web Service

What is Render Web Service?

You can use the render service to draw maps of routes and locations, place pushpins, draw polygon regions, set the map size and map view, select points on a map, get location information about points and polygons on a map, and pan and zoom a rendered map.

Audience

This document is intended for website developers who need to:

  • resolve an address to a coordinate or the reverse
  • draw base maps with routes and locations
  • provide routes and driving directions from co-ordinates

Authentication

MDS Webs Services uses the HTTP Digest Access authentication protocol to authenticate the calls made to the SOAP APIs. In order to receive a response to your web service request, the request will need to be authenticated by MDS. The authentication is done by applying the username and password (supplied to you by MapData Science) in each request.

In a request, the Authentication Header class contains the username and password as attributes. An invalid username/password combination will result in an error response.

The sample Visual Basic .NET code below shows how to apply your username and password in your application (note: MDSQuickLocateWS is the name of the QuickLocate Web Services web reference):

Example 
  
        [VISUAL BASIC.NET]
        
        'Sets up MDS Quicklocate WebService 
        
        Dim QLService As New MDSQuickLocateWS.GeocoderService
        Dim wsHeader As New MDSQuickLocateWS.AuthHeader
        wsHeader.Username = "InsertYourUsernameFromMDS"
        wsHeader.Password = "InsertYourPasswordFromMDS" 
        QLService.AuthHeaderValue = wsHeader

Remarks

In the sample applications authentication credentials are referenced in the webconfig The credentials must be set before you call any of the method calls, otherwise, you will get an HTTP 401 error. You must authenticate each service before you use it, and then you can make as many method calls as you want on that service object.

Render Web Service

The Map Render Web Service allows you to generate a map based on map extents that are set by:

  • Either a bounding box defined by bottom left, top right coordinates (i.e. South-West and North-East coordinates);
  • Map centre coordinates and map width and height (in kilometres);
  • Or map centre coordinates and zoom level;

All map coordinates are Latitudes and longitudes on the GDA94 (i.e. WGS84) datum.

Maps generated by the web service can either be returned as a URL to a PNG image file stored on MDS� servers, or returned as a stream with a MIME type of "image/png".

Map Styles

Set the map specification DataSourceName to "MDSPREBUILT".

MDSPREBUILT maps have superior cartography and rendering speeds. This mapping is available at up to 18 discrete levels. When using this mapping, ViewByBoundingRectangle (Extents) will return the nearest extents available for the request rather than the exact extents requested. The exact extents of the response are returned with the map.

The MDSPREBUILT maps have superior cartography and rendering speeds. This mapping is available at a large number of discrete levels. When using this mapping, ViewByBoundingRectangle (Extents) will return the nearest extents available for the request rather than the exact extents requested. The exact extents of the response are returned with the map.

Map Coordinate Systems

All map render web service objects, methods and properties use the WGS84 Lat Long coordinate system. The map images are projected in the Spherical (Web) Mercator projection on the WGS84 Datum. This is the same projection as maps generated using the Microsoft Virtual Earth or Google Maps APIs.

Pushpins

You can add one or more pushpins (or points) to a map using the web service. A pushpin can be positioned in a map by using Latitude, Longitude coordinates or pixel coordinates. Each pushpin can also be labelled.

Pushpins can be created as "hot areas" to enable users of your application to use the pushpins in the returned map image as hyperlinks. Hot areas are returned in the web service response as a set of rectangles defined by top left, bottom right pixel coordinates and a unique ID.

Adding a pushpin to a map request is done in the following manner.

  
    MapSpecification.Pushpins().LatLong.Latitude
    MapSpecification.Pushpins().LatLong.Longitude
    then calling the method GetMap(MapSpecification)

Note: pixel coordinates start from the top left corner of the resulting map image, which is in contrast to map coordinates which increase from the bottom left corner. This is due to differences in the standard conventions of pixel and map coordinates.

Binary Stream
Requesting the render web service to return in binary stream (image file) can be done by setting the property MapSpecification.Options.MapReturnType.ReturnImage 
  MapSpecification.Options.MapReturnType.ReturnImage
then calling the method GetMap(MapSpecification)
Pointer to an MDS picture file
Requesting the render web service to return a map image URL can be done by setting the property 
  
    MapSpecification.Options.MapReturnType.ReturnUrl (HTTP) 
    or
    MapSpecification.Options.MapReturnType.ReturnSecureUrl (HTTPS)
    then calling the method GetMap(MapSpecification)
Render Routes built with routing service
Requesting the render web service to return a map with a route can be done by setting the property 
  
    MapSpecification.Routes.CalculatedRepresentation.DrawLine.MapFileName
    then calling the method GetMap(MapSpecification)
Pixel size of Map Image (Maximum of 1300 x 1300)

Requesting the render web service to return a map image of a certain pixel size can be done by setting the properties

  
    MapSpecification.Options.Format.Height
    MapSpecification.Options.Format.Width
Pictures without copyright (Only available under a contract of agreed use)

Map Images can be rendered without the MDS copyright under agreement with MDS

Referencing pixels on the map picture to latitudes,longitudes in the map.
ConvertToLatLong

Conversion from a bitmap point to latitude, Longitude values based on the mapping datasource projection

ConvertToPoint

Getting the pixel X,Y of latitude, longitude points on the map. Conversion to bitmap point based on mapping datasource projection

GetBestMapView

Allows you to view the best map view for a set of points. The best map view is the largest scale map that contains all the desired locations.

Request Workflow

The general development process for sending a map render request is as follow:

1. Create a new MDSRenderServiceSoap request;
2. Create and assign the authentication header to the map request;
3. Create a map view by bounding rectangle or by map centre with width/height;
4. Create a map specification and add the map view to it;
5. Add the map render options to the map specification;
6. Optionally add one or more pushpins to the map specification;
7. Generate the map using the GetMap() method of the request;
8. Get the map image URL or stream from the response.