{% extends "timeseries/base.html" %} {% block title %}Time-series endpoint documentation{% endblock %} {% block content %}

Documentation of the time-series endpoint API

This site exposes a time-series endpoint at {{ endpoint_url }}. The endpoint exposes a simple API for querying data from a number of time-series.

What is a time-series?

A time-series is a sequence of data points, where each point is some value sampled at regular or irregular intervals over time. For more information, see the Wikipedia article.

What is available through this endpoint?

The endpoint only exposes the raw time-series data (a sequence of timestamp—real-number pairs) and metadata about how that data is held and can be queried. It does not ascribe any meaning to the data, such as the units used, how the data were collected, or what they relate to.

Time series are recorded at one or more fixed resolutions, with lower resolutions being aggregations of higher resolutions. For example, an electricity meter time series might contain average power draw (kW) for successive half-hour periods. These might then be aggregated to provide daily and weekly average power draws. The endpoint exposes the possible resolutions so that you can specify a desired resolution when fetching data.

API reference

The endpoint is available at a single base URL with query parameters used to control the response.

This implementation of the API supports content negotiation on Internet media type (MIME type). This means that you can send an Accept request header with the IMT of your preferred response serialization. Alternatively, use the format query parameter with the serialization name. Supported IMTs and serialization names are given below.

The action parameter may have one of the following values:

list
Returns a list of available time-series
info
Returns metadata about a series
fetch
Returns a time-bounded range of data from the series

The list action

{% with renderers=renderers.list action="list" %} {% include "timeseries/documentation_renderers.html" %} {% endwith %}

The list action returns a list of all series for which the endpoint can supply data. In JSON format, the response is an object containing a names member, being a list of strings. For example:

{
  "names": [
    "first_series",
    "second_series",
    "third_series"
  ]
}

As CSV the response is effectively a newline-delimited list of names:

first_series
second_series
third_series

This endpoint's series list is available as {% for renderer in renderers.list %}{% if not forloop.first %}{% if forloop.last %} and {% else %}, {% endif %}{% endif %}{{ renderer.name }}{% endfor %}.

The info action

{% with renderers=renderers.info action="info" %} {% include "timeseries/documentation_renderers.html" %} {% endwith %}

The info action will return metadata about the series named using the series query parameter. Here's an example as JSON:

{
  "series": {
    "first_series": {
      "info": {
        "updated": 1315092600000.0, 
        "interval": 1800, 
        "type": "gauge", 
        "value": 0.0, 
        "samples": [
          {
            "count": 100000, 
            "type": "average", 
            "resolution": 1800, 
            "aggregation": 1
          }, 
          {
            "count": 10000, 
            "type": "average", 
            "resolution": 86400, 
            "aggregation": 48
          }, 
          {
            "count": 10000, 
            "type": "average", 
            "resolution": 604800, 
            "aggregation": 336
          }
        ]
      }, 
      "name": "first_series"
    }
  }
}

You can specify more than one series by providing a comma-separated list as the series query parameter.

Within the info member, the interval member specifies the number of seconds between data points. The type member will either be "rate", "cumulative" or "impulse".

The samples member contains a list of sampling resolutions. Each sample has a type (one of "average", "min" and "max"), resolution (being the number of seconds between data points), an aggregation (the number of data points aggregated together), and a count (the maximum number of data points held in this sample).

In the above example, the samples provide half-hourly, daily and weekly averages.

The RDF serializations contain the same information, modelled using the time-series vocabuluary.

The fetch action

{% with renderers=renderers.fetch action="fetch" %} {% include "timeseries/documentation_renderers.html" %} {% endwith %}

The fetch action takes the following parameters:

series (required)
A comma-separated list of series for which to return data.
type (required)
The aggregation type, corresponding to that returned as a type member on a sample. Must be one of "average", "min" and "max".
resolution (optional)
The number of seconds between readings. Must match that given by a sample. Defaults to the time-series resolution (i.e. the most frequent).
startTime (optional)
The start of the time range to return. Can be either a JavaScript timestamp (milliseconds since 1970-01-01T00:00:00), or any other sane-looking timestamp (such as YYYY-MM-DDTHH:MM:SS). Defaults to 48 hours ago.
endTime (optional)
The end of the time range to return, using the same format as startTime. Defaults to now.
{% endblock %}