{% extends "timeseries/base.html" %} {% block title %}Time-series endpoint documentation{% endblock %} {% block content %}
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.
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.
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.
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:
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 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 takes the following parameters: