1.1.2 Shape

Release Version

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

Search Point performs a spatial query on a polygon based dataset using a RESTful interface. This query finds the polygons

Security

(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==

This service supports API Key Authentication.

(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/shape/searchpoint/?key=YOUR KEY HERE

SearchUID

What is SearchUID?

SearchUID performs a spatial query on a polygon based dataset using a RESTful interface. This query submits a unique and finds the polygon with the matching id

Request

http(s)://api.nowwhere.com.au/1.1.2/shape/searchuid/?PARAMETERS

Parameters

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

Parameter Type Required Default Description
UID String Yes The unique ID of the selected record.
Datasets String Yes The name of the requested dataset.
Fields String No Allows for the selection of record attributes to return. If blank or missing (default) all record attributes are returned.

Response

The response from the service will contain a status & results object.
The response will be returned as JSON.
A typical context response is made up of the following attributes:

Attribute Type Description
results Array An array of results objects
total int The total number of results returned
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 query was successfully parsed and at least one result returned.
ZERO_RESULTS Indicates that no errors occurred. The query was successfully parsed.

(results) Results Object

The service response contains an array of result objects. By default a result is made up of all attributes contained within the selected datasets.

Available Datasets

Custom Datasets

SearchNearby can support custom data sets, contact MapData Services to discuss options for adding your data to / or creating a Custom Dataset.

Response Content-Type (JSON )

The format of a SearchUID response is JSON.

Examples

Example JSON

http(s)://api.nowwhere.com.au/1.1.2/shape/searchuid/?point=[151.3426361,-33.4245981]&datasets=[datasets]&key=[Your API Key Here]

The returned JSON is shown below.

{"Results":[{
        "objectid":"9697",
        "state":"New South Wales",
        "overall_pop":"113074",
        "median_age_person":"28",
        "sa1_most_common_occupation":"Professionals",
        "shape":{"coordinates":[[[151.203439712,-33.8759535704999],
                                [151.203457056,-33.875853171],
                                [151.203488224,-33.8756627504999],
                                [151.203485216,-33.8754082645],
                                [151.203473728,-33.87533839],
                                [151.203457632,-33.8752691074999],
                                [151.20444384,-33.8755428889999],
                                [151.204073984,-33.8755071285],
                                [151.20375872,-33.8754765295],
                                [151.20366464,-33.8754908854999],
                                [151.203656416,-33.875546737],
                                [151.203439712,-33.8759535704999]]],
                    "type":"polygon"
                }
            }],
        "Total":1,
        Status":ok}

SearchPoint

What is SearchPoint?

SearchPoint performs a spatial query on a polygon based dataset using a RESTful interface. This query submits a point and finds the polygon intersecting that point

Request

http(s)://api.nowwhere.com.au/1.1.2/shape/searchpoint/?PARAMETERS

Parameters

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

Parameter Type Required Default Description
Point String Yes A longitude and latitude representing a point. In the format "[longitude,latitude]". Formatted as [longitude, latitude] using the GeoJSON format.
Datasets String Yes The name of the requested dataset.
Fields String No Allows for the selection of record attributes to return. If blank or missing (default) all record attributes are returned.

Response

The response from the service will contain a status & results object.
The response will be returned as JSON.
A typical context response is made up of the following attributes:

Attribute Type Description
results Array An array of results objects
total int The total number of results returned
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 query was successfully parsed and at least one result returned.
ZERO_RESULTS Indicates that no errors occurred. The query was successfully parsed.

(results) Results Object

The service response contains an array of result objects. By default a result is made up of all attributes contained within the selected datasets.

Available Datasets

Custom Datasets

SearchNearby can support custom data sets, contact MapData Services to discuss options for adding your data to / or creating a Custom Dataset.

Response Content-Type (JSON )

The format of a SearchPoint response is JSON.

Examples

Example JSON

http(s)://api.nowwhere.com.au/1.1.2/shape/searchpoint/?point=[151.3426361,-33.4245981]&datasets=[datasets]&key=[Your API Key Here]

The returned JSON is shown below.

{"Results":[{
        "objectid":"9697",
        "state":"New South Wales",
        "overall_pop":"113074",
        "median_age_person":"28",
        "sa1_most_common_occupation":"Professionals",
        "shape":{"coordinates":[[[151.203439712,-33.8759535704999],
                                [151.203457056,-33.875853171],
                                [151.203488224,-33.8756627504999],
                                [151.203485216,-33.8754082645],
                                [151.203473728,-33.87533839],
                                [151.203457632,-33.8752691074999],
                                [151.20444384,-33.8755428889999],
                                [151.204073984,-33.8755071285],
                                [151.20375872,-33.8754765295],
                                [151.20366464,-33.8754908854999],
                                [151.203656416,-33.875546737],
                                [151.203439712,-33.8759535704999]]],
                    "type":"polygon"
                }
            }],
        "Total":1,
        Status":ok}

SearchNearby

What is SearchNearby?

SearchNearby performs a spatial query on a polygon based dataset using a RESTful interface. This query submits a point and finds locations within a specified distance

Request

http(s)://api.nowwhere.com.au/1.1.2/shape/searchnearby/?PARAMETERS

Parameters

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

Parameter Type Required Default Description
Point String Yes A longitude and latitude representing a point. In the format "[longitude,latitude]". Formatted as [longitude, latitude] using the GeoJSON format.
Datasets String Yes The name of the requested dataset.
Distance Integer No 5000 Distance in metres from that point to search. Maximum distance is 100000 metres ( 100km)
Limit Integer No 100 The maximum number of results returned. The Maximum is 1000.
Fields String No Allows for the selection of record attributes to return. If blank or missing (default) all record attributes are returned.
Filters String No Country, Locality, Postcode, State, Place_Category Collection 0-n e.g. (Pyrmont, NSW, Branch, ATM, Restaurants) Country: The country to restrict suggestions to. The value of this parameter can be set to the country name or the TLD code for that country. Default is no restriction. Supported countries are Australia and New Zealand. State: 3 Char code e.g. NSW.
  • Single filter format "fieldName:value".
  • Multiple filter format "fieldName:value,fieldName:value,fieldName:value".

Response

The response from the service will contain a status & results object.
The response will be returned as JSON.
A typical context response is made up of the following attributes:

Attribute Type Description
results Array An array of results objects
total int The total number of results returned
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 query was successfully parsed and at least one result returned.
ZERO_RESULTS Indicates that no errors occurred. The query was successfully parsed.

(results) Results Object

The service response contains an array of result objects. By default a result is made up of all attributes contained within the selected datasets.

Available Datasets

Custom Datasets

SearchNearby can support custom data sets, contact MapData Services to discuss options for adding your data to / or creating a Custom Dataset.

Response Content-Type (JSON )

The format of a SearchNearby response is JSON.

Examples

Example JSON

http(s)://api.nowwhere.com.au/1.1.2/shape/searchnearby/?point=[151.3426361,-33.4245981]&datasets=[datasets]&key=[Your API Key Here]

The returned JSON is shown below.

{"Results":[{
        "objectid":"9697",
        "state":"New South Wales",
        "overall_pop":"113074",
        "median_age_person":"28",
        "sa1_most_common_occupation":"Professionals",
        "shape":{"coordinates":[[[151.203439712,-33.8759535704999],
                                [151.203457056,-33.875853171],
                                [151.203488224,-33.8756627504999],
                                [151.203485216,-33.8754082645],
                                [151.203473728,-33.87533839],
                                [151.203457632,-33.8752691074999],
                                [151.20444384,-33.8755428889999],
                                [151.204073984,-33.8755071285],
                                [151.20375872,-33.8754765295],
                                [151.20366464,-33.8754908854999],
                                [151.203656416,-33.875546737],
                                [151.203439712,-33.8759535704999]]],
                    "type":"polygon"
                }
            }],
        "Total":1,
        Status":ok}

SearchArea

What is SearchArea?

The SearchArea HTTP API performs a spatial query on a polygon based dataset using a RESTful interface. This query submits a bounding box and finds polygons within that area

Request

http(s)://api.nowwhere.com.au/1.1.2/shape/searcharea/?PARAMETERS

Parameters

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

Parameter Type Required Default Description
BBox String Yes A bounding box which restricts results to items within its bounds. The query uses the top left and bottom right points in the format "[longitude,latitude],[longitude,latitude]".
Datasets String Yes The name of the requested dataset.
Limit Integer No 50 The maximum number of records returned. The maximum results 1000.
Fields String No Allows for the selection of record attributes to return. If blank or missing (default) all record attributes are returned.
Filters String No Country, Locality, Postcode, State, Place_Category Collection 0-n e.g. (Pyrmont, NSW, Branch, ATM, Restaurants) Country: The country to restrict suggestions to. The value of this parameter can be set to the country name or the TLD code for that country. Default is no restriction. Supported countries are Australia and New Zealand. State: 3 Char code e.g. NSW.
  • Single filter format "fieldName:value".
  • Multiple filter format "fieldName:value,fieldName:value,fieldName:value".

Response

The response from the service will contain a status & results object.
The response will be returned as JSON.
A typical context response is made up of the following attributes:

Attribute Type Description
results Array An array of results objects
total int The total number of results returned
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 query was successfully parsed and at least one result returned.
ZERO_RESULTS Indicates that no errors occurred. The query was successfully parsed.

(results) Results Object

The service response contains an array of result objects. By default a result is made up of all attributes contained within the selected datasets.

Available Datasets

Custom Datasets

SearchNearby can support custom data sets, contact MapData Services to discuss options for adding your data to / or creating a Custom Dataset.

Response Content-Type (JSON )

The format of a SearchArea response is JSON.

Examples

Example JSON

http(s)://api.nowwhere.com.au/1.1.2/shape/searcharea/?&bbox=[151.32774353027344,-33.41786645959481],[151.359543800354,-33.430760851437405]&limit=10&datasets=[datasets]&key=[Your API Key Here]

The returned JSON is shown below.

 {"Results":[{
        "objectid":"9697",
        "state":"New South Wales",
        "overall_pop":"113074",
        "median_age_person":"28",
        "sa1_most_common_occupation":"Professionals",
        "shape":{"coordinates":[[[151.203439712,-33.8759535704999],
                                [151.203457056,-33.875853171],
                                [151.203488224,-33.8756627504999],
                                [151.203485216,-33.8754082645],
                                [151.203473728,-33.87533839],
                                [151.203457632,-33.8752691074999],
                                [151.2033864,-33.8750754494999],
                                [151.204073984,-33.8755071285],
                                [151.20375872,-33.8754765295],
                                [151.20366464,-33.8754908854999],
                                [151.203656416,-33.875546737],
                                [151.203439712,-33.8759535704999]]],
                    "type":"polygon"
                }
            }],
        "Total":1,
        Status":ok}

SearchPolygon

What is SearchPolygon?

The SearchPolygon HTTP API performs a spatial query on a polygon based dataset using a RESTful interface. This query submits a polygon and finds polygons within that polygon

Request

http(s)://api.nowwhere.com.au/1.1.2/shape/searchpolygon/?PARAMETERS

Parameters

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

Parameter Type Required Default Description
Polygon String Yes A polygon which restricts results to items within its bounds. The query uses an array of points in the format "[longitude,latitude]". Formatted as [longitude, latitude] using the GeoJSON format.
Limit Integer No 50 The maximum number of records returned. The Maximum is 1000.
Datasets String Yes The name of the requested dataset.
Fields String No Allows for the selection of record attributes to return. If blank or missing (default) all record attributes are returned.
Filters String No Country, Locality, Postcode, State, Place_Category Collection 0-n e.g. (Pyrmont, NSW, Branch, ATM, Restaurants) Country: The country to restrict suggestions to. The value of this parameter can be set to the country name or the TLD code for that country. Default is no restriction. Supported countries are Australia and New Zealand. State: 3 Char code e.g. NSW.
  • Single filter format "fieldName:value".
  • Multiple filter format "fieldName:value,fieldName:value,fieldName:value".

Response

The response from the service will contain a status & results object.
The response will be returned as JSON.
A typical context response is made up of the following attributes:

Attribute Type Description
results Array An array of results objects
total int The total number of results returned
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 query was successfully parsed and at least one result returned.
ZERO_RESULTS Indicates that no errors occurred. The query was successfully parsed.

(results) Results Object

The service response contains an array of result objects. By default a result is made up of all attributes contained within the selected datasets.

Available Datasets

Custom Datasets

SearchNearby can support custom data sets, contact MapData Services to discuss options for adding your data to / or creating a Custom Dataset.

Response Content-Type (JSON )

The format of a SearchPolygon response is JSON.

Examples

Example JSON

http(s)://api.nowwhere.com.au/1.1.2/shape/searchpolygon/?limit=5&Polygon=[151.33310794830322,-33.422666262544304],[151.34606838226318,-33.41912016507054],[151.35186195373535,-33.428683551067344],[151.33310794830322,-33.422666262544304]&datasets=[datasets]&key=[Your API Key Here] 

The returned JSON is shown below.

{"Results":[{
        "objectid":"9697",
        "state":"New South Wales",
        "overall_pop":"113074",
        "median_age_person":"28",
        "sa1_most_common_occupation":"Professionals",
        "shape":{"coordinates":[[[151.203439712,-33.8759535704999],
                                [151.203457056,-33.875853171],
                                [151.203488224,-33.8756627504999],
                                [151.203485216,-33.8754082645],
                                [151.203473728,-33.87533839],
                                [151.203457632,-33.8752691074999],
                                [151.20444384,-33.8755428889999],
                                [151.204073984,-33.8755071285],
                                [151.20375872,-33.8754765295],
                                [151.20366464,-33.8754908854999],
                                [151.203656416,-33.875546737],
                                [151.203439712,-33.8759535704999]]],
                    "type":"polygon"
                }
            }],
        "Total":1,
        Status":ok}