marktstammdatenregister-cli

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

A dependency-light TypeScript client + CLI for the Marktstammdatenregister (MaStR) — the Bundesnetzagentur's register of the German electricity & gas market: ~9 million generation and consumption units (solar, wind, storage, CHP, …). Wraps the public "erweiterte öffentliche Einheitensuche". A bund.dev API.

• No API key. The public search is open.
• Zero runtime HTTP dependencies. Built on node:http/https; the CLI's only runtime dependency is commander.
• Library + CLI. Use the typed MastrClient, or the mastr command.

We provide the tool, not the data. MaStR data is © the Bundesnetzagentur under DL-DE-BY-2.0 — free to use with attribution. See DATA_LICENSE.md.

Install

npm install -g @maschinenlesbar.org/marktstammdatenregister-cli   # the `mastr` command
# or as a library:
npm install @maschinenlesbar.org/marktstammdatenregister-cli

Requires Node.js 22.12+.

CLI

Four datasets, each paged and filterable. Prints { total, data } (or just the count with --total).

mastr stromerzeugung --total                       # how many electricity-generation units? → 9562366 (2026-10-05; it grows)
mastr stromerzeugung --filter "Energieträger~eq~'2495'" --total   # …how many are solar? → 6545851
mastr stromerzeugung --sort "Bruttoleistung-desc" --page-size 20 --iso-dates
mastr gaserzeugung --page 1 --page-size 50
mastr filters stromerzeugung                        # the filterable columns + dropdown codes

Categories: stromerzeugung, stromverbrauch, gaserzeugung, gasverbrauch.

Filtering uses the register's own syntax — FilterName~op~'value'~and~… (ops eq|neq|sw|ct|nct|ew|null|nn, plus the strict gt/lt — meant for numbers and dates, but the register applies them to text and dropdown columns too, comparing the text or the code); there is no working ~or~ (the register drops everything after it, so the CLI rejects it) — for several codes of one dropdown, list them in one value: Energieträger~eq~'2497,2498'. Discover the German field names and dropdown codes with mastr filters <category>. The register silently ignores a FilterName it doesn't know (you'd get the unfiltered set) and answers an unknown dropdown code with 0 rows, so the CLI checks every FilterName and every eq/neq dropdown code against the category's columns (one extra request) and rejects an unknown one (exit 2, with "did you mean"); a name typed with a decomposed umlaut, padding or in another case is sent the register's way. A value is sent as text: trimmed inside its quotes and in NFC (the register trims codes, not text: ' Münster ' matched nothing), and one with an invisible, control or half character is rejected. A malformed spec or an unknown operator (e.g. gte) is rejected too. Several --filter flags are joined with ~and~; any other option given twice is a usage error. --sort takes FieldKey-asc or FieldKey-desc (several joined by ~), sent trimmed; any other form (no direction, -down, a name with spaces) is a usage error before any request, since the register sorted it ascending or not at all without a word. A wrong --sort field name is refused by the register (live 2026-10-09: {"Error":true}, exit 1 with an ERROR record of mastr.api that names the sort key; it used to answer 0 rows, so sanity-check a sorted query with --total); sort keys are record field names (Bruttoleistung), not FilterNames — list them with mastr stromerzeugung --page-size 1 --compact | jq '.data[0] | keys'. Dates come as Microsoft /Date(ms)/ strings — add --iso-dates to convert them to ISO-8601: date-only fields (InbetriebnahmeDatum, …) as YYYY-MM-DD, timestamps (DatumLetzteAktualisierung) in German time with an explicit offset, 2020-02-20T17:28:35.250+01:00.

Global flags: --base-url, --timeout, --user-agent, --max-retries, --max-response-bytes, --log-format, --compact, --iso-dates. See Usage.md. A --base-url on plain http: to a host other than loopback logs one WARN record of mastr.http (… sent unencrypted …) on stderr before the first request (stdout and the exit code are unchanged); the library's check is cleartextProblem(baseUrl).

Each line on stderr is a log record: a timestamp (UTC), a level (ERROR, WARN, INFO) and a topic, the program and the area it comes from (mastr.cli for usage errors, mastr.api for the register's answers, a malformed one included, and the notes about them — also a WARN when characters of an answer that were not valid text (invalid bytes, a lone surrogate) were replaced with U+FFFD, so stdout stays well-formed JSON —, mastr.http for the connection, mastr.output for a failed write to stdout and an answer that can't be printed — nested too deeply or too large). By default it is written log4j style; --log-format jsonl writes one JSON object per line instead. A record is always one line: a line break, a control character or a bidi control in a message (a server's text, a value you typed) is written as an escape (\n, \u001b, \u202e), so it can neither split a record nor forge another one, nor steer the terminal; a message longer than 4000 characters is cut and ends in … (N more characters):

2026-10-09T14:03:12.481Z WARN  [mastr.http] requests to mirror.test are sent unencrypted (http:, not https:)
2026-10-09T14:03:12.902Z INFO  [mastr.api] 0 results with --filter set. If you expected matches, check the values: …

mastr --log-format jsonl stromerzeugung --filter "Ort~eq~'Nirgendwo'" --total 2>log.jsonl   # {"ts":"…","level":"INFO","topic":"mastr.api","msg":"0 results with --filter set. …"}

Library

import { MastrClient, parseMsDate } from "@maschinenlesbar.org/marktstammdatenregister-cli";

const mastr = new MastrClient();
const solar = await mastr.stromerzeugung({ filter: "Energieträger~eq~'2495'", pageSize: 10 });
solar.total; // total matching units
await mastr.count("stromerzeugung", { filter: "Energieträger~eq~'2495'" }); // just the count, one-row request
parseMsDate(String(solar.data[0]?.EinheitRegistrierungsdatum)); // Date | null

The client checks a filter's FilterNames and dropdown codes against the category's columns (filterColumns(), fetched once per client and category) and throws MastrValidationError for one the register would ignore; new MastrClient({ allowUnknownFilters: true }) skips that check and its request. A query key it doesn't know (filtr) is refused the same way.

Build filters from user input with buildFilter, not string interpolation: a filter value cannot contain ~ (the register splits on it and has no escape), so `Ort~eq~'${input}'` lets an input like Münster'~and~Energieträger~eq~'2497 add a condition. buildFilter quotes each value, sends a text value trimmed and in Unicode NFC (normalizeText), and throws MastrValidationError for a ~ or a blank value:

import { buildFilter } from "@maschinenlesbar.org/marktstammdatenregister-cli";

const filter = buildFilter([
  { name: "Ort", op: "eq", value: town },                        // quoted, ~ refused
  { name: "Energieträger", op: "eq", value: ["2497", "2498"] },  // comma list = any of
]);
await mastr.stromerzeugung({ filter, pageSize: 1 });

Documentation

• Usage.md — commands, filter syntax, exit codes
• DEVELOPING.md — architecture, testing, the live-API quirks
• GLOSSARY.md — MaStR domain terms
• DATA_LICENSE.md — the DL-DE-BY-2.0 data terms
• SKILLS.md — the Claude Code skills this repo ships

Licence

Code is dual-licensed AGPL-3.0-or-later OR commercial — see LICENSING.md. No external code contributions are accepted (see CONTRIBUTING.md); bug reports and AGPL forks are welcome.