Reading Feeds

Getting started

Once you have registered for an account, you will be able to generate the API keys that you will need to access the API.

API Overview

The Developers’ API is REST-based and can be accessed by issuing HTTP GET requests. All usage is measured in hits of the API, including where access is free. The vast majority of API methods correspond to a usage of one hit; methods where this does not apply are clearly marked in the documentation. You will need to construct a URL appropriate to the dataset you’re interested in and the particular information you want to retrieve. In general, there are four URL patterns for GET requests:
Path Returns
/sensors/feeds/feed ID
/events/feeds/feed ID
Metadata about the feed and streams, with latest values and timestamps if available.
/locations/feeds/feed ID Metadata about the feed.
/locations/feeds/feed ID?near=lat,lng,radius
/locations/feeds/feed ID?bbox=west lng,north lat,east lng,south lat
Search for items in a location feed. Values for near and bbox in the query strings are defined below.
/sensors/feeds/feed ID/datapoints The most recent data points of all the datastreams, from the past 24 hours, up to 50 per datastream as available.
/sensors/feeds/feed ID/datastreams/datastream ID
/events/feeds/feed ID/datastreams/datastream ID
Metadata about the stream, with the latest value and timestamp if available.
/sensors/feeds/feed ID/datastreams/datastream ID/datapoints
/events/feeds/feed ID/datastreams/datastream ID/events
The most recent data points or events from the past 24 hours, up to 50 as available.
/sensors/feeds/feed ID/datastreams/datastream ID/datapoints?refinement parameters
/events/feeds/feed ID/datastreams/datastream ID/events?refinement parameters
Data points or events, selected according to the refinement parameters.

Request

You can make test API requests by using a program such as curl: include the username option -u followed by your key with a : appended to indicate the password is an empty string:
curl -u your API key: https://api.mksmart.org:60445/sensors/feeds/feed ID

Request Parameters

When requesting data points (as opposed to metadata) you can also add URL parameters if you want to return something other than the last 50 data points. Some parameters are particular to one or more feeds so see the feed page for the detail. The general parameters are outlined below.
Parameter Value Default Example
start ISO8601 date and time None 2010-05-07T12:52:00Z which represents 12:52pm GMT on 7 May 2010
end ISO8601 date and time None 2011-06-17T08:54:00Z which represents 8:54am GMT on 17 June 2011
limit Maximum number of events to return 50 5 i.e. return a maximum of 5 events
near latitude(decimal),longitude(decimal),radius(metres)

Click here to try out your bounding box on a real map.
None 52.0381382,-0.7576441,5000 which represents: MK-5k
bbox
(bounding box)
western_longitude(decimal),northern_latitude(decimal)
,eastern_longitude(decimal),southern_latitude(decimal)

NOTE: These are lng-lat but will be changing to lat-lng.

Click here to try out your bounding box on a real map.
None -0.7776441,52.0481382,-0.7376441,52.0281382 which represents: MK-box
When using multiple parameters at the same time, you’ll also need to note the following:
end defined end not defined
start defined startend start → now
start not defined (end minus 24 hours) → end (now minus 24 hours) → now
If limit is also set, then at most that many most-recent points will be returned.

Response

Depending upon the Accept header of the request, the response will be either in XML or JSON format. For JSON, use Accept: application/json; for XML either use Accept: text/xml or don’t send an Accept header.

Java example

Here’s how you might access the API using Java. For clarity, exception handling is omitted.

Making the Connection

First, open a connection to the server. Next you’ll need to authenticate using your API key. If you’re using Java 8+ you can use the built-in Base64 class to encode the credentials: Otherwise, you can use an external library such as Apache Commons: Alternatively, you can add your credentials using an HTTP header parameter called x-api-key:

Getting the Response

Next, you need to specify whether you’d like XML or JSON returned. All methods support either XML or JSON as a response format; many support both. Please check the individual documentation for each method to see which formats are supported and to find the structure of responses. Use an Accept header with the value application/json for JSON and text/xml for XML: or: Then you can read the response, e.g. using dom4j if you’ve requested an XML response:

Attribution

Please ensure that you mention the MK:Smart project and a link to our website (www.mksmart.org) in your application or service, either on a startup screen or an about page. In some circumstances, you may need to attribute the owner of the dataset. Any requirements for this will be provided on the dataset’s page.

Terms and Conditions

Please refer to this page.