1.1.2 Geocode

Release Version

This reference documents version 1.1.2 (the release version) of the MapData Services Geocoding API. 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.

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.

Security

This service supports basic authentication for https requests or key referer authentication for http(s) requests.

(HTTPS) Basic Authentication

When the user agent wants to send the server authentication credentials it may use the Authorization attribute in the HTTPS header.
The Authorization header is constructed as follows:

- Username and password are combined into a string "username:password"
- The resulting string literal is then encoded using Base64
- The authorization method and a space i.e. "Basic " is then put before the encoded string.

For example, if the user agent uses 'Aladdin' as the username and 'open sesame' as the password then the header is formed as follows:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

(HTTP/HTTPS) Key referer Authentication

The API can use an API key to identify your application. The key is attached to the request uri as a HTTP(S) GET parameter.
The key is linked to the authorized URI's that are checked using the HTTP request referer attribute.

For example:

http(s)://api.nowwhere.com.au/1.1.2/geocode/?key=YOUR KEY HERE

Request

Requests to the Geocode service can by made either by Address components, Coordinate or property ID.
Requests can be made via HTTP GET or POST.
NT: POST requests can use basic authentication, POST or GET requests can use key / referer authentication. Check the security section for more info.

(GET/POST) By Address

http(s)://api.nowwhere.com.au/1.1.2/geocode/?parameters

Parameters

PARAMETERS are query string parameters in the structure “key=value”. The following table describes the available parameters.

Parameter Type Description
street String The subpremise / street portion of the address, e.g. SUITE 2 110 Pacific Highway.
locality String The locality portion of the address, e.g. Greenwich.
postcode Integer The postcode portion of the address, e.g. 2065.
region String The region portion of the address, e.g. NSW.
country String The country portion of the address, e.g. Australia.

(GET/POST) By Coordinate

http(s)://api.nowwhere.com.au/1.1.2/geocode/?parameters

Parameters

PARAMETERS are query string parameters in the structure “key=value”. The following table describes the available parameters.

Parameter Type Description
latitude Float The latitude portion of the coordinate, e.g. -33.825071.
longitude Float The longitude portion of the coordinate, e.g. 151.1904.

(GET/POST) By PropertyId

http(s)://api.nowwhere.com.au/1.1.2/geocode/?parameters

Parameters

PARAMETERS are query string parameters in the structure “key=value”. The following table describes the available parameters.

Parameter Type Description
propertyid String The id of a property parcel e.g. GANSU705290690

Response

The response from the service will contain a status & results object.
The response will be returned as XML or JSON, this is controlled using the content-type HTTP header attribute.
A typical context response is made up of the following attributes:

Attribute Type Description
copyright String The copyright information for this data
results Array [results] An array of results objects
status String The status of the request

(status) Status Codes

The status field within the response describes the type of response. The status field will contain one of the following values:

Code Description
OK Indicates that no errors occurred. The address or coordinate was successfully parsed and at least one geocode was returned.

(results) Results Object

The service response contains an array of result objects. A typical result is made up of the following attributes:

Attribute Type Description
formattedaddress String The formatted address
subpremise String The unit / suite number
streetnumber Integer The building number
route String The name of the street
locality String The locality
postcode String The postcode
region String The region
country String The country
propertyId String The GNAF Property ID of the location
geometry Object [geometry] The latitude and longitude of the location & the location type eg: "Rooftop"
boundaries Array [boundary] The statistical area boundary ID's from 1-4 ie: SA1, SA2, SA3, SA4

(geometry) Geometry Object

The geometry object contains the coordinates and a location type in the following format:

Attribute Type Description
Coordinate Object The coordinate object contains two Float attributes: Longitude & Latitude
LocationType String The name of the type of location eg: "ROOFTOP"

(boundary) Boundary Array

An individual statistical area geographical boundary name & ID from 1-4 ie: SA1, SA2, SA3, SA4 The boundary object will contain the following values:

Attribute Type Description
name String The name of the boundary eg: SA1
code String The id of the boundary eg: 1141411

Response Content-Type (JSON or XML)

The format of a Geocode response can be controlled by setting the content-type attribute of the HTTP(S) request header, XML & JSON are supported.
NT: JSON is the default.

Content-Type: application/json
Content-Type: application/xml

JSON Response

In this example an address geocode request is made for SUITE 2 110 Pacific Highway, Greenwich 2065 NSW, Australia.

http(s)://api.nowwhere.com.au/1.1.2/geocode/?street=suite%202%20110+pacific+hwy&locality=greenwich&postcode=2065

The returned JSON is shown below.

{
    "copyright": "Copyright © 2019 MapData Services and its suppliers. All rights reserved. This API cannot be accessed and the content and any results may not be used, reproduced or transmitted in any manner without express written permission from MapData Services.",
    "status": "OK",
    "results": [{
        "formattedaddress": "SUITE 2/110 Pacific Highway, Greenwich 2065 NSW, Australia",
        "subpremise": "SUITE 2",
        "streetnumber": "110",
        "route": "Pacific Highway",
        "locality": "Greenwich",
        "postcode": "2065",
        "region": "NSW",
        "country": "Australia",
        "propertyId": "GANSW717827087",
        "geometry": {
            "Coordinate": {
                "Longitude": 151.1904,
                "Latitude": -33.825071
            },
            "LocationType": "ROOFTOP"
        },
        "boundaries": [{
            "name": "SA1",
            "code": "1140037"
        }, {
            "name": "SA2",
            "code": "121011400"
        }, {
            "name": "SA3",
            "code": "12101"
        }, {
            "name": "SA4",
            "code": "121"
        }]
    }]
}

XML Response

In this example an address geocode request is made for SUITE 2 110 Pacific Highway, Greenwich 2065 NSW, Australia.

http(s)://api.nowwhere.com.au/1.1.2/geocode/?street=suite%202%20110+pacific+hwy&locality=greenwich&postcode=2065

The returned XML is shown below.

<geocode>
    <copyright>Copyright © 2019 MapData Services and its suppliers. All rights reserved. This API cannot be accessed and the content and any results may not be used, reproduced or transmitted in any manner without express written permission from MapData Services.</copyright>
    <status>OK</status>
    <results>
    <result>
        <address>
        <formattedaddress>SUITE 2/110 Pacific Highway, Greenwich 2065 NSW, Australia</formattedaddress>
        <subpremise>SUITE 2</subpremise>
        <streetnumber>110</streetnumber>
        <route>Pacific Highway</route>
        <locality>Greenwich</locality>
        <postcode>2065</postcode>
        <region>NSW</region>
        <country>Australia</country>
        </address>
        <geometry>
        <location>
            <lat>-33.825071</lat>
            <lng>151.1904</lng>
        </location>
        <location_type>ROOFTOP</location_type>
        </geometry>
        <propertyid>GANSW717827087</propertyid>
        <boundaries>
        <boundary>
            <name>SA1</name>
            <code>1140037</code>
        </boundary>
        <boundary>
            <name>SA2</name>
            <code>121011400</code>
        </boundary>
        <boundary>
            <name>SA3</name>
            <code>12101</code>
        </boundary>
        <boundary>
            <name>SA4</name>
            <code>121</code>
        </boundary>
        </boundaries>
    </result>    
    </results>
</geocode>