# Glossary A reference for the domain concepts and project-specific terms used throughout `smard-cli`. The SMARD domain is German; this glossary gives the English term used in the CLI/library (where one exists) alongside the original German. > **Translation table** (the labels the `filters` catalogue carries). The CLI's > filter labels are German with an English gloss in parentheses: > > | German | English | > | --- | --- | > | Stromerzeugung | (electricity) generation | > | Stromverbrauch | (electricity) consumption | > | Residuallast | residual load | > | Großhandelspreis | wholesale price | > | Prognose | forecast | > | Braunkohle / Steinkohle | lignite / hard coal | > | Kernenergie | nuclear | > | Wasserkraft / Pumpspeicher | hydropower / pumped storage | > | Erdgas | natural gas | > | Photovoltaik | photovoltaics | --- ## SMARD & the platform **SMARD — Strommarktdaten** ("electricity market data"). The German power-market data platform operated by the **Bundesnetzagentur** (the Federal Network Agency) at [`smard.de`](https://www.smard.de). It publishes electricity generation, consumption, residual load and wholesale market prices. **Bundesnetzagentur (BNetzA).** The German Federal Network Agency, regulator of the electricity, gas, telecommunications, post and railway markets, and operator of SMARD. **chart-data API.** The open, no-authentication HTTP interface this tool wraps. It is not a query API but a **static file tree**: for each *(filter, region, resolution)* combination SMARD publishes an *index* of available window timestamps plus one *data file* per window. The base URL is `https://www.smard.de`. **Read-only, no auth.** The chart-data endpoints require no API key. This client only performs `GET` requests and never writes. No credential header is ever constructed. Redirects are **not followed** — a `3xx` surfaces as a `SmardApiError` — and only `http:`/`https:` base URLs are accepted (enforced in the default transport). See DEVELOPING.md "Design notes" for these deliberate divergences from the workspace blueprint. --- ## The request triple Almost every data call is addressed by three coordinates — a **filter**, a **region** and a **resolution** — plus, for a specific window, a **timestamp**. **filter.** A numeric series id identifying *what* time series you want (e.g. `410` = total grid load, `4068` = photovoltaic generation, `4169` = DE/LU wholesale price). The API accepts **any integer** filter id, so the CLI and client accept any integer; the bundled `FILTERS` catalogue (see `smard filters`) documents the well-known ones but is **not exhaustive**. **region.** A market or grid area code. See `smard regions`; the valid set (`RegionValues`) is `DE`, `AT`, `LU`, `DE-LU`, `DE-AT-LU`, `50Hertz`, `Amprion`, `TenneT`, `TransnetBW`, `APG`, `Creos`. **resolution.** The temporal granularity of a series: one of `hour`, `quarterhour`, `day`, `week`, `month`, `year` (`ResolutionValues`). See `smard resolutions`. **timestamp.** An **epoch-millisecond** value marking the start of one data window. Obtain valid values from `smard timestamps`; pass one to `series`. Each data file covers a fixed window (e.g. one week of hourly values). --- ## Filter groups The `FILTERS` catalogue tags each documented filter with one of four groups (`smard filters --group `): **generation (Stromerzeugung).** Realised electricity generation by source, e.g. Braunkohle/lignite (`1223`), Kernenergie/nuclear (`1224`), Wind Offshore (`1225`), Wasserkraft/hydropower (`1226`), Biomasse (`4066`), Wind Onshore (`4067`), Photovoltaik (`4068`), Steinkohle/hard coal (`4069`), Pumpspeicher/pumped storage (`4070`), Erdgas/natural gas (`4071`). **consumption (Stromverbrauch).** Total grid load (`410`), residual load (`4359`) and pumped-storage consumption (`4387`). **forecast (Prognose).** Forecasted generation, e.g. Wind Offshore (`3791`), Wind Onshore (`123`), Photovoltaik (`125`), combined Wind & PV (`5097`) and total (`122`). **price (Großhandelspreis).** Day-ahead wholesale market prices for Germany/ Luxembourg (`4169`) and neighbouring bidding zones (e.g. Austria `4170`, France `254`, Netherlands `256`, Switzerland `259`). Since 1 October 2025 the day-ahead market sets a price per quarter-hour, and the `hour` series holds the mean of the four quarter-hour prices (before that, the `quarterhour` series repeats the hourly price). The next day's prices are published after the midday auction, so from the afternoon on the newest window already contains tomorrow's values. --- ## Regions in detail **DE / AT / LU.** Germany, Austria and Luxembourg. **DE-LU.** The German–Luxembourg **bidding zone**, the price area used for most current wholesale-price series. **DE-AT-LU.** The former combined Germany–Austria–Luxembourg bidding zone (split in 2018), used for historical data. **TSO control areas (Regelzonen).** `50Hertz`, `Amprion`, `TenneT` and `TransnetBW` are the four German transmission-system-operator control areas. **APG / Creos.** The Austrian (Austrian Power Grid) and Luxembourg (Creos) TSOs. --- ## Resolutions **hour / quarterhour / day / week / month / year.** The supported aggregation intervals for a series. `quarterhour` (15-minute) is also the granularity of the richer `table_data` response. --- ## Data shapes **index (`TimestampIndex`).** The response of an `index_{resolution}.json` request: `{ timestamps: number[] }` — the epoch-millisecond start of each available data window. Surfaced by `client.timestamps()` / `smard timestamps`. **series (`SeriesResult`).** The response of a `chart_data` request: `{ meta_data, series }` where `series` is an array of `SeriesPoint`s. Returned by `client.series()` / `client.latest()`. **SeriesPoint.** A single `[timestampMs, value]` tuple. The second element is `null` for a **gap** (no data for that point). **SeriesMetaData (`meta_data`).** `{ version, created }` — the data version and its creation time accompanying a series/table response. **table_data (`TableResult`).** A richer quarter-hour response (`smard table`). Its `series` is an array of `TableSeriesEntry` objects, each nesting the actual points under a `values` array of `TablePoint`s. **TablePoint.** `{ timestamp, versions }` — one quarter-hour point carrying multiple versioned values. **TableVersion.** One versioned value of a table point: `{ value, name }`. Note that `name` identifies the **data version** and is a *number* at runtime, not a label string. Either field may be `null`. --- ## Units & semantics **MWh — megawatt-hour.** The unit for generation and consumption series (energy per window). Note: values are unitless numbers in the JSON; the unit is implied by the chosen filter. **EUR/MWh — euro per megawatt-hour.** The unit for the wholesale-price filters (the `price` group). **Residual load (Residuallast).** Total grid load minus generation from fluctuating renewables (wind + solar) — the load that must be met by other sources. Filter `4359`. **Total grid load (Gesamtstromverbrauch).** Overall electricity consumption in a region. Filter `410`. **Window / data file.** The fixed time span covered by one `*_{timestamp}.json` data file (e.g. one week of hourly values). To read the newest data you fetch the index, take the last timestamp, then fetch that file — what `latest` does in one call. --- ## Commands & methods **timestamps.** `smard timestamps ` / `client.timestamps(...)` — list a series' available window timestamps. **series.** `smard series ` / `client.series(...)` — fetch one window's data. **latest.** `smard latest ` / `client.latest(...)` — convenience that reads the index, picks the newest timestamp and fetches that window in one call. **table.** `smard table ` / `client.tableData(...)` — quarter-hour `table_data` for one window. Its valid timestamps are a **different set** from those returned by `timestamps` (which lists `chart_data` windows); there is no discovery endpoint for `table_data` timestamps, so a `table` call may `404` for a timestamp valid for `series`. **filters / regions / resolutions.** Catalogue commands that print the documented filter ids (optionally one `--group`), the valid region codes and the valid resolution values — served locally from the bundled enums, no network call. --- > **Library & internals.** Terms for the TypeScript client and its internals — > `SmardClient`, the request engine, transport, retry/backoff, error types, > `FILTERS`/`RegionValues`/`ResolutionValues`, and the validation boundary — > now live in **[DEVELOPING.md](DEVELOPING.md)**.