Skip to content
Documentation

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.

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]).

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

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.

flask Create a formula time series

Section titled “ Create a formula time series”

Request

POST /repositories/{repository}/timeSeries

Request 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:

flask 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.

An ad hoc calculation evaluates a formula immediately, without creating a time series:

GET /repositories/{repository}/calculations/formulas

The 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=1

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.

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

The following examples use standard functions, which are available without any configuration.

  • 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=1

Response

{
"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=1

Response

{
"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
},
...
]
}

flask 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=CET

Response

{
"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
},
...
]
}
© 2026 Volue.Version v0.6.38017 November 2026