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 (located at https://api.bt-hypercat.com). This guide assumes that you have already onboarded your feed (by that, we mean utilised 'Create Feed' form to capture metadata about the feed, generated feed uuid with an api key assigned to it) 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.
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
<eeml>
	<environment>
    	<data id="0">
      		<current_value>123</current_value>
    	</data>
  	</environment>
</eeml>
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.
<eeml>
	<environment>
		<data id="0">
		  <current_value>123</current_value>
		</data>
		<data id="1">
		  <current_value>456</current_value>
		</data>
		<data id="2">
		  <current_value>789</current_value>
		</data>
	</environment>
</eeml>
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.
<eeml>
			  <environment>
			    <data id="0">
			      <current_value></current_value>
			      <datapoints>
			        <value at="2015-04-14T19:59:00Z">123</value>
			        <value at="2015-04-14T20:00:10Z">456</value>
			        <value at="2015-04-14T20:00:20Z">789</value>
			        <value at="2015-04-14T20:00:30Z">123</value>
			        <value at="2015-04-14T20:00:40Z">456</value>
			      </datapoints>
			    </data>
			  </environment>
			</eeml>
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.

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 feed's metadata: curl -u {your API key}: -X POST -d@{filename} -H 'Content-Type:text/xml' -H 'Accept:*/*' {URL path}. You will need to put {feed ID} within {URL path} (pick appropriate one from the table above). 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 exactly the same as for the Developers' API: click here for details.

Sending the Data

Then, write the data and check the response, e.g.:
	// Remember:
	// import java.io.OutputStream;
	// import java.io.PrintWriter;

	// Prepare to write the data
	conn.setDoOutput(true);
	OutputStream os = conn.getOutputStream();
	PrintWriter out = new PrintWriter(os);

	// Write the data, either in one go or line by line, using
	// e.g. out.print(...), out.printf(...) or out.println(...)

	// Finish the output
	out.close();
	os.close();

	// Read the response to see if the data was accepted
	if (conn.getResponseCode() == HttpURLConnection.HTTP_OK) {
	    // Success
	} else {
	    // Failure - use the response code, conn.getResponseMessage()
	    // and/or conn.getErrorStream() to find out why.
	}
		

Terms and Conditions

Please refer to this page.