R2 Geocode

What is Geocode?

Geocode is a process by which an address is translated into a geographical coordinate. This service provides a way to does this via an HTTP request. The converse operation is also available, i.e. take a geographical coordinate and translate that into an address.

Note: all input or output coordinates are Latitudes and longitudes on the GDA94 (i.e. WGS84) datum.

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

Search Options

The web service allows erroneous address data to be corrected, if required, by using the following options:

  • Fuzzy' logic searching on the street name, suburb name and/or state name (E.g a fuzzy search on "Read St, Tuggaranong" would find "Reed St, Tuggeranong");
  • Correct an incorrect street type in the street name (E.g. changing "George Rd" to "George St");
  • Search for a street name in adjacent suburbs if it can't be found in the requested suburb.

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 R2 Geocode:

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

QuickLocate®(Geocoding) Web Service http://apps.nowwhere.com.au/webservices/quicklocate.asmx

Request Workflow

The general development process for sending a QuickLocate® request is as follows:

1. Create a new QuickLocate request;

2. Create and assign the authentication header to the QuickLocate request;

3. Create and assign the required address to the request. The appropriate Country name must be assigned to the address to define which geocoding database is used to process the input address. Valid country names are:

  • "Australia" for Australian address ranges
  • "New Zealand" for New Zealand address ranges
  • "GNAFPID" (Australian Geocoded National Address File points)

4. Create and assign the required search options to the request;

5. Create a result using the FindAddress() method;

6. Check the FullResult code in the result and get the result location(s);

7. Extract the coordinates and the parsed address(es) from the result location(s).

Note: if the "GNAFPID" country name was used, the response will return a GNAF PID in the LocationID property of each result location.

IMPORTANT: GNAF usage restrictions - (Please discuss GNAF usage with MapData Services sales consultants)
If using GNAF geocoding - a client may use GNAF latitude/longitude coordinates only within its own organisation. The client may not export latitude/longitude coordinates to any other organisation. If the client is developing an application on behalf of a third party, the client must undertake to not allow any subsequent party to access or use the GNAF latitude/longitude coordinates in any manner whatsoever. If the client is developing an application for a third party then the client must disclose to MDS the complete details of that third party so that MDS can audit the GNAF usage at any time in the future.

Using Addresses

R2 Geocode allows your application to enter in a wide variety of addresses. All of the properties in the Address class are optional; however there is a minimum combination of properties that must be sent in a request.

The Street Property

This property allows you to enter any of the following in a single string:

  • Unit number
  • Street number
  • Street name
  • Street type (full or abbreviated, e.g. "st" or "Street")
  • Street suffix (e.g. "Alfred St North")

If there is any missing information, the web service will attempt to account for it:

  • If you omit the street number, the web service will return the coordinates at the centre of the street.
  • If you fail to enter a suburb it will return a set of suburbs containing the street you have specified.
  • If the street is not in the request, the web service will return the centre of the specified suburb or postcode.

For example: only submitting "Prince Street" would return the following matches:

      
        PRINCE STREET, 
        WALLAROO SA 5556 PRINCE STREET, 
        WAMBERAL NSW 2260 PRINCE STREET,
        WARATAH NSW 2298 PRINCE STREET,
        WERRINGTON COUNTY NSW 2747 
        . . . 
        PRINCE STREET,
        CANNON HILL QLD 4170
The Suburb Property

This property allows you to send a suburb (or locality) name with the request.

If there is more than one suburb by that name all matching suburbs are returned. For example: submitting "St Leonards" would return:

        
        ST LEONARDS NSW 2065
        ST LEONARDS VIC 3223
        ST LEONARDS TAS 7250
Submitting a partial suburb name will return more matches. For example: only submitting "St L" would return:
       
        ST LAWRENCE QLD 4707
        ST LEONARDS CREEK NSW 2354
        ST LEONARDS NSW 2065
        . . .
        ST LUCIA QLD 4067
The State Property

This property allows you to submit an abbreviated state name (Australia) or full region name (New Zealand).

This property is only used for Australian addresses, and the only valid values are ACT, NSW, NT, QLD, SA, TAS, and WA. This is used to restrict return values to a particular state. For Example: submitting "Leichhardt Street" and "NSW" would return:

                   
        LEICHHARDT STREET, DARLINGHURST NSW 2010
        LEICHHARDT STREET, DUBBO EAST NSW 2830
        LEICHHARDT STREET, GLEBE NSW 2037
        . . .
        LEICHHARDT STREET, WAVERLEY NSW 2024
The Postcode Property

This property allows you to submit a four digit postcode. Only postcodes that relate to postal delivery areas are allowed. The web service cannot account for postal codes that are particular to a large business or regional mail exchange, for example.

Result Codes

The web service will return a result code as integer that identifies the quality of an address match. Result codes can be used to return error messages for user feedback within your application.

FullResult Result
0 Address not found.
1 Found a single address
100 Multiple locations matching the search criteria were found.
110 Could not find address.
120 Invalid postcode.
888 Manual positioning, not exact match
999 Manual positioning, exact match
Location.ResultCode Result
10 Found street address.
12 Found street address using fuzzy street and/or suburb match (GNAF only).
20 Street number not found - found nearest number.
22 Street number not found - found nearest number using fuzzy street and/or suburb match (GNAF only).
30 Found street address in surrounding town/suburb.
32 Found street address in surrounding town/suburb using fuzzy street and/or suburb match (GNAF only).
40 Found nearest street number in surrounding town/suburb.
42 Found nearest street number in surrounding town/suburb using fuzzy street and/or suburb match (GNAF only).
50 Street number not found - centred on street.
60 Found street centre in surrounding town/suburb.
70 Found suburb centre.
80 Street not found - centred on suburb.
90 Street not found - centred on postcode.
95 Found postcode centre.