1.1.2 Place

Release Version

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

The Place HTTP API performs a spatial or text query on a point based dataset using a RESTful interface.

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/place/suggest/?key=YOUR KEY HERE

Suggest

What is Suggest?

The Suggest HTTP API performs a text query on a point based dataset using a RESTful interface.

Request

http(s)://api.nowwhere.com.au/1.1.2/place/suggest/?PARAMETERS

Parameters

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

Parameter Type Required Default Description
Query String Yes Free text to find suggestions. Minimum of 3 characters.
Datasets String Yes The name of the requested dataset.
Limit Integer No 20 The maximum number of results returned. The Maximum is 50.
Callback String No The function name to wrap the JSON object in. Used for JSON-P requests
Filters String No Country, Street, 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".
Fields String No These are extra fields to be returned. If these fields are poplulated the will be returned in an array called "CustomFields"

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. A typical result is made up of the following attributes:

Attribute Type Description
value string The returned suggestion
highlight string The returned suggestion with the submitted value formatted within
coordinate string The latitude and longitude of the location (Returned if available for the dataset)
CustomFileds Object If fields parameter has been specified and fields are found these are returned in this array

Available Datasets

Dataset Name Dataset Description Coordinates Available
gnaf Australian Addresses: PSMA GNAF (Inc. SuburbPostcodeAU, Streets) Yes
gnafLite Australian Addresses Lite (no coordinates): PSMA GNAF (Inc. SuburbPostcodeAU, Streets) No
suburbpostcodeau Australian Suburb/Postcode: PSMA Yes
geopaf NewZealand Addresses: GeoPAF (Inc. SuburbPostcodeNZ, Streets) Yes
suburbpostcodenz NewZealand Suburb and Postcodes: MDS Yes

Custom Datasets

Suggest 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 Suggest response is JSON.

Content-Type: application/json

Examples

Example JSON

http(s)://api.nowwhere.com.au/1.1.2/place/suggest/?limit=5&filters=state:nsw&query=watt&datasets=[datasets]&key=[Your API Key Here]

The returned JSON is shown below.

  { "Results" : [ { "Coordinate" : "151.3438322,-33.4231614",
        "Highlight" : "WATT STREET, GOSFORD, 2250, NSW, Australia",
        "Value" : "WATT STREET, GOSFORD, 2250, NSW, Australia",
        "CustomFields":{"locality":"Gosford"}
      },
      { "Coordinate" : null,
        "Highlight" : "Gosford, 2250, NSW, Australia",
        "Value" : "Gosford, 2250, NSW, Australia",
        "CustomFields":{"locality":"Gosford"}
      },
      { "Coordinate" : null,
        "Highlight" : "East Gosford, 2250, NSW, Australia",
        "Value" : "East Gosford, 2250, NSW, Australia",
        "CustomFields":{"locality":"East Gosford"}
      },
      { "Coordinate" : null,
        "Highlight" : "Gosford South, 2250, NSW, Australia",
        "Value" : "Gosford South, 2250, NSW, Australia",
        "CustomFields":{"locality":"Gosford South"}
      },
      { "Coordinate" : null,
        "Highlight" : "West Gosford, 2250, NSW, Australia",
        "Value" : "West Gosford, 2250, NSW, Australia",
        "CustomFields":{"locality":"West Gosford"}
      },
      { "Coordinate" : null,
        "Highlight" : "North Gosford, 2250, NSW, Australia",
        "Value" : "North Gosford, 2250, NSW, Australia",
        "CustomFields":{"locality":"North Gosford"}
      },
      { "Coordinate" : null,
        "Highlight" : "Wattening, 6568, WA, Australia",
        "Value" : "Wattening, 6568, WA, Australia",
        "CustomFields":{"locality":"Wattening"}
      },
      { "Coordinate" : null,
        "Highlight" : "Wattlebank, 4704, QLD, Australia",
        "Value" : "Wattlebank, 4704, QLD, Australia",
        "CustomFields":{"locality":"Wattlebank"}
      },
      { "Coordinate" : null,
        "Highlight" : "Watton, 2795, NSW, Australia",
        "Value" : "Watton, 2795, NSW, Australia",
        "CustomFields":{"locality":"Watton"}
      },
      { "Coordinate" : null,
        "Highlight" : "Wattamolla, 2535, NSW, Australia",
        "Value" : "Wattamolla, 2535, NSW, Australia",
        "CustomFields":{"locality":"Wattamolla"}
      }
    ],
  "Status" : "OK",
  "Total" : 10
}

SearchUID

What is SearchUID?

The SearchUID HTTP API performs an id query on a point based dataset using a RESTful interface. This query submits a unique id and finds the record matching the id

Request

http(s)://api.nowwhere.com.au/1.1.2/place/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

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

Content-Type: application/json

Examples

Example JSON

http(s)://api.nowwhere.com.au/1.1.2/place/searchuid/?distance=5000&uid=4245981&datasets=[datasets]&key=[Your API Key Here]

The returned JSON is shown below.

{ "Results" : [ { 
        "country" : "AU",
        "phone" : "02 43257456",
        "postcode" : "2250",
        "state" : "NSW",
        "store" : "True",
        "street" : "69-71 PACIFIC HIGHWAY",
        "locality" : "GOSFORD WEST",
        "location" : [ 151.33955700000001,
            -33.426695000000002
          ]
      }
    ],
  "Status" : OK,
  "Total" : 1
}

SearchNearby

What is SearchNearby?

The SearchNearby HTTP API performs a spatial query on a point 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/place/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 1000 Distance in metres from that point to search.
Limit Integer No 100 The maximum number of results returned. The Maximum is 1000.
Sortby String No Distance Field to sort results by. Results are in ascending order.
Cluster String No false Grouping of locations within a certain distance of each other. Parameter defines if clustering is to be applied by true/false and clustering precision(1-5), the current zoom level must also be passed to the service. example "&cluster=true:5&zoom=10"
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.

Content-Type: application/json

Examples

Example JSON

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

The returned JSON is shown below.

 { "Results" : [ { 
        "country" : "AU",
        "phone" : "02 43257456",
        "postcode" : "2250",
        "state" : "NSW",
        "store" : "True",
        "street" : "69-71 PACIFIC HIGHWAY",
        "locality" : "GOSFORD WEST",
        "location" : [ 151.33955700000001,
            -33.426695000000002
          ]
      },
      { "country" : "",
        "latitude" : "-33.4278830",
        "longitude" : "151.3363210",
        "phone1" : "0243295288",
        "postcode" : "2250",
        "shop_unit_no" : "",
        "state" : "NSW",
        "street" : "9 Pacific Highway",
        "locality" : "Gosford",
        "location" : [ 151.336321,
            -33.427883000000001
          ]
      },
      { "country" : "",
        "externaluri" : "",
        "fax" : "",   
        "latitude" : "-33.4267310",
        "longitude" : "151.3418850",
        "phone1" : "0243232990",
        "postcode" : "2250",
        "shop_unit_no" : "",
        "state" : "NSW",
        "street" : "112 Mann Street",
        "locality" : "Gosford",
        "_fillcolour" : "#00ff00",
        "location" : [ 151.34188499999999,
            -33.426730999999997
          ]
      }
    ],
  "Status" : OK,
  "Total" : 3
}

SearchArea

What is SearchArea?

The SearchArea HTTP API performs a spacial query on a point based dataset using a RESTful interface. This query submits a bounding box and finds locations within that area

Request

http(s)://api.nowwhere.com.au/1.1.2/place/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]". Formatted as [longitude, latitude] using the GeoJSON format.
Datasets String Yes The name of the requested dataset.
Limit Integer No 100 The maximum number of records returned. The Maximum is 1000.
Sortby String No Distance Field to sort results by. Results are in ascending order.
Cluster String No false Grouping of locations within a certain distance of each other. Parameter defines if clustering is to be applied by true/false and clustering precision(1-5), the current zoom level must also be passed to the service. example "&cluster=true:5&zoom=10"
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

SearchArea 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/place/searcharea/?&bbox=[151.32774353027344,-33.41786645959481],[151.359543800354,-33.430760851437405]&limit=3&datasets=[datasets]&key=[Your API Key Here]

The returned JSON is shown below.

 { "Results" : [ { 
        "country" : "AU",
        "phone" : "02 43257456",
        "postcode" : "2250",
        "state" : "NSW",
        "store" : "True",
        "street" : "69-71 PACIFIC HIGHWAY",
        "locality" : "GOSFORD WEST",
        "location" : [ 151.33955700000001,
            -33.426695000000002
          ]
      },
      { "country" : "",
        "latitude" : "-33.4278830",
        "longitude" : "151.3363210",
        "phone1" : "0243295288",
        "postcode" : "2250",
        "shop_unit_no" : "",
        "state" : "NSW",
        "street" : "9 Pacific Highway",
        "locality" : "Gosford",
        "location" : [ 151.336321,
            -33.427883000000001
          ]
      },
      { "country" : "",
        "externaluri" : "",
        "fax" : "",   
        "latitude" : "-33.4267310",
        "longitude" : "151.3418850",
        "phone1" : "0243232990",
        "postcode" : "2250",
        "shop_unit_no" : "",
        "state" : "NSW",
        "street" : "112 Mann Street",
        "locality" : "Gosford",
        "_fillcolour" : "#00ff00",
        "location" : [ 151.34188499999999,
            -33.426730999999997
          ]
      }
    ],
  "Status" : OK,
  "Total" : 3
}

SearchPolygon

What is SearchPolygon?

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

Request

http(s)://api.nowwhere.com.au/1.1.2/place/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.
Datasets String Yes The name of the requested dataset.
Limit Integer No 100 The maximum number of records returned. The Maximum is 1000.
Sortby String No Distance Field to sort results by. Results are in ascending order. Default sortby distance.
Cluster String No false Grouping of locations within a certain distance of each other. Parameter defines if clustering is to be applied by true/false and clustering precision(1-5), the current zoom level must also be passed to the service. example "&cluster=true:5&zoom=10"
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

SearchPolygon 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/place/searchpolygon/?limit=3&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" : [ { 
        "country" : "AU",
        "phone" : "02 43257456",
        "postcode" : "2250",
        "state" : "NSW",
        "store" : "True",
        "street" : "69-71 PACIFIC HIGHWAY",
        "locality" : "GOSFORD WEST",
        "location" : [ 151.33955700000001,
            -33.426695000000002
          ]
      },
      { "country" : "",
        "latitude" : "-33.4278830",
        "longitude" : "151.3363210",
        "phone1" : "0243295288",
        "postcode" : "2250",
        "shop_unit_no" : "",
        "state" : "NSW",
        "street" : "9 Pacific Highway",
        "locality" : "Gosford",
        "location" : [ 151.336321,
            -33.427883000000001
          ]
      },
      { "country" : "",
        "externaluri" : "",
        "fax" : "",   
        "latitude" : "-33.4267310",
        "longitude" : "151.3418850",
        "phone1" : "0243232990",
        "postcode" : "2250",
        "shop_unit_no" : "",
        "state" : "NSW",
        "street" : "112 Mann Street",
        "locality" : "Gosford",
        "_fillcolour" : "#00ff00",
        "location" : [ 151.34188499999999,
            -33.426730999999997
          ]
      }
    ],
  "Status" : OK,
  "Total" : 3
}