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.

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
An ISO 8601 formatted date
When present, an ISO 8601 formatted date
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.

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.

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

Attribute Necessity Description
An ISO 8601 formatted date
An ISO 8601 formatted date
An integer number of seconds, greater than 0
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.