3.2 Features

Release Version

This reference documents the release version of MapData Services Features. This release version of the Features is a feature-stable version, whose interfaces are guaranteed to remain as documented within these pages until this version is retired.

What is Features?

The Features HTTP API performs a spatial query on a 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/shape/searchpoint/?key=YOUR KEY HERE

Request

Requests for the Features HTTP API are made up of the Feature_Code and Parameters.

    https://data.nowwhere.com.au/v3.2/features/FEATURE_CODE?PARAMETERS

Feature Code

FEATURE_CODE is the feature code for the data set you wish to query across, for example “POI_FastFoodAu0909” to query over fast food restaurants only.

Parameters

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

Parameter Type Description
Pts String A collection of points to search around. Each point should be in the format “<longitude> <latitude>”. Points are separated with a comma. You cannot use this option with bbox.
Bbox String A bounding box which restricts results to items within its bounds. The query uses the left bottom and top right points in the format “<longitude> <latitude> , <longitude> <latitude>”. You cannot use this option with buffer or pts.
Buffer Integer The distance, in metres, from the defined points in which to search for features. Default= 1 metre. You cannot use this option with bbox.
Items Integer Maximum number of items to return. If not defined returns maximum.
Sortby String Tells the service to sort results by the chosen criteria, the default is to sort by “Feature_ID”. Any field name defined for the feature type can be specified. If this parameter is set to “distance” then the results are sorted according to radial distance from the first point in the pts parameter. Distance and Field sorting are mutually exclusive.
Filter String Allows for selection of records by filtering based on columns and values. This parameter is similar to the WHERE CLAUSE in SQLs.
Cluster String Clustering will group locations that are close together indicating there is more than one location in the area.
Fields String Allows for the selection of record attributes to return. If blank or missing (default) all record attributes are returned. Please note that when using this parameter if you require the “Location” attributes of a record your request will need to include it.

Response

The format of a Features v3.2 response can be controlled by setting the Accepts header. Currently JSON and XML are supported.

Examples

Example JSON

Finds the nearest 10 items to a point sorted by distance.

https://data.nowwhere.com.au/v3.2/features/POI_FastFoodAu0909?items=10&sortby=distance,pts=150.82 -34.016&buffer=5000 

Finds 10 items within a bounding box

https://data.nowwhere.com.au/v3.2/features/POI_FastFoodAu0909?bbox=150.82 -34.016, 151.348 -33.724&items=10 

Finds all items within a buffer to multiple points

https://data.nowwhere.com.au/v3.2/features/POI_FastFoodAu0909?pts=132 -50,132.1 -50.1, 132.2 -50.5&buffer=5000

Finds up to 100 items within a bounding box where the company name field contains "Subway" or "KFC"

https://data.nowwhere.com.au/v3.2/features/POI_FastFoodAu0909?items=100&filter=[(company Like "%Subway%" or company Like "%KFC%")]&bbox=151.07688598853%20-33.842355494582%20151.31412201147%20-33.804136234948

Example JSON response

({"Features":[ {    
                    "state":"VIC",
                    "phone1":"0394277767",
                    "fax":"",
                    "externaluri":"",
                    "postcode":"3121",
                    "distance":"77",
                    "displayname":"McDonald's",
                    "street":"227 Church Street",
                    "suburb":"Richmond",
                    "company":"McDonald's"
                },{
                     "state":"VIC",
                     "phone1":"0394284048",
                     "fax":"",
                     "externaluri":"",
                     "postcode":"3121",
                     "distance":"154",
                     "displayname":"Subway",
                     "street":"222 Bridge Road","Suburb":"Richmond",
                     "company":"Subway
                },{
                    "state":"VIC",
                    "phone1":"0394290160",
                    "fax":"",
                    "externaluri":"http://www.hudsonscoffee.com.au",
                    "postcode":"3121",
                    "distance":"602",
                    "displayname":"Hudsons Coffee Stores",
                    "street":"89 Bridge Road",
                    "suburb":"Richmond",
                    "company":"Hudsons Coffee Stores"}]
                 })

Find all items with clustering

https://data.nowwhere.com.au/v3.2/features/POI_FastFoodAu0909.json?cluster=distance:20|zoom:14

Example JSON response with clustering

    ({"Features":[
        {
            "latitude":-23.696818,
            "longitude":133.878704,
            "distance":60,
            "zoom":6,
            "contains":[
                {
                    "uuid":"73"
                },
                {
                    "uuid":"1112"
                },
                {
                    "uuid":"767"}]},
        {
            "state":"VIC",
            "phone1":"0394290160",
            "fax":"",
            "externaluri":"http://www.hudsonscoffee.com.au",
            "postcode":"3121",
            "distance":"602",
            "displayname":"Hudsons Coffee Stores",
            "featureid":"d34bbce7-755c-48bd-913d-1fd901cec983",
            "street":"89 Bridge Road",
            "suburb":"Richmond",
            "lastupdated":"11/10/2010 3:00:13 PM",
            "featuretypeid":"3f19c279-19de-4353-80c3-e0c16c644dca",
            "company":"Hudsons Coffee Stores",
            "geocoderesult":"1"}]
    })

Example XML

Finds the nearest 10 items to a point sorted by distance.

https://data.nowwhere.com.au/v3.2/features/POI_FastFoodAu0909.xml?items=10&sortby=distance,pts=150.82 -34.016&buffer=5000 

Finds 10 items within a bounding box

https://data.nowwhere.com.au/v3.2/features/POI_FastFoodAu0909.xml?bbox=150.82 -34.016, 151.348 -33.724&items=10 

Finds all items within a buffer to multiple points

https://data.nowwhere.com.au/v3.2/features/POI_FastFoodAu0909.xml?pts=132 -50,132.1 -50.1, 132.2 -50.5&buffer=5000

Finds up to 100 items within a bounding box where the company name field contains "Subway" or "KFC"

https://data.nowwhere.com.au/v3.2/features/POI_FastFoodAu0909.xml?items=100&filter=[(company Like "%Subway%" or company Like "%KFC%")]&bbox=151.07688598853%20-33.842355494582%20151.31412201147%20-33.804136234948

Example XML response

  <feature>
    <type>Feature</type>
      <state>VIC</state>
      <phone1>0394277767</phone1>
      <fax/>
      <externaluri/>
      <postcode>3121</postcode>
      <distance>77</distance>
      <displayname>McDonald's</displayname>
      <street>227 Church Street</street>
      <suburb>Richmond</suburb>
      <company>McDonald's</company>
      <geocoderesult>1</geocoderesult>
  </feature>
  <feature>
      <state>VIC</state>
      <phone1>0394284048</phone1>
      <fax/>
      <externaluri/>
      <postcode>3121</postcode>
      <distance>154</distance>
      <displayname>Subway</displayname>
      <street>222 Bridge Road</street>
      <suburb>Richmond</suburb>
      <company>Subway</company>
      <geocoderesult>1</geocoderesult>
  </feature>
  <feature>
      <state>VIC</state>
      <phone1>0394290160</phone1>
      <fax/>
      <externaluri>http://www.hudsonscoffee.com.au</externaluri>
      <postcode>3121</postcode>
      <distance>602</distance>
      <displayname>Hudsons Coffee Stores</displayname>
      <street>89 Bridge Road</street>
      <suburb>Richmond</suburb>
      <company>Hudsons Coffee Stores</company>
      <geocoderesult>1</geocoderesult>
  </feature>

Find all items with clustering

https://data.nowwhere.com.au/v3.2/features/POI_FastFoodAu0909.xml?cluster=distance:20|zoom:14

Example XML response with clustering

    <Features>
        <latitude>-23.696818</latitude>
        <longitude>133.878704</longitude>
        <distance>60</distance>
        <zoom>6</zoom>
        <contains>
            <uuid>73</uuid>
        </contains>
        <contains>
            <uuid>1112</uuid>
        </contains>
        <contains>
            <uuid>767</uuid>
        </contains>
    </Features>
    <Features>
        <state>VIC</state>
        <phone1>0394290160</phone1>
        <fax></fax>
        <externaluri>http://www.hudsonscoffee.com.au</externaluri>
        <postcode>3121</postcode>
        <distance>602</distance>
        <displayname>Hudsons Coffee Stores</displayname>
        <featureid>d34bbce7-755c-48bd-913d-1fd901cec983</featureid>
        <street>89 Bridge Road</street>
        <suburb>Richmond</suburb>
        <lastupdated>11/10/2010 3:00:13 PM</lastupdated>
        <featuretypeid>3f19c279-19de-4353-80c3-e0c16c644dca</featuretypeid>
        <company>Hudsons Coffee Stores</company>
        <geocoderesult>1</geocoderesult>
    </Features>