smard-cli

Website: English · Deutsch — command reference, guides and API docs

Query Germany's open electricity-market data from your terminal. smard is a command-line tool over the SMARD chart-data API (smard.de), operated by the Bundesnetzagentur — fetch generation, consumption, residual load and wholesale prices as clean JSON you can pipe straight into jq.

• Works out of the box — no account, no API key, no configuration. Install and query.
• Clean JSON output — pretty-printed by default, --compact for one-line/scripting.
• Seven commands — discover filters/regions, fetch the newest window in one call, or navigate timestamps manually.
• No credentials to manage — the SMARD API is fully open; this tool only reads.

Want to use this as a TypeScript library or understand how it's built? See DEVELOPING.md.

Install

npm i -g @maschinenlesbar.org/smard-cli

This installs the smard command. Requires Node.js 20+.

Check it works:

smard --help

Quickstart

No setup needed — the API requires no key. Your first query:

smard latest 410 DE week

That fetches the newest week file of total grid load for Germany: one value per week for the current year (52 weekly totals, the weeks still to come as null). An hour or quarterhour file covers one week; a day, week or month file covers a year. The result is a JSON object: time-series values live under series, metadata under meta_data. Pull out just the series with jq:

smard latest 410 DE week | jq '.series'

Show just the most recent data point (the window runs to the end of its period, so .series[-1] is usually [ts, null] — skip the nulls):

smard --compact latest 410 DE week | jq -c '[.series[] | select(.[1] != null)][-1]'

Commands

timestamps  <filter> <region> <resolution>              available window timestamps
series      <filter> <region> <resolution> <timestamp>  one window's data
latest      <filter> <region> <resolution>              newest window's data (one call)
table       <filter> <region> <timestamp>               quarter-hour table_data
filters     [--group generation|consumption|price|forecast]   filter catalogue
regions                                                  valid region codes
resolutions                                              valid resolution values

Positional arguments

| Argument | What it means | | --- | --- | | <filter> | Numeric series id — e.g. 410 (total grid load), 4068 (photovoltaics), 4169 (DE-LU wholesale price). Use smard filters to browse all documented ids. | | <region> | Grid or bidding-zone code — e.g. DE, DE-LU, TenneT. Use smard regions for the full list. | | <resolution> | Temporal granularity: hour, quarterhour, day, week, month, or year. Use smard resolutions to confirm. | | <timestamp> | Epoch-millisecond window start from smard timestamps. |

filters option

| Flag | Meaning | | --- | --- | | --group <group> | Only show one group: generation, consumption, price, or forecast |

Note on table: table reads the separate table_data endpoint, which has no index of its own. SMARD seems to have stopped publishing it: in a check on 2026-09-26, windows from 2021 to October 2023 answered (with the same weekly window starts that timestamps lists), but every window from December 2024 on — including the newest — returned 404, for DE and DE-LU alike. The cut-off lies between October 2023 and December 2024. So a 404 from table for a recent window is the normal case, not a wrong timestamp; for current data use series/latest.

Common tasks

A few recipes to get going — see Usage.md for the full, use-case-driven set.

# What filter ids exist? Show just the consumption group
smard filters --group consumption

# Total grid load for Germany, one value per week of the current year
smard latest 410 DE week

# Newest hourly wholesale price for the DE-LU bidding zone (EUR/MWh)
smard latest 4169 DE-LU hour

# Newest photovoltaic generation, compact output
smard --compact latest 4068 DE hour

# Latest wind onshore and wind offshore generation
smard latest 4067 DE hour    # Wind Onshore
smard latest 1225 DE hour    # Wind Offshore

# Pick a specific window explicitly (any timestamp from the list; old windows stay available)
TS=$(smard --compact timestamps 4169 DE-LU hour | jq '.[-1]')
smard series 4169 DE-LU hour "$TS"

Output & scripting

Every command prints pretty JSON to stdout. Errors go to stderr, so piping stdout into jq stays clean.

# Count data points in a series window
smard --compact latest 4068 DE hour | jq '.series | length'

# Sum all non-null values in a window (total MWh)
smard --compact latest 4068 DE hour | jq '[.series[][1] | select(. != null)] | add'

# Save a window to a file
smard --compact latest 410 DE day > load.json

Use --compact for single-line JSON in pipelines and logs:

smard --compact latest 410 DE week | jq -c '.series[-3:]'

--compact (and every global option) works before or after the command — both smard --compact latest … and smard latest … --compact do the same thing.

Exit codes make the CLI easy to use in scripts:

| Code | Meaning | | --- | --- | | 0 | success (also --help / --version) | | 4 | resource not found (404) — a timestamp that is not a window start, or a filter/region/resolution combination without data | | 1 | any other error: network failure, timeout, parse error, non-404 API status | | non-zero | usage / invalid argument (bad region, non-integer filter, etc.) |

Troubleshooting

• command not found: smard — the global npm bin directory isn't on your PATH. Run npm bin -g to find it and add it, or run via npx @maschinenlesbar.org/smard-cli ….
• Exit 4 / "not found" — the timestamp is not a window start, or the filter/region/resolution combination has no data (SMARD answers both with a 404; it never returns an empty list). Take a timestamp from smard timestamps <filter> <region> <resolution> — old windows stay available, so a timestamp from that list keeps working — and check the combination with smard regions and smard filters. For table, see the table_data note above.
• Exit 1 / network error — connectivity, DNS, or a timeout. Try again, or raise the limit with --timeout 60000.
• Exit 1 with "Unexpected response shape" — the index was not {"timestamps": [...]} (an error page from a proxy, or a changed format), so the CLI refuses to read it as "no data". latest also exits 1 if an index lists no windows at all.

Global options

These apply to every command and may be given before or after it:

| Option | Description | | --- | --- | | -V, --version | Print the version number | | -h, --help | Show help for the program or a command | | --compact | Print JSON on a single line instead of pretty-printed | | --base-url <url> | API base URL (default https://www.smard.de; an http:/https: URL, optionally with a path prefix; a query ?, fragment # or surrounding whitespace is a usage error). Userinfo (https://user:pw@mirror) is sent as Basic auth and shown as *** in error messages | | --timeout <ms> | Time limit per request in ms, reading the whole response included (0 = no timeout; default 30000; at most 2147483647) | | --user-agent <ua> | User-Agent header value (non-blank; no control characters or characters above U+00FF — a usage error before any request) | | --max-retries <n> | Retries for transient 429/503 responses (0–10, default 2). Each retry waits the server's Retry-After (up to 30 s; a longer one is not retried) or else backs off linearly | | --max-response-bytes <n> | Cap response body size in bytes (0 = unlimited; default 100 MiB) |

Learn more

• SKILLS.md — Claude Code Agent Skills that drive this CLI for energy-mix, price-watch and time-series-export tasks.
• Usage.md — full use-case-driven cookbook.
• GLOSSARY.md — every domain term, filter group, region code, and data shape explained.
• DEVELOPING.md — TypeScript library usage, architecture, testing, CI.

Data license

This CLI is a client — it accesses data it does not own or redistribute. The upstream data is © its provider and licensed separately from this tool's code. See DATA_LICENSE.md.

Bundesnetzagentur — CC BY 4.0. Attribution required, exact source string Bundesnetzagentur | SMARD.de; commercial use and modification allowed.

License

Dual-licensed — use it under either:

• AGPL-3.0-or-later (default, free). Note the AGPL's §13 network clause: if you run a modified version as a network service, you must offer that modified source to the service's users.
• Commercial license (paid), for closed-source / proprietary or SaaS use without the AGPL's obligations.

See LICENSING.md for details, and CONTRIBUTING.md for the contribution policy (this project does not accept external code contributions). Commercial enquiries: [email protected].