nordic-balancing

Python client for Nordic electricity balancing and imbalance data, normalised to 15-minute UTC intervals.

Status: alpha. Releases are on PyPI. Every source is checked against its live API, but the API of this library may still change between 0.x versions. See CHANGELOG.md.

Install

pip install nordic-balancing            # httpx is the only dependency
pip install "nordic-balancing[pandas]"  # adds to_frame()

Python 3.12 or newer.

Why

Nordic balancing data is spread across several transmission system operators and eSett, each with its own API, authentication, time zone handling and resolution history. The Nordic markets moved to 15-minute resolution in stages (imbalance settlement in 2023, mFRR energy activation and intraday in 2025, day-ahead in October 2025), so the same series can change resolution mid-history.

nordic-balancing aims to give one typed interface over these sources, with every series in UTC on 15-minute intervals and a dated record of resolution and price-formula changes.

Usage

from datetime import UTC, datetime, timedelta

from nordic_balancing import BiddingZone, ESettClient, EnergiDataServiceClient

start = datetime(2026, 1, 15, tzinfo=UTC)
with EnergiDataServiceClient() as eds:
    prices = eds.imbalance_prices(start, start + timedelta(hours=1), [BiddingZone.DK1])

with ESettClient() as esett:
    nordic_prices = esett.imbalance_prices(start, start + timedelta(hours=1))  # all 12 zones

for p in prices:
    print(p.start, p.zone, p.imbalance_price_eur, p.dominating_direction)

With the pandas extra, to_frame turns any list of records into a DataFrame: one row per record, one column per field except raw, start in UTC, None as NaN, and directions as nullable integers.

from nordic_balancing import to_frame

frame = to_frame(nordic_prices).set_index(["start", "zone"])

Every query takes timezone-aware datetimes and returns intervals starting in [start, end), keyed by their UTC start. A price of None means the source has not published it yet or does not provide it. resolution retains the source's publication interval; historical hourly values are expanded into four quarters. raw is a read-only mapping over a deep copy of the source record, private to that record; only its top level rejects writes, so treat nested values as read-only too.

Set FINGRID_API_KEY to a free key from https://developer-data.fingrid.fi. Use with FingridClient() as fingrid: after importing it from nordic_balancing. Call fingrid.imbalance_prices(start, end) for FI prices, or series(dataset_id, start, end). series() expands hourly records only for datasets 319, 244, 106 and 369; any other dataset must be 15-minute, and an hourly record raises SourceError.

Svenska kraftnät needs no key. Call SvKClient().capacity_market(ReserveProduct.MFRR, start, end) for SE1–SE4 capacity prices and volumes.

Data contracts

Every client enforces the same contracts; a violation raises SourceError.

• C1 Window. Queries take aware datetimes and return exactly the intervals whose start is in [start, end), at any sub-second precision of start/end.
• C2 Pagination. Rows fetched must equal the total the source reported; a missing or invalid total, a short or empty page before the total is reached, or a mismatch is an error.
• C3 Duplicates. Two source records for the same series key (zone and interval start, plus product and direction for SvK) are an error, even when the values are equal. Two exceptions:
  • ENTSO-E: an interval published under distinct price categories (A04 and A05) with one equal price collapses to that price, with every category kept in raw. The same category twice (or two records without one), unequal prices, or equal prices at different resolutions raise.
  • Fingrid: around its 2025-03 switch an hourly and a 15-minute record can cover the same quarter. The hourly value is kept before 2025-03-18T23:00Z and the 15-minute value from then on; the other stays in raw["<dataset>_superseded"]. Two records with the same start and resolution raise.
• C4 Missing vs unpublished. An interval the source did not return is absent from the result; a record returned with a null value has that field set to None. Clients never fill gaps.
• C5 Numbers. Values must be JSON numbers (bool rejected), finite and convertible to float.
• C6 Outside window. Records outside the requested query window are an error.
• C7 Resolution. resolution is the source's publication interval; hourly records are repeated across four quarters. Sources can label the same price differently: ENTSO-E kept PT60M for SE and NO until 2025-03-18T00:00Z, eSett switched to 15 minutes on 2023-05-21T22:00Z (see docs/RELEASE_EVIDENCE.md).
• C8 Transport. Network and protocol failures surface as SourceError, never as raw httpx exceptions. HTTP 429/503 are retried, then raise RateLimitError, which is raised at once when Retry-After exceeds 300 s. HTTP 502/504, timeouts and dropped connections are retried within the same max_retries budget, then raise SourceError.

reconcile_imbalance_prices reports differences between two sources; it never merges series or picks a source. identical counts intervals present in both with the same resolution, exactly equal prices (a difference within the tolerance is a ROUNDING divergence) and, when both sides have one, the same dominating direction; other fields are not compared. Zones present in only one input are listed in primary_only_zones / reference_only_zones rather than dropped silently.

See docs/RELEASE_EVIDENCE.md for provider verification status, observed API behaviour and known limitations.

Sources

Not covered yet: Energi Data Service mFRR/aFRR datasets, and activated balancing energy volumes. Out of scope: generic day-ahead price clients and mFRR bid submission — other projects already cover those.

Development

uv sync
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run mypy
uv run pytest -m live      # calls the real APIs; not run by default

Licence

MIT — see LICENSE. Data retrieved through this library remains subject to each source's own terms of use.

This is an independent project. It is not affiliated with, endorsed by or supported by Energinet, Fingrid, Svenska kraftnät, eSett, ENTSO-E or any other data provider.