1.1.2 Context

Release Version

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

The Context API is a HTTP RESTful API that can take either a coordinate, an address or a property ID and return meaningful data about that location in XML or JSON. Context will return a: geocoded address, statistical area id's 1-4, Risk Frontiers Address Risk Rating information, Flood Exclusion Zone information, and National Flood Index information by default.

NT: You can add your own datasets to context - available linking ID's for Australia include:

  • - Locality
  • - Postcode
  • - Region
  • - Country
  • - Statistical area boundary ID1
  • - Statistical area boundary ID2
  • - Statistical area boundary ID3
  • - Statistical area boundary ID4
  • - GNAF Property ID
Contact MapData Services for more information

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 paramater.
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 Context 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/context/?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/context/?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/context/?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 GNAF 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 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 Integer 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] A array of name & ids for statistical area boundaries.
By default this will contain statistical area boundaries from 1-4 ie: SA1, SA2, SA3, SA4
datasets Array [Object] Datasets are returned as an array of objects each representing data from specific datasets that apply to the queried location.

The following datasets can be accessed by default in Context: Risk Frontiers Address Risk Ratings, Flood Exclusion Zones, and National Flood Index.

NT: You can add your own datasets to context - available linking ID's for Australia include:
  • - Locality
  • - Postcode
  • - Region
  • - Country
  • - Statistical area boundary ID1
  • - Statistical area boundary ID2
  • - Statistical area boundary ID3
  • - Statistical area boundary ID4
  • - GNAF Property ID
Contact MapData Services for more information

(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

(datasets) Datasets Object

The datasets object array within the result object represent data from specific datasets that apply to the queried location.

The following datasets can be accessed by default in Context: Risk Frontiers Address Risk Ratings, Flood Exclusion Zones, and National Flood Index.
NT: You can add your own datasets to context - available linking ID's for Australia include:

  • - Locality
  • - Postcode
  • - Region
  • - Country
  • - Statistical area boundary ID1
  • - Statistical area boundary ID2
  • - Statistical area boundary ID3
  • - Statistical area boundary ID4
  • - GNAF Property ID
Contact MapData Services for more information

The dataset object array will contain the following values by deafult:

Attribute Type Description
RiskFrontiers_AddressRiskRatings Object The Risk Frontiers Address Risk Rating information for the queried location's GNAF Property ID
RiskFrontiers_FEZ Object The Flood Exclusion Zone information for the queried location's GNAF Property ID
RiskFrontiers_NationalFloodIndex Object The National Flood Index information for the queried location's GNAF Property ID

(RF_AddressRiskRatings) Risk Frontiers Address Risk Rating Object

The Risk Frontiers Address Risk Rating is a national address database with natural peril risk rating information for flood, hailstorm, earthquake and cyclone; plus other relevant characteristics such as aspect, elevation above sea level and distance to shoreline. For more information on the risk rating values visit the website.

The Risk Frontiers Address Risk Rating Object contains the following attributes:

Attribute Type Description
gnaf_pid String The GNAF Property ID
elevation Integer Height above mean sea level in meters
aspect Integer The site aspect in degrees
bushfire_scale Integer 0-5 rating for Bushfire risk, 0 being no data available, 1 being negligible and 5 being very high.
flood_scale Integer 0-5 rating for Flood risk, 0 being no data available, 1 being negligible and 5 being very high
flood_wd100 Decimal (4,1) Water depth at 100-year ARI level in meters.
Valid value range [-1, 99.9]
e.g., “13.1 metres”.
“-1” for “Not Yet Available”.
earthquake_scale Float 0-5 rating for Quake risk, 0 being no data available, 1 being negligible and 5 being very high
soil_zone Integer 0-5 rating for soil, rating is based on the product of the PGA value on bedrock and Ground Zonation amplification factors that vary between 0.6 and 2.0 between Zones 1 and 5. 0 being no data available.
more info
hail_scale Integer 0-5 rating for Hail risk, 0 being no data available, 1 being negligible and 5 being very high
tc_scale Integer 0-5 rating for Cyclone risk, 0 being no data available, 1 being negligible and 5 being very high

(RiskFrontiers_FEZ) Flood Exclusion Zone Object

The National Flood Exclusion Zones (FEZ) database was developed by Risk Frontiers, an independent risk research centre specialising in the study of natural hazards. The database assists users in understanding if properties lie within the boundaries of a flood plain.

The Flood Exclusion Zone Object contains the following attributes:

Attribute Type Description
elevation Float Height above mean sea level in meters
level_fez_id Integer 1 or 0 (true or false), if the location is inside a flood exclusion zone
gnaf_pid String The GNAF Property Id

(RiskFrontiers_NationalFloodIndex) National Flood Index Object

The National Flood Index (NFID) database was jointly developed by Risk Frontiers & Willis Re Australia. The NFID comprises a database of flood hazard information – flood height as a function of Average Recurrence Interval - at street address resolution for communities across Australia with significant numbers of residential properties at risk to riverine flood. NFID uses City or Local Council flood information expressly to avoid unnecessary inconsistencies between flood maps used for land-use planning decisions and those used for underwriting purposes.

The National Flood Index Object contains the following attributes:

Attribute Type Description
gnaf_pid String The GNAF Property ID
elevation Float Height above mean sea level in meters
flooddepth20 Float Water depth in meters above ground level at 20 year average recurrence interval (ARI) flood level
flooddepth50 Float Water depth in meters above ground level at 50 year average recurrence interval (ARI) flood level
flooddepth100 Float Water depth in meters above ground level at 100 year average recurrence interval (ARI) flood level
flooddepthextreme Float Water depth in meters above ground level at extreme flood level
floodarigl Integer Flood ARI at ground level (assuming floor height zero meters)
floodarigl1m Integer Flood ARI at a floor height of 1 meter
floodarigl2m Integer Flood ARI at a floor height of 2 meters
confidencelevel Integer 1-5 rating confidence measure based on digital elevation model (DEM) accuracy and flood data

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 context request is made for SUITE 2 110 Pacific Highway, Greenwich 2065 NSW, Australia.

http(s)://api.nowwhere.com.au/1.1.2/context/?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"
        }],
        "datasets": [{
            "rf_addressriskratings": {
                "gnaf_pid": "GANSW717827087",
                "elevation": "88",
                "aspect": "128",
                "bushfire": "1",
                "flood": "0",
                "waterdepth": "-9.9",
                "peakgroundacceleration": "0.05",
                "soilzone": "2",
                "hailstorm": "4",
                "cyclone": "1"
            }
        }, {
            "rf_fezs": {
                "elevation": "88.0",
                "levelfezid": "1",
                "gnaf_pid": "GANSW717827087"
            }
        }, {
            "rf_nationalfloodindexs": {
                "gnaf_pid": "GANSW717827087",
                "elevation": "88.0",
                "flooddepth20": "-1.0",
                "flooddepth50": "-1.0",
                "flooddepth100": "-1.0",
                "flooddepthextreme": "-1.0",
                "floodarigl": "-1",
                "floodarigl1m": "-1",
                "floodarigl2m": "-1",
                "confidencelevel": null
            }
        }]
    }]
}

XML Response

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

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

The returned XML is shown below.

<context>
  <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>
      <datasets>
        <rf_addressriskratings>
          <gnaf_pid>GANSW717827087</gnaf_pid>
          <elevation>88</elevation>
          <aspect>128</aspect>
          <bushfire>1</bushfire>
          <flood>0</flood>
          <waterdepth>-9.9</waterdepth>
          <peakgroundacceleration>0.05</peakgroundacceleration>
          <soilzone>2</soilzone>
          <hailstorm>4</hailstorm>
          <cyclone>1</cyclone>
        </rf_addressriskratings>
        <rf_fezs>
          <elevation>88.0</elevation>
          <levelfezid>1</levelfezid>
          <gnaf_pid>GANSW717827087</gnaf_pid>
        </rf_fezs>        
        <rf_nationalfloodindexs>
          <gnaf_pid>GANSW717827087</gnaf_pid>
          <elevation>88.0</elevation>
          <flooddepth20>-1.0</flooddepth20>
          <flooddepth50>-1.0</flooddepth50>
          <flooddepth100>-1.0</flooddepth100>
          <flooddepthextreme>-1.0</flooddepthextreme>
          <floodarigl>-1</floodarigl>
          <floodarigl1m>-1</floodarigl1m>
          <floodarigl2m>-1</floodarigl2m>
          <confidencelevel />
        </rf_nationalfloodindexs>        
      </datasets>
    </result>
  </results>
</context>