Time Series API

The time series API enabling access to time-value pair datasets within entity instances

The Timeseries API is used to retrieve timeseries data points from entity types present within the catalog. Not all entity types have timeseries associated with them.

In this section, we will explore the capabilities of the Timeseries API in depth.

A quick way to get going with building your own applications is to adapt the example apps which use this and the other Consumer APIs.

All Consumer API calls happen within the context of a data sharing policy. The policy defines a data segment which you are allowed to access. Any queries which you make using the Timeseries API can only operate within the data segment you are permitted access to.

In the Catalog API documentation, you can find examples of how to search for entity instances which have timeseries associated with them.

In our sample calls, we use the standard server name and port format outlined for local installations and demos. If you have an alternative API host base URL, then enter it in the box below to update all the sample calls on this page :

Your API Host Base URL

The Consumer API can be run in production or development mode; each requiring a different header. If you are running a local installation of BitBroker, then you can switch the sample calls on this page to development mode by activating the toggle below. If you are unsure, leave this toggle off.

Apply development mode

All API calls in BitBroker require authorization. The sample calls below contain a placeholder string where you should insert your consumer API authorization token. This authorization token should have been provided to you by the coordinator user who administers the BitBroker instance. If you already have a token, enter it in the box below to update all the sample calls on this page:

Your Consumer API Authorization Token

When installing BitBroker locally, authorization is bypassed. In this scenario, you need to specify the policy you are using in a development header. Enter your desired policy in the box below to update all the sample calls on this page:

Your Current Policy

Getting Timeseries Data

You can query for a list timeseries data by issuing an HTTP/GET to the /entity/:type/:id/timeseries/:tsid end-point.

Timeseries are always housed within a parent entity type and each has a unique ID on that entity type. Hence, you will need to know the entity type ID (type), the entity instance ID (id) and timeseries ID (tsid), in order to get access to such data points.

curl http://bbk-consumer:8003/v1/entity/country/34c3ab32774042098ddc0ffa9878e4a1a60b33c0/timeseries/population \
     --header "x-bbk-auth-token: your-header-goes-here"

This will return a JSON array as follows:

[
    {
        "from": 1960,
        "value": 89608
    },
    {
        "from": 1961,
        "value": 97727
    },
    {
        "from": 1962,
        "value": 108774
    },
    {
        "from": 1963,
        "value": 121574
    },
    // other timeseries data points here
]

In this response, the attribute you will see is as follows:

Attribute	Presence	Description
`from`	always	An ISO 8601 formatted date
`to`	sometimes	When present, an ISO 8601 formatted date
`value`	always	A valid JSON data type or object

The exact nature of the value attribute will depend upon the context of the timeseries you are using. It might be as simple as an integer, or as complex as an object.

The timeseries will always be returned sorted on the from attribute. Taking the first item of a returned array, should always represent the latest data point.

Paging Timeseries

It is possible that timeseries may run to a great many data points. There is a hard limit to how many data points will be returned in a single call to this API.

The hard limit to how many data points will be returned in a single call to this API is 500

It is possible to page access to timeseries data points by using a set of URL query parameters, as follows:

Attribute	Necessity	Description
`start`	optional	An ISO 8601 formatted date
`end`	optional	An ISO 8601 formatted date
`duration`	optional	An integer number of seconds, greater than 0
`limit`	optional	An integer number of data points, between 1 and 500

Here are additional considerations for when using these paging parameters:

If you specify and end, you must also specify a start
If you specify and end, it must be after the start
If you specify and duration, you must also specify a start
You cannot specify an end and a duration

If the paging parameters are incorrect, the API will respond with a standard validation error containing details of the violation.