Calculating Formulas
This page describes how to define formulas in the PowerTSM HTTP API and how to calculate them, either as a stored formula time series or as an ad hoc calculation. Examples using standard functions follow at the end.
Defining Formulas
Section titled “Defining Formulas”A formula definition is a string in the same format as in all other PowerTSM applications. Within the expression, a time series can be referenced either by its name or by its numeric ID using the id: prefix, for example [SolarData] + [id:23]. A custom or standard function can be indicated by its name followed by brackets and its parameters, such as BestValue([id:23],[TimeSeries2]).
Performing the Calculation
Section titled “Performing the Calculation”A formula produces no values on its own, it has to be calculated. The HTTP API offers two ways to do that, and the choice determines whether the formula becomes a permanent part of the repository or exists only for the duration of one request.
| Formula Time Series | Ad Hoc Calculation | |
|---|---|---|
| What is persisted | The formula, as part of the time series definition | Nothing |
| How results are obtained | By reading data from the time series | GET /repositories/{repository}/calculations/formulas |
| Reusable elsewhere | Yes, can be referenced by name or ID in other formulas | No |
| Typical use | A calculation that is queried repeatedly | A one-off or exploratory calculation |
Formula Time Series
Section titled “Formula Time Series”A formula time series is an ordinary time series whose definition carries a formula. It is created through the regular time series endpoint by adding the formula property. See Defining Time Series for the remaining properties.
The formula property is an object of timestamp and expression pairs. Each pair is a formula slice: the expression is applied from that point along the time series and stays in effect until the next slice succeeds it.
Create a formula time series
Section titled “ Create a formula time series”Request
POST /repositories/{repository}/timeSeriesRequest Body
{ "name": "TSM_Example_TotalRenewables", "interval": { "type": 3, "multiplier": 1 }, "cyclic": true, "function": 1, "formula": { "1971-12-31T23:00:00Z": "[SolarData] + [WindData]" }}The timestamp 1971-12-31T23:00:00Z is the default start of a formula, which corresponds to 1972-01-01T00:00:00+01:00. Using it means the expression covers the entire time series. To split the calculation into periods, add further entries:
Formula with two slices
Section titled “ Formula with two slices”{ "formula": { "1971-12-31T23:00:00Z": "[SolarData] + [WindData]", "2025-01-01T00:00:00Z": "BestValue([SolarData], [WindData])" }}Once created, the time series is read through the usual data endpoint, see Working with Time Series Data. The formula is evaluated transparently for the requested period, interval and unit, so consumers do not have to know that the series is derived.
Ad Hoc Calculations
Section titled “Ad Hoc Calculations”An ad hoc calculation evaluates a formula immediately, without creating a time series:
GET /repositories/{repository}/calculations/formulasThe response has the same shape as the timeSeries/data endpoint. Instead of naming a time series, the formula is supplied as the formulaString parameter.
The formula is URL-encoded from ([id:14]+[id:15]) to %28%5Bid%3A14%5D%2B%5Bid%3A15%5D%29.
Request
GET /repositories/TSM_SQLSERVER/calculations/formulas?formulaString=%28%5Bid%3A14%5D%2B%5Bid%3A15%5D%29&from=2025-12-05&to=2025-12-06&calculationCyclic=False&calculationFunction=1&calculationInterval.type=3&calculationInterval.multiplier=1Query Parameters
Section titled “Query Parameters”The parameters fall into two groups. Those without a prefix describe how the result is returned, and those prefixed with calculation describe how the referenced time series are read before the calculation takes place.
| Parameter | Type | Default | Required | Description |
|---|---|---|---|---|
formulaString |
string |
— | ✓ | The URL-encoded formula that shall be used in this query. |
from |
string |
— | ✓ | ISO 8601 date/time. Together with the to parameter, defines the period of time for which data is to be returned. |
to |
string |
— | ✓ | ISO 8601 date/time. Together with the from parameter, defines the period of time for which data is to be returned. |
interval.type |
integer/string |
— | The interval type (i.e. hour, minute, etc.) in which data should be returned. Can be given either as a numeric value or as its short string representation, for example 3 or H. Defaults to the setting of the time series. |
|
interval.multiplier |
integer |
1 |
In combination with the interval.type parameter, this allows for the data to be returned in any conceivable interval, i.e. 15 minutes, 2 hours, 8 weeks, etc. |
|
cyclic |
boolean |
— | Specifies whether the data should be read as if it is cyclic or not. If not specified, the cyclic property of the underlying time series is used. | |
function |
integer/string |
StepRight |
Specifies the function type that should be used when reading the data. Can be given either as a numeric value or by name, for example 1 or StepRight. |
|
unit |
string |
— | Specifies the unit the data should be read in. Conversion is attempted if possible. If not specified, the unit of the underlying time series is used. | |
intervalTransformationMethod |
integer/string |
— | Specifies the interval transformation method that should be used when reading data in another interval than the underlying time series has set. Can be given either as a numeric value or by name, for example 2 or Average. Defaults to the setting of the time series. |
|
timeZone |
string |
— | The time zone in which the data is to be read. If this is different from the time zone of the underlying time series, some transformations may be applied. Defaults to the setting of the time series. | |
historicDateTime |
string |
— | ISO 8601 date/time in the history of the time series that should be read. If not specified, the current state of the data is read. | |
calculationInterval.type |
integer/string |
— | ✓ | The interval type to use for calculation (i.e. hour, minute, etc.). This and calculationInterval.multiplier affect how data is read from source time series prior to calculation. |
calculationInterval.multiplier |
integer |
1 |
✓ | A multiplier for the given calculationInterval.type. |
calculationCyclic |
boolean |
— | ✓ | Whether or not to calculate the data on the assumption that the underlying time series data holds cyclic data. |
calculationFunction |
integer/string |
StepRight |
✓ | The function type to use during calculation. Can be given either as a numeric value or by name, for example 1 or StepRight. |
calculationUnit |
string |
— | The unit to use during calculation. This may affect how underlying/referenced time series data is converted prior to calculation. Defaults to the setting of the time series. | |
calculationIntervalTransformationMethod |
integer/string |
— | The interval transformation method to use during calculation. If not specified, the method of the underlying time series is used. | |
calculationTimeZone |
string |
— | The time zone that should be used during calculation. This may affect results during DST transitions. If not specified, the time zone of the underlying time series is used. | |
calculationStartOfTime |
string |
— | The start of time that should be used during calculation, that is the hour when a day starts. This is usually zero and is only required in specific edge cases when reading/calculating time series in intervals greater than or equal to one day. Given as an ISO 8601 date/time. If not specified, the startOfTime property of the underlying time series is used. |
Deprecated Query Parameters
Section titled “Deprecated Query Parameters”The following parameters are still accepted, but they are deprecated and should not be used in new code. Each has a direct replacement in the table above.
| Deprecated parameter | Use instead |
|---|---|
intervalType |
interval.type |
intervalMultiplier |
interval.multiplier |
functionType |
function |
calculationIntervalType |
calculationInterval.type |
calculationIntervalMultiplier |
calculationInterval.multiplier |
calculationFunctionType |
calculationFunction |
Examples
Section titled “Examples”The following examples use standard functions, which are available without any configuration.
Average
Section titled “ Average”- Formula:
Average([in1],[in2],[in3])
Request
GET /repositories/TSM_ORACLE/calculations/formulas?formulaString=Average(%5Bin1%5D%2C%5Bin2%5D%2C%5Bin3%5D)&from=2025-12-18&to=2026-01-02&calculationCyclic=False&calculationFunction=1&calculationInterval.type=3&calculationInterval.multiplier=1Response
{ "unit": null, "interval": { "type": 3, "multiplier": 1 }, "cyclic": false, "function": 1, "timeZone": "UTC", "data": [ { "time": "2025-12-17T23:00:00.0000000+00:00", "value": 331.3333333333333, "flag": 21 }, { "time": "2025-12-18T00:00:00.0000000+00:00", "value": 0, "flag": 19 }, { "time": "2025-12-18T07:00:00.0000000+00:00", "value": 0, "flag": 7 }, { "time": "2025-12-18T14:00:00.0000000+00:00", "value": 0, "flag": 9 }, ... ]}- Formula:
Peak([TestTimeSeries]) - Time Zone of Time Series:
UTC
Request
GET /repositories/TSM_ORACLE/calculations/formulas?formulaString=Peak%28%5Bin1%5D%29&from=2025-12-18&to=2026-01-02&calculationCyclic=False&calculationFunction=1&calculationInterval.type=3&calculationInterval.multiplier=1Response
{ "unit": null, "interval": { "type": 3, "multiplier": 1 }, "cyclic": false, "function": 1, "timeZone": "UTC", "data": [ { "time": "2025-12-17T23:00:00.0000000+00:00", "value": 0, "flag": 19 }, { "time": "2025-12-19T08:00:00.0000000+00:00", "value": 10, "flag": 9 }, { "time": "2025-12-19T09:00:00.0000000+00:00", "value": 11, "flag": 9 }, ... ]}Peak with a differing calculation time zone
Section titled “ Peak with a differing calculation time zone”The peak window is evaluated in the calculation time zone. Here the peak window starts on Monday at 09:00 in the time series’ own time zone, because the request specifies CET as calculationTimeZone.
- Formula:
Peak([TestTimeSeries]) - Time Zone of Time Series:
UTC
Request
GET /repositories/TSM_ORACLE/calculations/formulas?formulaString=Peak%28%5BTestTimeSeries%5D%29&from=2025-12-18&to=2026-01-02&calculationCyclic=False&calculationFunction=1&calculationInterval.type=3&calculationInterval.multiplier=1&calculationTimeZone=CETResponse
{ "unit": null, "interval": { "type": 3, "multiplier": 1 }, "cyclic": false, "function": 1, "timeZone": "W. Central Africa Standard Time", "data": [ { "time": "2025-12-18T00:00:00.0000000+01:00", "value": 0, "flag": 19 }, { "time": "2025-12-19T09:00:00.0000000+01:00", "value": 10, "flag": 9 }, { "time": "2025-12-19T10:00:00.0000000+01:00", "value": 11, "flag": 9 }, ... ]}