Working with Time Series Data
This page describes how to read, write and delete time series data with the PowerTSM HTTP API, including reading aggregated data. It starts with an overview of the dimensions in which a time series can store data.
Time Series Dimensions
Section titled “Time Series Dimensions”A time series can store data across up to three dimensions:
- Data dimension — current values
- History dimension — historized (audit) values written at a historic date
- Quotation dimension — versioned values
For details on historization and quotations, see Enabling Historization.
Reading Data
Section titled “Reading Data”GET /repositories/{repository}/timeSeries/{timeSeries}/dataThe {timeSeries} path segment accepts the time series name or an ID prefixed with id:.
Required Parameters
Section titled “Required Parameters”| Parameter | Type | Default | Required | Description |
|---|---|---|---|---|
from |
string |
— | ✓ | Start of the period to read (ISO 8601). |
to |
string |
— | ✓ | End of the period to read (ISO 8601). |
Read data for a period
Section titled “ Read data for a period”GET /repositories/TSM_Example_Repository/timeSeries/TSM_Example_TimeSeries/data?from=2024-01-01&to=2024-02-01Optional Parameters
Section titled “Optional Parameters”| Parameter | Type | Default | Required | Description |
|---|---|---|---|---|
cyclic |
boolean |
— | Whether to read as cyclic data. Defaults to the setting of the time series. | |
function |
number |
— | Function type to use when reading. Defaults to the setting of the time series. | |
interval.type |
number |
— | Interval type for the returned data. Defaults to the setting of the time series. | |
interval.multiplier |
number |
1 |
Interval multiplier. | |
intervalTransformationMethod |
number |
— | Aggregation method when reading at a different interval. Defaults to the setting of the time series. | |
unit |
string |
— | Unit symbol to convert the data into. Defaults to the setting of the time series. | |
timeZone |
string |
— | Time zone for the returned data. Defaults to the setting of the time series. | |
historicDateTime |
string |
— | Read data as it existed at a specific point in history (ISO 8601). Defaults to the current state. | |
quotation.from |
string |
— | Lower bound of quotations to include (ISO 8601). | |
quotation.to |
string |
— | Upper bound of quotations to include (ISO 8601). | |
quotationBehavior |
number |
— | How to select data when multiple quotations exist. Defaults to the setting of the time series. |
Reading in a Different Interval
Section titled “Reading in a Different Interval”To receive hourly data from a time series stored in a 15-minute interval, override interval.type and interval.multiplier. The data is aggregated using the interval transformation method of the time series unless overridden with intervalTransformationMethod.
Read the data in 2 hour intervals.
- Interval type =
3( = hour) - Interval multiplier =
2
GET /repositories/{repository}/timeSeries/{timeSeries}/data?from=2024-01-01&to=2024-02-01&interval.type=3&interval.multiplier=2For more information on intervals see Intervals.
Reading in a Different Unit
Section titled “Reading in a Different Unit”To receive data converted to a different unit, provide the target unit symbol. Unit conversion paths must be configured in the repository.
GET /repositories/{repository}/timeSeries/{timeSeries}/data?from=2024-01-01&to=2024-02-01&unit=kWReading Historical Data
Section titled “Reading Historical Data”To read data as it existed at a specific point in time, provide historicDateTime. Historization must be enabled on the time series.
GET /repositories/{repository}/timeSeries/{timeSeries}/data?from=2024-01-01&to=2024-02-01&historicDateTime=2024-06-15T10:00:00ZReading Aggregated Data
Section titled “Reading Aggregated Data”To retrieve an aggregation of all values in the given time frame. The transformation method can be manually chosen, otherwise defaults are used.
The aggregation method used is determined by the following hierarchy:
- The
intervalTransformationMethodquery parameter - If not specified, the
Aggregation Methodof the time series - If that does not exist, the default
AGGREGATIONof the unit is used (Database tableFWS_UNITCONVERSION) - If no aggregation database entry for that unit exists,
Averageis used
Average value of data in January 2024
Section titled “ Average value of data in January 2024”GET /repositories/{repository}/timeSeries/{timeSeries}/data/total?from=2024-01-01&to=2024-02-01&intervalTransformationMethod=2Writing Data
Section titled “Writing Data”The request body specifies the data points along with metadata describing their format. The service converts the incoming data to match the time series definition (interval, unit, time zone) before storing it.
Write time series data
Section titled “ Write time series data”Request
POST /repositories/{repository}/timeSeries/{timeSeries}/dataRequest Body
{ "unit": { "identifier": "W", "storageInformation": { "repositoryName": "TSM_Example_Repository" } }, "interval": { "type": 4, "multiplier": 1 }, "cyclic": true, "function": 2, "timeZone": "W. Europe Standard Time", "data": [ { "time": "2024-01-01T00:00:00+01:00", "value": 550.0, "flag": 5 }, { "time": "2024-02-01T00:00:00+01:00", "value": 450.5, "flag": 9 }, { "time": "2024-03-01T00:00:00+01:00", "value": 475.75, "flag": 9 } ]}Error response for a timestamp outside the valid range
Section titled “ Error response for a timestamp outside the valid range”Response
{ "title": "HK15190", "status": 400, "detail": "Operations with the timestamp 0001-01-01T00:00:00.0000000+00:00 are not possible because it is before the minimum (0001-01-02T00:00:00.0000000+00:00) or after the maximum (9999-12-30T23:59:59.9999999+00:00) of the valid range.", "traceId": "00-39a886d6d306017425ac3a399eb54488-ae323cc0d588b069-00"}Writing Quotation Data
Section titled “Writing Quotation Data”To write data for a specific quotation date, include the quotationDateTime query parameter:
Write quotation data
Section titled “ Write quotation data”POST /repositories/{repository}/timeSeries/{timeSeries}/data?quotationDateTime=2024-06-15T10:00:00ZError response for a non-quotation time series
Section titled “ Error response for a non-quotation time series”Response
{ "title": "HK15136", "status": 400, "detail": "Writing with quotation date and time is only possible for time series for which quotations are enabled.", "traceId": "00-39a886d6d306017425ac3a399eb54488-ae323cc0d588b069-00"}Writing Data with Time Spans
Section titled “Writing Data with Time Spans”For non-cyclic data where each value covers an explicit time range, use the datatimespan endpoint:
Request
POST /repositories/{repository}/timeSeries/{timeSeries}/datatimespanRequest Body
[ { "value": 1.0, "flag": 9, "period": { "from": "2025-10-29T12:00:00Z", "to": "2025-10-29T13:00:00Z" } }, { "value": 0.1, "flag": 9, "period": { "from": "2025-10-29T13:00:00Z", "to": "2025-10-29T14:00:00Z" } }]Deleting Data
Section titled “Deleting Data”Both from and to are required.
DELETE /repositories/{repository}/timeSeries/{timeSeries}/data?from=2024-01-01&to=2024-02-01