Reference · Data Dictionary v1.8
Data Dictionary
Field-level reference for every value the Voltstack Data API returns: name, type, unit, source and meaning,
plus the controlled vocabularies for zones, interconnectors, fuels, regions and sources.
All payloads are wrapped in the standard response envelope (source, live,
data, fetchedAt, cached, lastGood, reason,
meta) — see the API Specification §4. The meta block names the upstream, unit and timezone;
archive-backed payloads add completeness, gaps and dataAgeSeconds; multi-area
payloads add a per-area areaStatus diagnostic. lastGood: true marks real data served from a
retained last-good copy rather than a fresh upstream read. This dictionary documents the data object of
each endpoint.
Access. The key gate is set for the documented /v1 surface as a whole: one
deployment setting covers every documented path, and no section below states a key rule of its own. Key every
request: the presented-key check runs ahead of the surface setting, so a request carrying a valid data API key in the
X-API-Key header is unaffected by how that setting is configured, provided the key's scopes cover the
endpoint. Keys are scoped by endpoint family (history for the settled-history endpoints, current
for every other documented path, all for both), and a valid key presented on an endpoint outside its scopes
is refused with 403 insufficient-scope; the refusal names the required scope and the key's granted scopes
(Specification §03 and §08). As measured on 9 August 2026, a
request carrying no key is refused with 401 api-key-required on every documented /v1 path,
current feeds and settled history alike, with no documented path answering more openly than another; that statement
is dated because the surface setting is deployment configuration and can be changed without any change to this
document. A requirement beyond the key gate is a separate axis, and the API Specification states it on the endpoint
that carries it: as at this revision the only one is /v1/benchmarks/de-bess/custom, which additionally
requires the calling tenant to be on a Professional or Enterprise plan (Specification §06). The API Specification §03
is the authority on the access model, and where this dictionary and the specification disagree, the specification is
correct. Keys: research@voltstack.energy.
VOLTSTACK DATA DICTIONARYPRODUCT DOCUMENTATION
01 — Power · Day-Ahead Price
/v1/power/day-ahead → data.{prices, changes}
| Field | Type | Unit | Description |
|---|
| prices[zone] | number | EUR/MWh | Day-ahead price for the delivery slot covering the current time, keyed by bidding-zone code (see §1a). |
| changes[zone] | number | EUR/MWh | Day-on-day move vs the same delivery slot the previous day, keyed by bidding-zone code. |
Both maps are keyed by the §1a zone codes. All 11 zones price in EUR; the payload carries no
per-zone currency or unit fields.
§1a — Bidding-zone codes
| Code | Zone | Currency | Source |
|---|
| DE_LU | Germany–Luxembourg | EUR | ENTSO-E |
| FR | France | EUR | ENTSO-E |
| NL | Netherlands | EUR | ENTSO-E |
| BE | Belgium | EUR | ENTSO-E |
| AT | Austria | EUR | ENTSO-E |
| NO_1 / NO_2 | Norway (Oslo / Kr.sand) | EUR | ENTSO-E |
| SE_3 | Sweden (Stockholm) | EUR | ENTSO-E |
| DK_1 | Denmark (West) | EUR | ENTSO-E |
| ES | Spain | EUR | ENTSO-E |
| IT_NORTH | Italy (North) | EUR | ENTSO-E |
GB is not part of this endpoint: ENTSO-E's A44 series carries nothing for GB. The GB day-ahead
auction curve is served by /v1/history/n2ex-dayahead (§04a, GBP/MWh); the terminal's GB price tile reads
the Elexon Market Index internally.
02 — Power · Cross-Border Flows
/v1/power/flows → data.flows
| Field | Type | Unit | Description |
|---|
| flows[id] | number | MW | Signed net physical flow, keyed by interconnector identifier (see §2a). Positive = the link's normal direction; negative = reversed. Net of both directions at the border. |
The payload is this one map. Nameplate capacities, direction labels and utilisation are not part of
it; §2a below is the reference for reading each id's sign.
§2a — Interconnector identifiers
| id | Link | id | Link |
|---|
| IFA_1 / IFA_2 | France ↔ GB | FR_DE | France ↔ Germany |
| NSL | Norway ↔ GB | DE_NL | Germany ↔ Netherlands |
| BRITNED | Netherlands ↔ GB | DE_AT | Germany ↔ Austria |
| NEMO | Belgium ↔ GB | NO_SE | Norway ↔ Sweden |
| VIKING | Denmark ↔ GB | ES_FR | Spain ↔ France |
| FR_IT | France ↔ Italy | | |
03 — Power · Generation Mix
/v1/power/generation?country=XX&range=1D|1W|1M → data.{range, hours[]}
| Field | Type | Unit | Description |
|---|
| range | string | — | Window the response covers: 1D (default), 1W or 1M, served from the settled A75 archive. GB (Elexon) is 1D only. |
| hour | string | HH:00 | Hour label. Multi-day ranges prefix the calendar day: MM/DD HH:00. |
nuclear, coal, gas,
biomass, hydro, solar, wind | number | MW | Average generation in that hour for each fuel bucket. A fuel is omitted when it has no generation/data. |
§3a — Fuel-bucket mapping
| Bucket | ENTSO-E PsrType | Elexon (GB) |
|---|
| gas | B03, B04, B06, B20 | CCGT, OCGT, OIL, OTHER |
| coal | B02, B05, B07, B08 | COAL |
| nuclear | B14 | NUCLEAR |
| wind | B18, B19 | WIND |
| hydro | B10, B11, B12, B13 | NPSHYD, PS |
| biomass | B01, B09, B15, B17 | BIOMASS |
| solar | B16 | n/a (GB solar is embedded/unmetered) |
VOLTSTACK DATA DICTIONARY§1–3 · POWER
History request conventions — from / to are UTC ISO dates
(YYYY-MM-DD), window capped at 3 years. When real coverage starts later than from, the payload
declares it via oldestAvailable instead of silently returning a shorter series.
04 — Power · Day-Ahead History
/v1/history/day-ahead?zone=XX&from=…&to=… → data
| Field | Type | Unit | Description |
|---|
| zone | string | — | Bidding-zone code (see §1a). |
| points[].t | integer | epoch ms | Delivery-slot start (UTC). Resolution follows the market — PT60M or PT15M, inferred from point spacing per window. |
| points[].p | number | ccy/MWh | Settled day-ahead price for that slot (ENTSO-E A44 — the same series behind §1's live value). |
| oldestAvailable | string | ISO date | Earliest settled point held for the zone. Archive is ~2 years deep and extended daily. |
04a — Power · GB N2EX Day-Ahead History
/v1/history/n2ex-dayahead?from=…&to=… → data
| Field | Type | Unit | Description |
|---|
| zone | string | — | Fixed GB series — no zone parameter. |
| points[].t | integer | epoch ms | Delivery-slot start (UTC); resolution inferred from point spacing, as §4. |
| points[].p | number | GBP/MWh | Settled N2EX day-ahead auction price for that slot. |
| oldestAvailable | string | ISO date | True archive start, reported rather than silently truncated. |
GB is §4's honest gap: ENTSO-E's A44 series carries nothing for GB, so the real GB auction curve
comes from the Nord Pool N2EX data portal instead. Anonymous portal access backfills only ~2 months; depth past
that accrues one day at a time from the live worker fetch. Same envelope and meta conventions as §4
(completeness, gaps, dataAgeSeconds); window capped at 3 years.
05 — Power · Realized Volatility
/v1/history/realized-vol?zone=XX&from=…&to=… → data
| Field | Type | Unit | Description |
|---|
| zone | string | — | Bidding-zone code (see §1a). |
| points[].date / dateMs | string / integer | ISO date / epoch ms | Display day (UTC). |
| points[].vol7d, vol30d, vol90d | number | null | ccy/MWh | Rolling sample standard deviation of day-over-day changes in the daily baseload price over 7/30/90-day windows. Null while real history is thinner than the window. |
| oldestAvailable | string | ISO date | Earliest settled day-ahead point held for the zone. |
A derived measure computed from §4's settled series, not a vendor-provided one — no free options data
exists for EU power. Never annualized; log returns are deliberately not used because EU day-ahead prices go negative.
06 — Power · Merit Order
/v1/power/merit-order?country=XX → data
| Field | Type | Unit | Description |
|---|
| country | string | — | DE or FR live today; capacity coverage DE, FR, ES, IT, NL, NO, SE, PL. |
| capacityYear | integer | year | ENTSO-E reference year of the capacity figures. Fuels retired before that year are excluded entirely, never carried forward stale. |
| stack[].fuel | string | — | wind · solar · hydro · nuclear · biomass · coal · gas · oil, in ascending modeled cost. |
| stack[].installedMw | number | MW | Installed capacity (A68). |
| stack[].unavailableMw | number | MW | Sum of currently active derates from outage messages (A77/A80). |
| stack[].availableMw | number | MW | installedMw − unavailableMw, floored at 0. |
| stack[].marginalCost | number | EUR/MWh | Modeled assumption, not a market quote — carried regardless of live status. |
| demandMw / demandAt | number / string | MW / ISO | Latest actual load (A65) and its delivery timestamp. |
| clearingPrice | number | EUR/MWh | Modeled cost of the marginal fuel where the cumulative stack meets demand. |
| totalAvailableMw | number | MW | Sum of availableMw across the stack. |
live is true only when capacity, derates and demand are all real for the requested
country. Derate collection covers all eight countries (DE, FR, ES, IT, NL, NO, SE, PL); a zone the collector has not
asked about is never presented as "zero MW unavailable" — the response falls back instead.
VOLTSTACK DATA DICTIONARY§4–6 · POWER HISTORY & MERIT ORDER
07 — Gas · Storage
/v1/gas/storage → data.{aggregate, countries[]}
| Field | Type | Unit | Description |
|---|
| aggregate.currentLevel | number | % | EU aggregate storage fullness. |
| aggregate.currentVolume | number | TWh | Working gas in store. |
| aggregate.workingCapacity | number | TWh | Total working capacity. |
| aggregate.gasDayStart | string | ISO date | Gas day the value applies to. |
| countries[].id | string | — | GIE_DE, GIE_IT, GIE_FR, GIE_NL, GIE_AT, GIE_UK. |
| countries[].currentPct | number | % | Country storage fullness. |
08 — Gas · LNG Terminals
/v1/gas/lng → data.{aggregate, countries[]}
| Field | Type | Unit | Description |
|---|
| aggregate.sendOut | number | GWh/d | LNG regasified and sent out to the grid — the LNG demand signal. |
| aggregate.sendOutUtil | number | % | Send-out vs declared max send-out capacity (dtrs). |
| aggregate.fullness | number | % | LNG tank inventory vs declared max inventory. |
| aggregate.dtrs | number | GWh/d | Declared total reference send-out (max capacity). |
| countries[].id | string | — | ES, FR, NL, IT, BE. |
| countries[].sendOut | number | GWh/d | Country send-out. |
| countries[].fullness | number | % | Country tank fullness. |
09 — Gas · Pipeline Flows
/v1/gas/pipeline-flows → data.{points[], total, gasDayStart}
| Field | Type | Unit | Description |
|---|
| points[].id | string | — | Artery key (e.g. dornum, mazara, tap, turkstream). |
| points[].label | string | — | Interconnection-point name. |
| points[].source | string | — | Supply origin: Norway · Algeria · Azerbaijan · TurkStream. |
| points[].flow | number | GWh/d | Physical entry flow, latest complete gas day. |
| total | number | GWh/d | Sum across all arteries. |
| gasDayStart | string | ISO date | Gas day of the values used. |
10 — Weather
/v1/weather?regions=… → data[regionId][]
| Field | Type | Unit | Description |
|---|
| date | string | ISO date | Forecast day. |
| forecastHigh / Low | number | °C / °F | Daily high / low (°C for EU regions, °F for US). |
| deviation | number | deg | High vs seasonal-normal high. |
| hdd / cdd | number | deg-days | Heating / cooling degree days (base 18°C EU, 65°F US). |
| windSpeed | number | km/h · mph | Max daily wind speed. |
| precipProb | number | % | Max daily precipitation probability. |
Degree-day base: 18°C (EU) / 65°F (US) by default. An optional base query parameter
(°C, clamped 5–30) re-bases both HDD and CDD for the request; the base joins the server-side cache key, so different
bases never share a cached value.
VOLTSTACK DATA DICTIONARY§7–10 · GAS & WEATHER
11 — Gas · Storage History
/v1/history/gas-storage?from=…&to=… → data
| Field | Type | Unit | Description |
|---|
| points[].date | string | ISO date | Gas day (UTC). |
| points[].level | number | % | EU aggregate storage fullness (GIE AGSI+ — the same series behind §7's live value). |
| points[].fiveYearAvg / Min / Max | number | null | % | Avg/min/max of the same calendar day across the five prior years — the display window is never compared against itself. Null while history is thinner than the band needs. |
| oldestAvailable | string | ISO date | Earliest EU aggregate row held. History from 2015-01-01. |
12 — Gas · LNG Terminal History
/v1/history/lng-terminals?from=…&to=… → data
| Field | Type | Unit | Description |
|---|
| points[].date | string | ISO date | Gas day (UTC). |
| points[].sendOut | number | null | GWh/d | EU aggregate LNG send-out (GIE ALSI+). |
| points[].fullness | number | null | % | EU aggregate tank fullness. |
| oldestAvailable | string | ISO date | Earliest EU aggregate row held. History from 2015-01-01. |
Deliberately no five-year band here: LNG send-out is driven by spot-arbitrage economics, not the
repeatable seasonal shape underground storage has — a min/max/avg band would overclaim a "normal range".
13 — Commodities · Benchmarks
/v1/history/commodities?from=…&to=… → data
| Field | Type | Unit | Description |
|---|
| series[].id | string | — | Series identifier (see §13a). |
| series[].freq | string | — | daily or monthly — read from the stored cadence, per series. |
| series[].points[].t / .v | string / number | ISO date / see §13a | Observation date and value, ascending. |
| oldestAvailable | object | — | Earliest row held, keyed per series id — cadences clamp at different depths. History from 2015-01-01. |
§13a — Benchmark series
| id | Benchmark | FRED series | Unit | Cadence |
|---|
| brent | Brent crude | DCOILBRENTEU | USD/bbl | Daily |
| wti | WTI crude | DCOILWTICO | USD/bbl | Daily |
| henryhub | Henry Hub natural gas | DHHNGSP | USD/MMBtu | Daily |
| eu_gas | EU natural gas import price | PNGASEUUSDM | USD/MMBtu | Monthly |
| coal | Australian thermal coal | PCOALAUUSDM | USD/mt | Monthly |
VOLTSTACK DATA DICTIONARY§11–13 · GAS HISTORY & COMMODITIES
§14–25 document the constraint & event layer — the endpoints behind the dislocation widgets.
None of these carries a simulated fallback: when an upstream has nothing, the envelope says so
(live:false + reason) rather than inventing a value. An empty constraint radar is
information; a fake binding constraint is not.
Point-in-time capture. Event-grade series in this layer (REMIT UMMs §19, unit outages §20,
redispatch §16) are version-captured since 2026-07-14: every republished version is retained with its publication
timestamp. Since 2026-07-31 an append-only vintage sidecar also records each capture pass of the four forecast feeds
(§10 weather, §23 forecast risk, the GB NESO forecast behind §17a, the FR RTE forecast), keyed by capture timestamp.
The as-of query API over these vintages follows in a later revision and is not yet part of the /v1 surface.
14 — Power · Imbalance Prices
/v1/power/imbalance → data.areas
| Field | Type | Unit | Description |
|---|
| areas[id].price | number | EUR/MWh | Latest settled imbalance price for the area. Keys are country codes or DE_* control areas. |
| areas[id].at | integer | epoch ms | Start of the settled 15-minute interval (UTC). |
| meta.areaStatus[id] | string | — | ok · stale (older settled interval) · estimator (DE_* only, see §15) · no-data. |
EU areas come from ENTSO-E A85 queried per control area. Where an area still runs dual-direction
pricing (e.g. FR publishes A04 excess and A05 deficit series), the deficit price is surfaced as "the" imbalance
price — the number that prices a short position. The four German control areas never publish A85 to ENTSO-E at all
(verified empirically); their rows come from the netztransparenz.de AEP estimator and are tagged
estimator.
15 — Power · German Imbalance (AEP / reBAP)
/v1/power/imbalance-de → data
| Field | Type | Unit | Description |
|---|
| price | number | EUR/MWh | Latest published 15-minute AEP estimator value — the near-real-time reBAP proxy. |
| at | integer | epoch ms | Interval start (UTC). |
| series[].t / .v | integer / number | epoch ms / EUR/MWh | Today's 15-minute estimator series. |
Germany settles imbalance with one uniform price across all four control areas
(reBAP), published on the TSOs' shared portal netztransparenz.de — not on ENTSO-E. The estimator is
near-real-time; the quality-assured settled series follows with a ~2–3 week settlement lag. The settled
cross-border marginal price and the TSOs' scarcity flag are in §17. Settled archive from 2022.
16 — Power · German Grid Stress (Redispatch + NRV)
/v1/power/grid-stress → data
| Field | Type | Unit | Description |
|---|
| todayMwh / todayMeasures | number | MWh / count | Today's redispatch energy and measure count (UTC day). |
| activeNow | integer | count | Measures whose window covers this instant. |
| median30dMwh | number | null | MWh | Median daily redispatch energy over the trailing 30 days — today's norm. |
| nrvLatestMw / nrvLatestAt | number | null / string | MW / ISO | Live NRV system balance (Netzregelverbund saldo) and its interval. |
| daily[] | array | — | day, measures, totalMwh — 30-day daily series. |
| topPlants[] | array | — | plant, direction (increase|reduce), totalMwh, measures — today's most-instructed plants. |
| latest[] | array | — | plant, direction, start, stop, meanMw, totalMwh, instructingTso — most recent measures. |
Redispatch is the grid stress zonal prices hide: DE_LU clears as one zone while the TSOs pay to
move generation around the internal north–south constraint. Event archive from 2024-07 (~42 TWh of measures),
extended continuously.
17 — Power · German Balancing Stress
/v1/power/balancing-stress → data
| Field | Type | Unit | Description |
|---|
| afrrCapacity[] / mfrrCapacity[] | array | EUR/MW | product (POS|NEG_hh_hh), direction (up|down), blockLabel (4-h block), marginalPrice, avgPrice, deliveryStart — latest capacity-auction clearing prices per product block (pay-as-cleared). |
| cbmpSeries[] | array | EUR/MWh | at, cbmp, daPrice, spread — the PICASSO/MARI-derived cross-border marginal price (netztransparenz AEP Modul 1) against the DE_LU day-ahead price. |
| scarcityEvents[] | array | — | at, nrvSaldoMw — firings of the TSOs' own binary scarcity component (AEP Knappheitskomponente). |
The scarcity flag is the TSOs' own published column, not a derived heuristic — 18 flagged
quarter-hours in 4.5 years of history make it a genuine rare-event regime marker (most recent real episode:
2026-04-06, reBAP −6,642.76 EUR/MWh). Pairs with §16: that section shows the TSOs physically moving generation;
this one shows the price the balancing market paid.
17a — Power · GB Balancing Skew
/v1/power/gb-balancing → data
| Field | Type | Unit | Description |
|---|
| todayDate | string | ISO date | GB settlement day — LOCAL London day, not UTC. |
| bmMidSpread / bmMidSpreadAt | number | null / string | GBP/MWh / ISO | Accepted offer/bid spread vs the market index (MID) at the latest settlement period. |
| topOfStackOffer / topOfStackBid | number | null | GBP/MWh | Highest accepted offer and lowest accepted bid price in the stack. |
| midLatest | number | null | GBP/MWh | Latest MID market index price. |
| windForecastLatest / windOutturnLatest / windDeltaLatest | number | null | MW | NESO day-ahead wind forecast, Elexon outturn, and the forecast-vs-outturn delta. |
| nextDemandForecast | object | null | MW / ISO | at, value — next NESO demand-forecast point ahead of now. |
| topUnits[] | array | — | unit, side, totalMw, acceptances, latestPrice — today's most-dispatched BM units. |
Sources: Elexon Insights (BOD/BOALF/MID, event-grain acceptances) and the NESO Data Portal.
The balancing-mechanism acceptance stream is stored event-by-event and exportable in bulk.
VOLTSTACK DATA DICTIONARY§14–17a · GERMAN & GB BALANCING
18 — Power · Constraint Radar (JAO Core FBMC)
/v1/power/constraints → data
| Field | Type | Unit | Description |
|---|
| day / dayLabel | string | ISO date / — | Delivery day shown: tomorrow once SDAC results land (~13:00 CET), else today. |
| totalBoundMtus | integer | count | Distinct MTUs with at least one binding CNEC that day. |
| constraints[] | array | — | cnecName, direction, tso, hubFrom, hubTo, maxShadowPrice (EUR/MWh), boundMtus, worstMtu — binding flow-based network elements ranked by shadow price. |
| borders[] | array | MW | border ("DE → FR"), minTodayMw, medianMinMw, ratio — today's minimum MaxBex vs the 30-day median of daily minima. Ratio < 1 = tighter than usual. |
MaxBex archive: 365-day backfill (~1.3M rows), extended daily from the JAO Publication Tool —
where the Core flow-based grid actually binds, border by border. The Nordic flow-based domain (MaxBex, net
positions) is ingested to the same store under identical conventions and available via bulk extract; a served
Nordic radar follows demand.
19 — Power · REMIT Outage Ticker (UMM)
/v1/power/umm → data
| Field | Type | Unit | Description |
|---|
| events[] | array | — | Latest version of each active urgent market message, newest publication first: externalId, version, eventType, area, assetName, assetEic, unavailableMw, eventStart, eventStop, publishedAt, status. |
| activeNowCount / activeNowMw | integer / number | count / MW | Events whose unavailability window covers this instant, and their summed MW. |
| topAreas[] | array | MW | area, mw — largest currently-impacted areas. |
Messages are versioned as republished; the latest version wins and cancelled/outdated messages
drop out. Upstream: Nord Pool REMIT UMM.
20 — Power · French Nuclear Availability
/v1/power/fr-nuclear → data
| Field | Type | Unit | Description |
|---|
| fleetMw | number | MW | Nominal nuclear fleet capacity constant the curve is derived against. |
| todayMw / weekAgoMw | number | null | MW | Available capacity today and seven days ago. |
| curve[] | array | MW | day, availableMw — forward availability curve, today through D+90. |
| minPoint | object | null | MW | Deepest point of the forward curve. |
| outages[] | array | — | Latest-version active nuclear unit outages behind the curve: assetName, assetEic, unavailableMw, eventStart, eventStop, eventType, version. |
Derived from ENTSO-E A77/A80 unit outage filings: fleet nominal minus the day's deepest active
outage per unit, summed across units — a forward curve that rebuilds on every outage revision.
21 — Power · Nordic Hydro Balance
/v1/power/nordic-hydro → data
| Field | Type | Unit | Description |
|---|
| areas[] | array | % · pp | area, weekStart, fillPct, minPct, medianPct, maxPct, deviationPp, weekOverWeekPp — current reservoir fill vs the historical min/median/max band for the same ISO week. |
| nationalDeviationTwh | number | null | TWh | National deviation expressed in energy (deviation × national reservoir capacity) — traders think in TWh, not percent. |
| nationalCapacityTwh | number | TWh | NVE national reservoir capacity constant. |
NVE Magasinstatistikk, weekly cadence, history from 1995 — thirty years of the structural driver
behind Nordic and German power.
VOLTSTACK DATA DICTIONARY§18–21 · CONSTRAINTS & FUNDAMENTALS
22 — Gas · GB Physical System
/v1/gas/gb-system → data
| Field | Type | Unit | Description |
|---|
| asOf | string | null | ISO | Timestamp of the freshest instantaneous reading. |
| supplyTotalMcmD / demandTotalMcmD | number | null | mcm/d | System-wide supply and demand totals. |
| linepackMscm / linepackDayAgoMscm | number | null | mscm | Actual NTS linepack and the same-time-yesterday value (matched within a ±2 h window, never an arbitrarily old point). |
| entryPoints[] | array | mcm/d | site, slug, flowMcmD — instantaneous flow by terminal/entry point. |
| demandByCategory[] | array | mcm/d | category, flowMcmD — LDZ, power stations, industrial, interconnector, storage. |
| demandForecast[] | array | GWh/d | gasDay, valueGwhD — D-1-published NTS demand forecast for the coming gas days. |
National Gas Transmission Data Portal (open data policy). GB-only by design: the Norwegian
(Gassco) half is parked pending access terms and listed under Pending Integrations on the public status page.
23 — Weather · Forecast Risk
/v1/weather/forecast-risk → data.zones[]
| Field | Type | Unit | Description |
|---|
| zone / day | string | — | Zone id and the forecast day evaluated. |
| variables[].deltaSigned / deltaAbs | number | null | per variable | D+1 run-to-run forecast change (signed and absolute) for temperature, wind, solar. |
| variables[].deltaPercentile | number | null | % | Today's |delta| ranked against the series' own trailing 30-day distribution. |
| variables[].spread / spreadPercentile | number | null | per variable / % | Ensemble spread and its percentile rank. |
| variables[].deltaHistoryDays / spreadHistoryDays | integer | days | How much history the percentile actually stands on. |
Forecast vintages cannot be backfilled, so this series is vintage-native by construction: the
band grows one day at a time, and a young series reports its real day count instead of a fabricated percentile.
24 — Benchmarks · DE BESS Revenue Index
/v1/benchmarks/de-bess → data · custom configs: /v1/benchmarks/de-bess/custom
| Field | Type | Unit | Description |
|---|
| config | object | — | Reference battery: powerMw 1, energyMwh 2, roundTripEfficiency 0.9, cyclesPerDay 1.5. |
| months[] | array | EUR/MW | month, arbitrageEur, afrrCapacityEur, mfrrCapacityEur, fcrCapacityEur, combinedEur plus per-stream day counts — monthly revenue per MW by stream. |
| monthToDate | object | null | EUR/MW | The current month's running figure. |
| imbalanceContext[] | array | — | Monthly AEP context (not a modeled revenue stream in this version). |
| oldestAvailable | object | ISO date | Archive start per input stream (arbitrage, aFRR, mFRR, FCR). |
Arbitrage is an exact perfect-foresight optimization on settled DE_LU day-ahead prices — an upper
bound, and labeled as one. Capacity legs settle at pay-as-cleared prices from regelleistung.net. Full methodology
and assumption table are published with the benchmark.
25 — Data Quality · Cross-Validation
/v1/health/cross-checks → checks[] · the same verdicts are also rendered on the public /status page
| Field | Type | Unit | Description |
|---|
| checks[].series / zone | string | — | Verdict series and its human label, e.g. DE_LU vs SMARD. |
| checks[].day | string | ISO date | Delivery day reconciled. |
| checks[].meanAbsDiff | number | EUR/MWh | Mean absolute difference between the Voltstack archive and the reference for that day. |
| checks[].pass / checkedAt | boolean / string | — / ISO | Verdict and when the harness ran. |
A nightly harness reconciles the settled day-ahead archive against Bundesnetzagentur SMARD
(CC BY 4.0) — an independent reference — for every zone SMARD also publishes, plus Fraunhofer ISE Energy-Charts for
DE_LU as a pipeline check: Energy-Charts' price endpoint is itself SMARD-sourced (per its own license_info), so that
comparison validates our plumbing rather than adding source independence. Restatement risk is measured daily, not
assumed away. This endpoint returns a plain payload, not the standard envelope.
VOLTSTACK DATA DICTIONARY§22–25 · GAS PHYSICALS, RISK & BENCHMARKS
26 — Source Registry
The source field in every envelope maps to one of the following upstreams.
| source | Provider | Domains | Cadence |
|---|
| entsoe | ENTSO-E Transparency Platform (Web API; File Library extracts as the persisted fallback for prices, load, generation, imbalance and cross-border flows) | Power prices, flows, generation, installed capacity, outages, load | Intraday / hourly / yearly |
| elexon | Elexon BMRS (Insights) | GB price & generation | Half-hourly |
| gie-agsi | GIE AGSI+ | Gas storage | Daily (per gas day) |
| gie-alsi | GIE ALSI+ | LNG send-out & inventory | Daily (per gas day) |
| entsog | ENTSOG Transparency Platform | Gas pipeline flows | Daily (settled D+1) |
| fred | FRED — Federal Reserve Bank of St. Louis | Commodity benchmarks (oil, gas, coal) | Daily / monthly |
| open-meteo | Open-Meteo / ECMWF | Weather, HDD/CDD, forecast risk | Several runs/day |
| jao-constraints | JAO Publication Tool (Core FBMC) | Binding CNECs, shadow prices, MaxBex | Daily (SDAC results ~13:00 CET) |
| netztransparenz | netztransparenz.de (shared German TSO portal) | AEP/reBAP imbalance, redispatch, NRV, CBMP, scarcity flag | 15-min, near-real-time |
| regelleistung-capacity | regelleistung.net | FCR/aFRR/mFRR capacity clearing prices | Daily auctions |
| umm-events | Nord Pool REMIT UMM | Urgent market messages (outages, unavailability) | Continuous, versioned |
| nve-hydro | NVE Magasinstatistikk (NLOD licence) | Norwegian reservoir fill, history from 1995 | Weekly |
| national-gas | National Gas Transmission Data Portal (open data) | GB entry flows, linepack, demand, NTS forecast | Instantaneous, multiple updates/day |
| cross-validate | SMARD (Bundesnetzagentur, CC BY 4.0) · Energy-Charts (Fraunhofer ISE) | Independent day-ahead reconciliation verdicts | Nightly |
| de-bess | Voltstack derived (ENTSO-E A44 · regelleistung.net · netztransparenz AEP) | DE battery revenue index | Daily |
| n2ex-dayahead | Nord Pool N2EX data portal | GB day-ahead settled auction prices | Daily |
| elexon-bm | Elexon Insights (BOD/BOALF/MID) | GB balancing mechanism: acceptances, top-of-stack, BM-vs-MID spread | Half-hourly settlement periods |
| neso-forecast | NESO Data Portal | GB day-ahead wind + demand forecast, wind-vs-outturn delta | Daily forecast, intraday outturn |
| entsoe-ida | ENTSO-E intraday auctions (IDA1–3) | IDA prices + DA–IDA spread; ES only (sole voluntary publisher) | Three auctions/day |
| jao-nordic | JAO Publication Tool (Nordic FBMC) | Nordic MaxBex + net positions, stored; bulk extract | Daily (SDAC results) |
| eex-eua-auction | EEX (licensed 2026-07-29; primary-auction results only — spot & futures excluded) | EU ETS EUA primary-auction clearing prices; history from 2020; cancelled auctions carried as first-class rows | Auction-day (EU ~every 2 days · NIR ~yearly; per-zone freshness on meta.areaStatus) |
| rte | RTE (France) data portal — generation forecast API | FR wind, solar & aggregate generation forecast, per horizon (D-1 / intraday / nowcast); terminal today, /v1 path to follow | ~4-hourly worker pass |
| history / merit-order | Voltstack settled archive | All §4–6, §11–13 and archive-backed §14–25 endpoints; the originating provider is named in meta.upstream | Extended daily by the ingestion worker |
27 — Enumerations
reason (when live = false)
| Value | Meaning |
|---|
| no-token | Upstream credential not configured server-side; the feed upgrades the moment its key lands. |
| upstream-error | Upstream API failed, timed out, or returned unparseable data. |
| rate-limited | Request backed off to respect an upstream limit. |
| bad-request | The request itself was invalid — an unknown feed or series, or a malformed parameter — and is served with an HTTP 4xx status. Correct the request; retrying unchanged will not help. Distinct from upstream-error, which reports a failure on Voltstack's side or the provider's. |
| disabled | Feed explicitly turned off via a server-side flag. |
currency
| Code | Symbol | Applies to |
|---|
| EUR | € | Continental & Nordic power, EU gas/LNG/carbon |
| GBP | £ | GB power |
weather region ids
EU_DE, EU_FR, EU_GB, EU_NL, EU_BE, EU_ES, EU_IT, EU_NO, EU_SE, EU_PL · ERCOT_COAST, ERCOT_NORTH, ERCOT_WEST, NE_BOSTON, MW_CHICAGO, SE_ATLANTA
merit-order fuels (§6, ascending modeled cost)
wind, solar, hydro, nuclear, biomass, coal, gas, oil
Live coverage as at 2026-07-31. Exchange-licensed forward and spot domains
(EUA/UKA spot & futures, TTF/NBP gas curves, Brent/WTI oil) follow the same field conventions and are documented
per-tenant on entitlement; EEX EUA primary-auction results are live and covered by §26's eex-eua-auction row.
v1.8 · 2026-08-27: §27's reason enum gains bad-request, returned with a
4xx when the caller's own parameters are invalid (an unknown feed or series, a malformed instant or window) so a keyed
client can tell a request mistake from an outage; previously such requests answered 200 upstream-error, indistinguishable
from a capture-pipeline failure. First served by the point-in-time vintages endpoint. No field, type or unit changed.
v1.7 · 2026-08-27: the access note records the key gate's second
refusal: keys are scoped by endpoint family (history, current, all), and a valid key presented on an endpoint outside
its scopes is refused 403 insufficient-scope. Documentation catch-up to the shipped gate; Specification §03/§08 remains
the authority on the access model. No field, type or unit changed.
v1.6 · 2026-08-09: §24 no longer describes its endpoint as "public, no
auth", which was false against the shipped gate, measured 401 unkeyed on every documented /v1 path. The key gate is
now stated once, for the surface, in the access note under the lede, and no section carries a per-endpoint key rule;
that note also records the one endpoint carrying a plan requirement beyond the key gate, which is where this
dictionary and Specification §06 have to agree. §25's "public" attaches explicitly to the /status page. No field,
type or unit changed.
v1.5 · 2026-08-08: §7's storage country list and §27's weather region ids
each gain the one id that was being served and had never been documented. No field, type or unit changed.
v1.4 · 2026-07-31: document version and date published as
machine-readable meta tags (voltstack-doc-version, voltstack-doc-updated) and printed in the page header; the PDF edition is served
alongside the HTML at /docs/.
v1.3 — 2026-07-31: §1/§2 corrected to the served map shapes (GB pointer
moved to §04a); phantom commodities-benchmarks path removed from §13; §10 degree-day base parameter documented;
§25 cross-validation independence phrasing corrected; §26 gains eex-eua-auction and rte; §27 reason enum corrected;
envelope note gains lastGood and areaStatus; point-in-time capture note added to §14–25.
© 2026 Voltstack.
VOLTSTACK DATA DICTIONARYdata@voltstack.energy