MDS WebServices V2

MDS Web Services

MDS Web Services are XML based web services with SOAP APIs that provide a set of classes, methods and properties that can be used in a variety of development environments. The services are self-documenting, with the methods and classes available by loading the ASMX or WSDL files in either a development environment or Internet browser.

There are four main web services that are provided as part of an MDS web services license. These are:

  • QuickLocate® (Geocoding) Web Service (for locating street addresses)
  • Route Web Service
  • Render Web Service

Accessing the MDS Web Service SOAP API

Referencing the MDS Web Service WSDL
You will use the same URL for each of the web services during every stage your development project, including:
  • Research and development;
  • Testing and QA;
  • Application release.
Note: All Web Services are billable, except when used to develop an application, but the free access is limited to what MDS considers reasonable development limits. Please check your licence for these limits from both a time and usage perspective.
Referencing the MDS Web Service WSDL Files

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 the MDS Web Services' SOAP APIs:

Your development project must reference the WSDL files below to access the MDS Web Services' SOAP APIs:

QuickLocate®(Geocoding) Web Service http://apps.nowwhere.com.au/webservices/quicklocate.asmx
Route Web Service http://apps.nowwhere.com.au/mdsservicesr2/MDSrouteServiceSoap.asmx
Render Web Service http://apps.nowwhere.com.au/mdsservicesr2/MDSRenderServiceSoap.asmx

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.

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