MapData Services API Suite

• API Suite

• Web Services API

  • Context
  • Geocode
  • Features V3
  • Tile

• MDS Web Services V2

  • QuickLocate
  • Render
  • Route

• Esri ArcGIS REST API’s

  • Map Service

• Deprecated

  • Features V2

  • MDS Web Services V1

    • QuickLocate
    • Render
    • Route

QuickLocate

What is QuickLocate?

The QuickLocate® web service determines the geographic location of a street address. This can be done using the web service FindAddress() method which takes a full or partial street address as input and returns one or more validated addresses and coordinates.

Conversely, reverse geocoding takes coordinates and converts them into an address. This can be done using the web service ReverseGeocode() method which takes a latitude and longitude (as double) and converts it to a street address (as string).

Note: all input or output coordinates are Latitudes and longitudes on the GDA94 (i.e. WGS84) datum. (As used by most GPS devices)

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.

QuickLocate Web Service

The QuickLocate® web service determines the geographic location of a street address. This can be done using the web service FindAddress() method which takes a full or partial street address as input and returns one or more validated addresses and coordinates.

Conversely, reverse geocoding takes coordinates and converts them into an address. This can be done using the web service ReverseGeocode() method which takes a latitude and longitude (as double) and converts it to a street address (as string).

Note: all input or output coordinates are Latitudes and longitudes on the GDA94 (i.e. WGS84) datum. (As used by most GPS devices)

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 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.

QuickLocate Using Addresses

The QuickLocate® Web Service 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.