elering-py

A small Python client for the Elering dashboard open API — Estonian electricity and gas system data published by Elering AS.

• No dependencies. Standard library only.
• No setup. The API is public and unauthenticated — import elering and go.
• Readable calls. Endpoint groups mirror the API docs, with snake case arguments and flexible dates.
• Long ranges just work. The API caps a request at one year; longer queries are split into windows and stitched back together for you.
• Plain data out. The {"success": ..., "data": ...} envelope is unwrapped and every call returns a list[dict], ready for pandas, polars or csv.

Quickstart

Install

pip install elering-py

Requires Python 3.11 or newer.

Query data

import elering

# Nord Pool day-ahead prices for every Baltic area plus Finland
prices = elering.nps.price(start="2024-01-01", end="2024-01-02")

prices.keys()
# dict_keys(['ee', 'fi', 'lv', 'lt'])

prices["ee"][0]
# {'timestamp': 1704067200, 'price': 28.46}

# Estonian power system, right now
elering.system.latest()
# [{'timestamp': 1788104700, 'production': 375.25, 'consumption': 780.73,
#   'losses': None, 'frequency': 50.02, 'system_balance': -405.47,
#   'ac_balance': 232.37, 'production_renewable': 96.29,
#   'solar_energy_production': None}]

Into a dataframe:

import pandas as pd

df = pd.DataFrame(prices["ee"])
df["time"] = pd.to_datetime(df["timestamp"], unit="s", utc=True)

Guide

Dates and times

start and end accept a string, a date or a datetime. Naive values are treated as UTC; aware values are converted to UTC. end is inclusive, so start="2024-01-01", end="2024-01-02" covers both days' boundary hours.

from datetime import date, datetime

elering.system.values(start="2024-01-01", end=date(2024, 2, 1))
elering.system.values(start=datetime(2024, 1, 1, 6), end="2024-01-01T12:00")

Omitting both gives whatever the API considers current — usually the last day or two. Passing only one of them raises ValueError.

elering.nps.price()  # no range: the current window

Timestamps

Every row is stamped with timestamp, a Unix time in seconds. Rows are returned exactly as the API sends them; convert when you need to:

from elering import from_timestamp

row = elering.system.latest()[0]
from_timestamp(row["timestamp"])
# datetime.datetime(2026, 4, 29, 5, 5, tzinfo=datetime.timezone.utc)

Rows and groups

Most methods return a list[dict]. Endpoints that publish one series per area return a dict[str, list[dict]] instead, keyed exactly as the API keys it:

Where the API also offers a single-area variant, so does the client:

elering.nps.price(start="2024-01-01", end="2024-01-02")["ee"]
elering.nps.price_latest("EE")

elering.transmission.capacity(start="2024-01-01", end="2024-01-02")["FI"]
elering.transmission.capacity_for("FI", start="2024-01-01", end="2024-01-02")

Area codes are case-insensitive and validated locally, so a typo raises ValueError instead of costing a round trip.

Long time ranges

The API rejects any request spanning more than a year with "Maximum period is 1 year". Ranges longer than max_window (default 365 days) are therefore split into consecutive requests and concatenated in order. Because end is inclusive, consecutive windows share one row; the duplicate is dropped by timestamp, so the result is the same series you would get from a single request:

# transparently issued as several requests
rows = elering.transmission.cross_border_hourly(start="2015-01-01", end="2024-01-01")

Urgent market messages

umm.messages() is the one paginated endpoint. It walks every page by default; pass page= to fetch just one:

elering.umm.messages(event_status="active", unavailability_type="planned")
elering.umm.messages(page=1)

# every message published for one event
elering.umm.event(2189)

Errors

An empty result is returned as [] (or {}), not an error. Everything else raises a subclass of elering.EleringError:

try:
    elering.Client(max_window=None).nps.price(start="2020-01-01", end="2024-01-01")
except elering.EleringBadRequest as exc:
    print(exc.status)  # 400
    print(exc.messages)  # ['Maximum period is 1 year']

Invalid arguments (an unknown area, a lone start, an unparseable date) raise ValueError before any request is made.

Configuring a client

The module-level helpers use a shared default client. Create your own to change its behaviour:

from datetime import timedelta

with elering.Client(timeout=120, retries=5, max_window=timedelta(days=90)) as client:
    rows = client.gas_system.values(start="2024-01-01", end="2024-04-01")

Endpoints

Each attribute is available both on a Client instance and at module level (elering.nps.price(...)).

Not covered

• CSV endpoints. Every /csv path serves the same data as its JSON sibling, so the client exposes the JSON one and leaves formatting to you.
• RSS feeds. /umm/gas/rss is XML; the same messages are available as data through umm.messages().

Contributing

make setup     # create the venv and install dev dependencies
make check     # ruff lint, format check, ty type check, deptry
make test      # fast offline tests
make test-live # end-to-end tests against the real API

make test never touches the network. The live suite is deselected by default and exercises every endpoint group, the windowing logic and the response shapes.

Keeping up with the API

The endpoint methods are hand-written. The published spec declares every schema as an empty object, so it documents paths and parameters but says nothing about the data — the response shapes here were verified against the live API.

make spec-check   # fail if the published spec differs from spec/openapi.json
make spec         # refresh the vendored spec

CI runs make spec-check weekly, so spec changes show up as a reviewable diff. Adding a new endpoint is then a few lines in src/elering/_resources.py.

Known spec defects

Worked around in the hand-written layer, each verified against the live API:

• Responses are wrapped in {"success": ..., "data": ...}, which no schema mentions. The client unwraps it.
• /api/balance/total documents its first parameter as fields; it is start.
• /api/umm/single/{id} also requires id as a query parameter, and returns HTTP 500 without it.
• /api/umm/gas/messages documents its parameter as id; it is event_id.
• start and end are documented as accepting yyyy-MM-dd HH:mm; only offset-bearing ISO 8601 (2024-01-01T00:00:00Z) is actually parsed.
• The one-year limit and the inclusive end are undocumented.

License

MIT — see LICENSE. This project is not affiliated with Elering AS.