Finding Time Series
The PowerTSM HTTP API provides the functionality to load a single time series and to find stored time series by several search options.
Loading a Single Time Series
Section titled “Loading a Single Time Series”To load a specific time series by name:
GET /repositories/{repository}/timeSeries/{timeSeries}In the endpoint GET /repositories/{repository}/timeSeries/{timeSeries}, the {timeSeries} path segment accepts either the time series name or an ID prefixed with id: (e.g., id:42).
A 200 response contains the time series object. A 404 is returned if the time series does not exist in the given repository.
Finding All Time Series
Section titled “Finding All Time Series”To retrieve all time series in a repository:
GET /repositories/{repository}/timeSeriesThe response is an array of time series objects.
Including Assigned Attributes
Section titled “Including Assigned Attributes”By default the response contains only the time series themselves. The includeAttributes query parameter extends each result with the attributes assigned to the time series and their values:
GET /repositories/{repository}/timeSeries?includeAttributes=true| Parameter | Type | Default | Required | Description |
|---|---|---|---|---|
includeAttributes |
boolean |
false |
When true, each returned time series additionally contains its assigned attributes and their data. |
The attributes are loaded together with the time series in a single query, which is considerably faster than reading them per time series afterwards. When enabled, each result gains an assignedAttributeData array; every entry holds the assigned attribute, the selected unit (only for attributes of type List, otherwise null) and the attribute’s data.
Result with assigned attributes
Section titled “ Result with assigned attributes”[ { "$successful": "true", "value": { "identifier": 10003, "storageInformation": { "repositoryName": "TSM_Example_Repository" }, "value": { "name": "KD_Test" }, "assignedAttributeData": [ { "attribute": { "identifier": 4, "storageInformation": { "repositoryName": "TSM_Example_Repository" }, "value": { "name": "Test Attribut 1", "type": { "identifier": 2, "value": { "name": "Text" } } } }, "unit": null, "data": { "2001-06-04T12:00:00+00:00": "1", "2002-06-04T12:00:00+00:00": "2", "2003-06-04T12:00:00+00:00": "3" } } ] } }]includeAttributes can be combined with the filtering, sorting and pagination options described below.
Filtering
Section titled “Filtering”The following query parameters are available to filter the results:
| Parameter | Type | Default | Required | Description |
|---|---|---|---|---|
name |
string |
— | Filter by name. Supports wildcards: ? (single character), * (multiple characters). |
|
description |
string |
— | Filter by description. | |
cyclic |
boolean |
— | Filter by cyclic flag. Can only be used in combination with a function filter. | |
function |
number |
— | Filter by function type value. | |
interval.type |
number |
— | Filter by interval type value. | |
interval.multiplier |
number |
— | Filter by interval multiplier. | |
intervalTransformationMethod |
number |
— | Filter by interval transformation method value. | |
unit |
string |
— | Filter by unit symbol. | |
timeZone |
string |
— | Filter by time zone identifier. | |
startOfTime |
string |
— | Filter by start of time (ISO 8601). | |
formula |
string |
— | Filter by formula string. | |
attribute |
string |
— | Filter by assigned attribute (see below). |
Find all minute time series matching a wildcard name
Section titled “ Find all minute time series matching a wildcard name”GET /repositories/{repository}/timeSeries?name=Oil*&interval.type=2Find cyclic time series
Section titled “ Find cyclic time series”A cyclic time series can only exist if the function type is StepRight, which is encoded as 1. Therefore, filtering for the cyclic parameter is only possible if a function=1 filter is also applied.
GET /repositories/{repository}/timeSeries?function=1&cyclic=trueFiltering by Attribute
Section titled “Filtering by Attribute”The attribute query parameter supports a rich filter syntax. Multiple attribute parameters can be included; all conditions must be met (logical AND).
Basic Syntax
Section titled “Basic Syntax”| Variant | Description |
|---|---|
?attribute=<name> |
Match time series that have the named attribute assigned |
?attribute=<name>|<value> |
Match time series where the attribute has a specific value |
?attribute=oneof(<name1>,<name2>) |
Match time series that have any of the named attributes |
?attribute=oneof(<name1>|<value1>,<name2>|<value2>) |
Match time series where any of the name/value pairs apply |
?attribute=<name>|oneof(<value1>,<value2>) |
Match time series where the attribute has any of the listed values |
Wildcards are supported in both <name> and <value>:
?— matches any single character*— matches any sequence of characters
Time Restriction
Section titled “Time Restriction”A datetime expression can be appended to any value filter to restrict the search to a specific time frame. Time series are matched only if they have the attribute value within the given period:
| Expression | Description |
|---|---|
@<datetime> |
Exactly at the given date and time |
@from:<datetime> |
At or after the given date and time |
@to:<datetime> |
At or before the given date and time |
@from:<datetime1>to:<datetime2> |
Between the two dates (both inclusive) |
When attached to a oneof(...) expression, the time restriction applies to all values within it unless a value inside oneof(...) has its own restriction.
Examples
Section titled “Examples”Basic attribute filter examples
Section titled “ Basic attribute filter examples”GET /repositories/{repository}/timeSeries?attribute=TypeGET /repositories/{repository}/timeSeries?attribute=Type|SolarGET /repositories/{repository}/timeSeries?attribute=Location|DEGET /repositories/{repository}/timeSeries?attribute=Active|trueFilter by value with a time restriction
Section titled “ Filter by value with a time restriction”GET /repositories/{repository}/timeSeries?attribute=Type|Coal@from:2020-01-01T00:00:00ZGET /repositories/{repository}/timeSeries?attribute=Type|Coal@from:2020-01-01T00:00:00Zto:2026-01-01T00:00:00ZFilter using oneof
Section titled “ Filter using oneof”GET /repositories/{repository}/timeSeries?attribute=Type|oneof(Solar,Wind,Coal)GET /repositories/{repository}/timeSeries?attribute=Location|oneof(DE,AT)GET /repositories/{repository}/timeSeries?attribute=oneof(Type|Solar,Location|DE)Combine multiple attribute filters (logical AND)
Section titled “ Combine multiple attribute filters (logical AND)”GET /repositories/{repository}/timeSeries?attribute=Location|DE&attribute=Type|SolarGET /repositories/{repository}/timeSeries?attribute=Type|Solar&attribute=Active|trueUse wildcards in name and value
Section titled “ Use wildcards in name and value”GET /repositories/{repository}/timeSeries?attribute=Type|S*GET /repositories/{repository}/timeSeries?attribute=Location|D?GET /repositories/{repository}/timeSeries?attribute=T*|SolarSorting
Section titled “Sorting”Results can be sorted using the order=<value>,<direction> parameter. The value is the property by which to order and the direction can be either ascending or descending. If no direction is specified, it uses a default. Multiple orderings can be utilized by applying the order parameter twice.
Sort by multiple fields
Section titled “ Sort by multiple fields”GET /repositories/{repository}/timeSeries?order=cyclic,descending&order=name,descendingPagination
Section titled “Pagination”The Range request header controls which subset of results is returned:
Range: timeSeries=<range-start>-<range-end>Both range-start and range-end are zero-based indices. Either can be omitted to indicate “from the beginning” or “to the end”.
Retrieve the first 50 time series
Section titled “ Retrieve the first 50 time series”GET /repositories/{repository}/timeSeriesRange: timeSeries=0-49Sort the time series by name and get the alphabetically last time series
Section titled “ Sort the time series by name and get the alphabetically last time series”GET /repositories/{repository}/timeSeries?order=name,descendingRange: timeSeries=0-0The response includes a Content-Range header indicating the returned range and total count:
Content-Range response header
Section titled “ Content-Range response header”The repository contains 312 time series and, using the Range header, 50 of them were returned. The response header looks as follows:
Content-Range: timeSeries 0-49/312