1.1.2 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 ©   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 ©   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>