Skip to main content

Timeseries

A timeseries is a list of values against times, aligned to a calendar. You save a timeseries as a property of a master data object and read it with the Data service using its data id, objectid:property, for example NGE.POWER.DE:SPOT.

There are five kinds:

_typeWhat it is
VarTimeSeriesValues you load
VarSmartTimeSeriesCalculated from other timeseries with an expression
VarEventTimeSeriesBuilt from the events of an event list
VarMetricTimeSeriesBuilt from platform usage metrics
VarComposedTimeSeriesAn element of a composition

Smart, event, metric and composed timeseries are definitions: their values are worked out when they are read (or built), so saving one with a data field is refused.


TimeSeries​

FieldTypeRequiredWhat it is
_typeStringYesVarTimeSeries
_idStringNoThe data id within the object. When saved in an object, the property name is used
calendarStringNoThe calendar code, for example DAILY, BUSINESS, #HENG, #PT1H. Defaults to SPARSE (no fixed interval)
startDateNoThe time of the first value. Needed only when data is a list of plain numbers
dataArrayNoThe values, see Values
nameStringNoA name
descriptionStringNoA description
currencyStringNoThe currency code, for example EUR
unitsStringNoThe units code, for example MWH, see the Unit service
timezoneStringNoThe timezone of the times, for example Europe/Berlin
observedStringNoHow a value relates to its period, used when converting to another calendar: end (the default), beginning, averaged, summed, high, low, delta or none
tenorStringNoA tenor period code, for timeseries taken from a curve
sourceStringNoWhere the data comes from
dataTypeStringNoThe type of the values, defaults to any
valueTypeStringNoTRACKED (the default): values are objects with a status. BASIC: values are written with only time and value
precisionObjectNoDecimal places and rounding, see Numbers
scalingIntegerOutputThe scaling applied when the timeseries was read
propertiesObjectNoYour own properties
_statusObjectNoThe status of the whole timeseries, see Status
_checksArrayOutputThe quality checks recorded on the timeseries
_identityObjectNoThe codes other systems use for the timeseries, by provider, see Identities
_linksObjectNoLinks
_objid, _dataid, _objtype, _subtypeStringOutputSet by the platform

Values​

Each value in data is an object:

FieldTypeWhat it is
timeDate or DateTimeThe time of the value
valueNumberThe value, or "NaN" for a missing value
statusObjectOptional: the status of the value

Responses for a tracked timeseries also have "_type": "TimeValue", "_links": {} and "allowLinks": true on each value; you do not need to send them. Fields with no value (for example a timeseries with no currency) are left out of the JSON.

For a calendar with a fixed interval you can also send data as a list of plain numbers, with the time of the first one in start. Each number takes the next time of the calendar.

{
"_type": "VarTimeSeries",
"calendar": "BUSINESS",
"start": "2026-11-16",
"data": [41.85, 42.10, 41.95, 42.60, 43.05]
}

A SPARSE timeseries must use value objects.

Example​

{
"_id": "NGE.GAS.TTF:SPOT",
"_type": "VarTimeSeries",
"start": "2026-11-16",
"calendar": "BUSINESS",
"observed": "end",
"currency": "EUR",
"units": "MWH",
"name": "TTF day-ahead",
"description": "Northgate TTF day-ahead index",
"precision": {"roundingMode": "HALF_UP", "scale": 6, "useDefault": true, "store": false},
"valueType": "TRACKED",
"dataType": "any",
"properties": {},
"_links": {},
"_status": {},
"_checks": [],
"_dataid": "SPOT",
"_objid": "NGE.GAS.TTF",
"_objtype": "#Object",
"_identity": {"ETRM": "GAS_TTF_DA", "RISK": "TTF-DA-IDX"},
"data": [
{"time": "2026-11-16", "value": 41.85, "status": {}, "_type": "TimeValue", "_links": {}, "allowLinks": true},
{"time": "2026-11-17", "value": 42.10, "status": {}, "_type": "TimeValue", "_links": {}, "allowLinks": true},
{"time": "2026-11-18", "value": "NaN", "status": {"quality": "FAILED:missing"}, "_type": "TimeValue", "_links": {}, "allowLinks": true}
],
"_oid": "NGE.GAS.TTF:SPOT",
"_version": 12,
"_user": "priya.shah@northgate-energy.com",
"_timestamp": "2026-11-18T18:05:44.120",
"_tag": []
}

Smart timeseries​

A smart timeseries calculates its values from a base timeseries (and optionally other inputs) with an expression. It has the descriptive fields of a timeseries (name, description, currency, units, timezone, precision, properties) and:

FieldTypeRequiredWhat it is
_typeStringYesVarSmartTimeSeries
baseTimeSeriesReference or StringYesThe timeseries it is built on: a reference, or a data id
expressionStringYesThe ODSL expression, for example BASE * 1.1
scriptStringNoA script whose functions the expression can use
calendarStringNoConvert the result to this calendar
propertiesObjectNoOther inputs. A string that is a data id (it contains a colon) is turned into a reference to that data
{
"_id": "SPOT_GBP",
"_type": "VarSmartTimeSeries",
"name": "TTF day-ahead in GBP",
"currency": "GBP",
"units": "THM",
"baseTimeSeries": {
"_type": "VarReference",
"_service": "data",
"_source": "private",
"_oid": "NGE.GAS.TTF:SPOT"
},
"expression": "BASE * FX",
"properties": {
"FX": {
"_type": "VarReference",
"_service": "data",
"_source": "public",
"_oid": "#ECB_FX.EURGBP:SPOT"
}
}
}

See Smart Data for building smart timeseries and curves.


Event timeseries​

An event timeseries takes one property of the events in an event list as its values.

FieldTypeRequiredWhat it is
_typeStringYesVarEventTimeSeries
eventStringYesThe event list, as objectid:eventlist
propertyStringYesThe event property used as the value
filterStringNoA filter on the events, for example {'side': 'ASK'}
indexStringNoThe event date used as the time: eventtime, eventstart or eventend
calendarStringNoThe calendar, defaults to SPARSE
{
"_id": "FILL_PRICE",
"_type": "VarEventTimeSeries",
"event": "NGE.TRADES:FILLS",
"property": "price",
"filter": "{'product': 'TTF'}"
}

Metric timeseries​

A metric timeseries totals or averages platform usage metrics into a timeseries.

FieldTypeRequiredWhat it is
_typeStringYesVarMetricTimeSeries
providerStringYesThe metric provider, for example ODSLRequest or ODSLProcess
metricStringYesThe metric name, for example ReadRequests
filterStringNoA filter on the metrics
calendarStringNoThe calendar to aggregate to, for example #PT1H
observedStringNoHow to aggregate: summed, averaged, high, low, beginning or end
{
"_id": "PROCESS_RUNS_HOURLY",
"_type": "VarMetricTimeSeries",
"provider": "ODSLProcess",
"metric": "RunRequests",
"calendar": "#PT1H",
"observed": "summed"
}

See the Metric service for the providers and metrics.


Composed timeseries​

A composed timeseries is one element of a composition report, saved so it can be read like any other timeseries.

FieldTypeRequiredWhat it is
_typeStringYesVarComposedTimeSeries
compositionStringYesThe id of the composition
elementStringYesThe element (column) of the composition
name, descriptionStringNoDescriptive fields
propertiesObjectNoYour own properties
{
"_id": "SPARK_SPREAD",
"_type": "VarComposedTimeSeries",
"composition": "NGE_SPARK_SPREADS",
"element": "spread",
"name": "German clean spark spread"
}