Directions

Release Version

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

What is Directions?

Routing can be done through CalculateSimpleRoute(LatLong, RouteDataset, SegmentPreference). Results are returned in Segments and Directions arrays.

You can return a full list of the datasets that are available from MDSCommonService.GetDataSourceInfo(Nothing). Currently "mapds.au" or "mapds.nz" route Datasets are available.

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
        

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.

Response

Routing can be done through CalculateSimpleRoute(LatLong, RouteDataset, SegmentPreference). Results are returned in Segments and Directions arrays.

You can return a full list of the datasets that are available from MDSCommonService.GetDataSourceInfo(Nothing). Currently "mapds.au" or "mapds.nz" route Datasets are available.

Distance

Itinerary.Distance
Itinerary.Segments.Directions.Distance

Times

Itinerary.DrivingTime
Itinerary.Segments.Directions.Duration

Avoidance

Set in SegmentPreference.avoidPreference (see enumerations table under AvoidanceMask for options). This is set then passed to CalculateSimpleRoute. How do I set more than one avoidance category

Multiple scenarios

Set in SegmentPreference. buildPreference (see enumerations table under SegmentBuildType for options).

Itineraries

Itinerary.Segments.Directions.Address.AddressLine

Reference to MDSroute file (stored at MAPDS)

Stored in CalculatedRouteRepresentation.DrawLine.MapFileName As String Eg. Route.CalculatedRepresentation.DrawLine.MapFileName. This can be passed to the Render WebService to draw the route.

Multiple via points routes 20 point Limit - (Agreed use can extend this)

With the use of CalculateSimpleRoute(LatLong, RouteDataset, SegmentPreference)

Parsing LatLong to the function CalculatedSimpleRoute as an array of larger size eg. [0]-[19] for a maximum of 20 [0] as start point [19] as end point [1]-[18] as via points.

Note: more than 20 points per route is available by arrangement with MapData Services

Route Coordinates

Are available by arrangement with MapData Services

Line-vectors

Available on agreed use

Routes

CalculateMultipleRoutes
Allows the efficient creation of multiple routes from the one call. Enhanced access is required
CalculateRoadDistances
Efficiently calculates the set of ROAD DISTANCES between an origin point and a set of destination points. Enhanced access is required
CalculateSimpleRoute
Calculate a route according to the specified settings (Extended to allow the creation of permanent routes)

RetrievePermanentRoutes

Allows the reuse of previously created, purpose built, stored routes.

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

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 Route:

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

Request Workflow

  • The general development process for sending a Route request is as follows:
  • 1. Create a new Route request;
  • 2. Create and assign the authentication header to the Route request;
  • 3. Create and assign the required and desired properties in the SegmentPreference class;
  • 4. Create a result using the CalculateSimpleRoute() method;
  • 5. Check the RouteReturnResult code in the result and get the result route;
  • 6. Extract the results from the Route class.