Curves & Data Access

Note

For full method signatures and parameters, see the API Reference.

Data in the API is stored in curves. A curve is a collection of metadata describing one or more time series. There are 4 main curve types:

• TIME_SERIES
• TAGGED
• INSTANCES
• TAGGED_INSTANCES

Additionally, there is a specialized curve type:

• PAIRED_LIST — for data structures with two related values per point.

Searching for curves

Each curve can have the following metadata attributes:

• commodity, categories, area, border_source, station
• sources, scenarios, unit, time_zone
• version, frequency, data_type

The standard way of finding curves is by searching using a combination of these attributes. You can search via the API web interface (see the documentation) or within Python using session.search():

curves = session.search(category='WND', area=['EE', 'LT'], frequency='H')

The valid values for each attribute can be accessed using the corresponding session.get_ATTRIBUTE() function.

Getting a curve object

To fetch data, first get a curve object. You can get one by searching (which returns a list of curve objects), or by name using session.get_curve():

curve = session.get_curve(name='pro ee wnd intraday mwh/h cet h a')

The returned curve object carries the curve’s metadata. The most important metadata attributes are:

• id — curve ID
• name — curve name
• curve_state — BETA, PUBLIC, DEPRECATED, or DELETED (see Curve lifecycle)
• curve_type — one of TIME_SERIES, TAGGED, INSTANCES, TAGGED_INSTANCES, or PAIRED_LIST

Access attribute values with curve.attribute_name:

>>> curve = session.get_curve(name='pro ee wnd intraday mwh/h cet h a')
>>> curve.name
'pro ee wnd intraday mwh/h cet h a'
>>> curve.curve_type
'TIME_SERIES'

Curve lifecycle

A curve’s curve_state reflects where it is in its lifecycle:

State	Label	Meaning
BETA	Beta release	Newly published curve, still being validated. Data and definition may change.
PUBLIC	Normal availability	Stable, generally available curve.
DEPRECATED	Scheduled for removal	Curve is being phased out and will be deleted. Migrate to its replacement.
DELETED	Deleted	Curve has been removed, no longer returns data, and is no longer visible in the API.

Curves move through these states in order: first BETA, then PUBLIC, then DEPRECATED, then DELETED.

You can tell a curve is deprecated by examining its curve_state when you fetch the curve metadata. We always inform you in advance when we plan to delete curves, so you have time to migrate.

Getting data from a curve

Each curve type has its own methods for fetching data. Check the type with curve.curve_type.

TIME_SERIES

A Time Series curve holds a single time series (actual values, backcasts, normals, etc.). Use get_data():

curve = session.get_curve(name='pro ee wnd intraday mwh/h cet h a')
ts = curve.get_data(data_from='2018-01-01T14:00Z', data_to='2018-02-01T14:00Z')

Note

End dates are always excluded from the result.

The method returns a TS object. You can also process data server-side (aggregate to daily/weekly/monthly/yearly) by passing additional parameters to get_data() — see the API Reference and Examples.

TAGGED

A Tagged curve holds a set of related time series, each identified by a tag (commonly used for ensemble weather data).

# Get available tags
tags = curve.get_tags()

# Get data for all tags
ts_list = curve.get_data(data_from='2018-01-01', data_to='2018-02-01')

# Get data for a single tag
ts = curve.get_data(data_from='2018-01-01', data_to='2018-02-01', tag='Avg')

# Get data for multiple tags
ts_list = curve.get_data(data_from='2018-01-01', data_to='2018-02-01',
                         tag=['Avg', '01', '12'])

INSTANCES

An Instance curve contains a time series for each issue date (typically forecasts). You can:

# Fetch a single instance by issue date
ts = curve.get_instance(issue_date='2018-01-01T00:00')

# Search for multiple instances in a date range
ts_list = curve.search_instances(
    issue_date_from='2018-07-01Z00:00',
    issue_date_to='2018-07-04Z00:00',
    with_data=True
)

# Fetch the latest available instance
ts = curve.get_latest()

Note

All three methods support server-side processing (date ranges, aggregation, filtering, timezone changes) via additional parameters. See the API Reference and Examples.

TAGGED_INSTANCES

Tagged Instance curves combine Tagged and Instance curves — each time series is defined by a unique combination of issue date and tag. Ensemble forecasts are a typical use case.

# Get available tags
tags = curve.get_tags()

# Get data for the default tag at a given issue date
ts_list = curve.get_instance(issue_date='2018-07-01T00:00')

# Get data for a single tag
ts = curve.get_instance(issue_date='2018-07-01T00:00', tag='Avg')

# Get data for multiple tags
ts_list = curve.get_instance(issue_date='2018-07-01T00:00',
                             tag=['Avg', '02', '05'])

# Search for multiple instances
ts_list = curve.search_instances(
    issue_date_from='2018-07-01Z00:00',
    issue_date_to='2018-07-04Z00:00',
    with_data=True,
    tags=['Avg', '11']
)

# Get the latest instance for a specific tag
ts = curve.get_latest(tags='03')

Note

All three methods support server-side processing via additional parameters. See the API Reference and Examples.

PAIRED_LIST

A PairedList curve contains paired values where each data point has two related values (e.g. price and volume).

# Get available tags
tags = curve.get_tags()

# Fetch paired data
paired_data = curve.get_data(
    data_from='2025-01-01',
    data_to='2025-01-31',
    with_data=True
)

# Convert to DataFrame
df = paired_data[0].to_pandas()

Note

PairedList curves do not support get_latest(), get_instance(), search_instances(), get_relative(), or get_absolute(). These methods raise a MethodNotApplicable exception.

Working with TS objects

All data-fetching methods return a TS object. The most important method is to_pandas(), which returns a pandas.Series with a date index:

>>> curve = session.get_curve(name='pro ee wnd intraday mwh/h cet h a')
>>> ts = curve.get_data(data_from="2018-01-01", data_to="2018-01-05",
...                     frequency="D", function="SUM")
>>> ts.to_pandas()
2018-01-01 00:00:00+01:00    2169.0
2018-01-02 00:00:00+01:00    3948.0
2018-01-03 00:00:00+01:00    1489.0
2018-01-04 00:00:00+01:00    1860.0
Freq: D, Name: pro ee wnd intraday mwh/h cet h a, dtype: float64

The TS class also provides simple aggregation methods: ts.sum(), ts.mean(), and ts.median().

See the Examples and pandas documentation for more on working with Series and DataFrame objects.

Working with PairedTS objects

PAIRED_LIST curves return PairedTS objects instead of TS objects. The to_pandas() method returns a pandas.DataFrame where each tag becomes a column:

>>> curve = session.get_curve(name='paired_list curve name')
>>> paired_data = curve.get_data(data_from="2025-12-18",
...                              data_to="2025-12-19", with_data=True)
>>> df = paired_data[0].to_pandas()
>>> df.head()
     price  volume
0  -581.93     5.0
1  -572.00     5.0
2  -562.97     5.0
3  -544.84     5.0
4  -536.21     5.0