Writing Feeds: the Data Providers’ API

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. This guide assumes that you have already onboarded your feed to the Data Hub and now wish to start sending data.

API Overview

The Data Providers’ API is REST-based and can be accessed by issuing HTTP POST requests. You will need to construct a URL appropriate to the dataset you’re interested in and the particular information you want to add; you will also need to construct XML for the data to add. In general, there are three URL patterns for POST requests:
Path Updates
1 /sensors/feeds/feed ID/datapoints a single data point for a single data stream; or a single data point for each of multiple data streams; or multiple data points for multiple data stream
2 /sensors/feeds/feed ID/datastreams/datastream ID/datapoints a single data point for a single data stream; or multiple data points for a single data stream.
3 /events/feeds/feed ID/datastreams/datastream ID/events
Note that you cannot modify existing datastream IDs or change metadata.

Example Sensor XML

Note that this section only applies to sensor feeds, not to event feeds. POSTed XML is EEML, so must be begin as follows: <?xml version="1.0" encoding="UTF-8"?> <eeml xsi:schemaLocation="http://www.eeml.org/xsd/0.5.1 http://www.eeml.org/xsd/0.5.1/0.5.1.xsd" version="0.5.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.eeml.org/xsd/0.5.1"> For clarity, however, this will be shown as follows in the examples: <eeml> The following table shows some example EEML, along with a summary of its purpose and to where it should be POSTed:
XML POST to Overview and Notes
1, 2 Post a single data point to a single data stream.(1) Only one <data> element. (2) When POSTing to 2, ensure that the datastream ID matches the data ID provided in the XML. (3) The <current_value> tag can optionally take an at attribute containing an ISO-8601 timestamp (e.g. ) for the value.
1 For each of a number of data streams, post a single data point.(1) Multiple <data> elements. (2) The data streams do not have to be listed in ID order. (3) The <current_value> tag can optionally take an at attribute containing an ISO-8601 timestamp (e.g. ) for the value.
2 Post multiple data points to a single data stream.(1) The values do not have to be listed in order. (2) Ensure that the datastream ID matches the data ID provided in the XML. (3) There can be only one <data> element. (4) The at attribute is an ISO-8601 timestamp for the value.
1 Post multiple data points to multiple data stream.(1) The values do not have to be listed in order. (2) The at attribute is an ISO-8601 timestamp for the value.

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, e.g. to update a single data point in a sensor feed:
curl -u your API key: -X POST -d@filename -H 'Content-Type:text/xml' -H 'Accept:*/*' https://api.mksmart.org:60445/sensors/feeds/feed ID/datapoints
The data in filename should be in one of the supported formats: EEML, SENML or CAP, and should (of course) conform to what’s described in the metadata.

Java example

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

Making the Connection

This is almost exactly the same as for the Developers’ API: click here for details. The only difference is that the content type must be set to text/xml when POSTing data.

Sending the Data

Then, write the data and check the response, e.g.:

Terms and Conditions

Please refer to this page.