Static Map

Release Version

This reference documents the release version of MapData Services Render. This release version of the API is a feature-stable version of the API whose interfaces are guaranteed to remain as documented within these pages until this version is retired.

Static Map?

Static map is a 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.

Static map 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".

Autentication

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
        

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

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.

Class Library

Class Methods and Properties Type Description/Comment
Address AddressLine
CountryRegion
PostalCode
PrimaryCity
SecondaryCity
Subdivision
String
String
String
String
String
String(50)
28 Railway Parade
"Australia", "New Zealand"
E.g. 2065
E.g. "Greenwich"
UNUSED in Aus NZ
E.g. "NSW" Region E.g. "Auckland"
AuthHeader AnyAttr
Password
Username
XmlAttribute
String
String
Sets the request authentication (See Authentication)
Direction Address
Bearing
DirectonType


Distance

Duration
FormattedInstruction

ID
Instruction

LatLong
View
Address
String
DirectionType


Double

Long
String

String
String

LatLong
MapViewRepresentations
See Address class for details
N|S|E|W|NE|NW|SE|SW
Type of direction. Currently only uses DirectionType.Driving

Distance in Kilometers to the next direction

Text of the instruction with HTML formatting
Unique direction identifier
e.g. Turn RIGHT (East) onto Carter Ave
See LatLong class for details
Future Addition. Will return route extents.
CalculatedRouteRepresentation DrawLine RouteLine See RouteLine class for details
RouteLine InnerCol


LineStyle


MapFileName



Opacity

OuterCol


Width
Integer


Integer


Sting



Double

Integer


Integer
Colour from centre to 1pixel from route line edge. Unused in MDSPREBUILT mapping dataset.
Dashed line |Solid line | hatched line. Unused in MDSPREBUILT mapping dataset.
Unique name given to route to allow referencing. Note most routes are temporary lasting up to 10 minutes from creation.
0.1 - 1 where 1 is opaque (fully blocks mapping underneath)
Red, Green, Blue value e.g. 255 - setting the colour of the route line
Width in pixels 1-30
Entity DisplayName
ID
Name
Properties
String
ID
Name
Properties
Unused in Render
Unused in Render
Unused in Render
Unused in Render
EntityPropertyValue Name
Value
String
Object
Unused in Render
Unused in Render
HotArea IconRectangle
LabelRectangle
PinID
PixelRectangle
PixelRectangle
String
Type PixelRectangle
Type PixelRectangle
The ID of the pushpin the HotArea relates to
ImageFormat Height
MimeType


Width
Integer
String


Integer
In pixels
"image/png/jpg/gif" is the only supported MIME type and is the default
In pixels
LatLong Latitude
Longitude
Double
Double
Coordinates in latitude and longitude
Based on the GDA94 (i.e. WGS84) datum
LatLongRectangle Northeast
Southwest
LatLong
LatLong
The bottom left and top right of a bounding rectangle. Both are type LatLong
Location Address
BestMapView
DataSourceName
Entity
LatLong
Address
MapViewRepresentations
String
Entity
LatLong
Unused in Render
MapImage HotAreas
MimeData
Url

View
HotArea
MimeDate
String

MapViewRepresentations
See HotArea class for details
See MimeData class for details
MapData Services IIS server map graphic location
See MapviewRepresentations class below.
MapOptions Format
ReturnType
MapReturnType
MapSpecification DataSourceName

Options

Pushpins
Routes
views
String

MapOptions

Pushpin()
Route()
MapView()
Mapping Datasource e.g. 'MDSPREBUILT'
See MapOptions class for details.
See Pushpin class for details.
See Route class for details.
See MapviewRepresentations class for details
MapviewRepresentations ByBoundingRectangle

ByHeightWidth
ByLevelCentreSize
ViewByBoundingRectangle

ViewByHeightWidth
ViewByLevelCentreSize
See viewByBoundringRectangle class
See ViewByHeightWidth class
See ViewByLevelCentreSize class
MDSRenderServiceSoap ConvertToLatLong


ConverToPoint


GetBestMapView


GetMap

AuthHeaderValue
Url

UseDefaultCredentials
LatLong()


PixelCoord()


MapViewRepresentations


MapImage()

AuthHeader
String

Boolean
accepts pixelcoord(), MapView, width, height and returns as LatLong()
accepts LatLong(), MapView, width, height and returns as pixelcoord()
Method to return the extents required to fit a set of map objects e.g. points
Main Mapping Call sends request for map image
See AuthHeader class for details
MapData Services IIS server map graphic location
Send request for map image
MimeData Bits

ContentID
MimeType
Byte

String
String
Stream of bytes comprising a mime encoded map graphic
e.g. map001.png
"image/png/jpg/gif" is the only supported MIME type and is the default
PixelCoord X
Y
Integer
Integer
The coordinates of a point in pixel coordinates 0,0 is top left
PixelRectangle Bottom
Left
Right
Top
Integer
Integer
Integer
Integer
Map object Extents in pixels, used for placing text and recording map "hot areas"
Pushpin IconDataSource


IconName

Label

LabelNearbyRoads

LatLong

PinID

Pixel

ReturnsHotArea
String


String

String

Boolean

LatLong

String

PixelCoord

Boolean
DataSource to use for pushpin icons e.g. "MDS:Icons"

Number of required graphic e.g. 1,2,3..100
Text label to be displayed in the map next to the icon


Location of the icon on the map in WGS84
User supplied reference ID

Location of the icon on the map in pixels top left is 0,0
If true, GetMap() will return hot areas defined by the pixel coordinates around the pushpin.
Route CalculatedRepresentation
Itinerary
Specification
CalculatedRouteRepresentation
RouteItinerary
RouteSepcification
Matches route object of routingService Currently rendering only uses
Calculated representation
ViewByBoundingRectangle BoundingRectangle LatLongRectangle See LatLongRectangle class for details
ViewByHeightWidth CenterPoint
Height
Width
LatLong
Double
Double
See LatLong class for details
In Km
In Km
ViewByLevelCentreSize Center
PixelWidth

PixelHeight

ReqZoomLevel
LatLong
int

int

int
See LatLong class for details
Physical width in pixels of the map graphic returned.
Physical height in pixels of the map graphic returned.
A number from 1-18 with 18 being providing the greatest detail mapping (closer to ground).

Enumerations

Enumeration Type Value
AvoidanceMask Integer Ferries
NoAvoid
Tollways
Tunnels
UnsealedRoads
MapReturnType Integer ReturnImage
ReturnSecureUrl
ReturnUrl
networkDetail Integer mainRoads
streets
tracks
SegmentbuildType Integer Shortest
Simplest
SnapType Integer NearestRoad
Normal

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.

ConvertToLatLong

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

Referencing lat/lng on the map.

ConvertToPoint

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

Set map view

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

A WSDL file is an XML document that defines the format of messages that each web service uses. It defines the behaviour of each web service and instructs applications on how to interact with it. Your development project must reference the WSDL files below to access Render:

Your development project must reference the WSDL files below to access the Render:

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.