Usage

mastr — a CLI for the Marktstammdatenregister (MaStR). No API key needed.

mastr [global options] <command> [command options]

Global options

Commands

Search options (the four data commands)

Each data command prints { total, data }: total is the full match count (respects the filter), data is the current page.

Filter syntax

FilterName~op~'value'~and~FilterName~op~'value'~…

• operators: eq (=), neq (≠), sw (starts-with), ct (contains), nct (not-contains), ew (ends-with), null (empty) and nn (not empty) — these two on text columns only: the register refuses them on number, dropdown and boolean columns, so the CLI rejects that (exit 2) — and for number/date columns gt (>) and lt (<). gt/lt are strict; there is no gte/lte. The register applies them to text and dropdown columns as well (checked live 2026-10-05: Ort~gt~'A' keeps a Münster unit, Ort~gt~'Z' drops it; on a dropdown they compare the code, Energieträger~gt~'2000') — the text comparison is the register’s own (its order for umlauts and case isn’t documented), so prefer eq/sw/ct there. An unknown or upper-case operator is rejected (exit 2) — the register would return 0 rows for it
• value: single-quoted; for a dropdown use its code (Value), not its label; decimals take a point ('4999.999') and no thousands separator ('5.000' means 5), dates work as '2025-01-01' or '01.01.2025' (a slash date is read day-first: '01/02/2025' is 1 February), booleans take '1'/'0'. A value the register can’t read (a decimal comma, an exponent, an invalid date, 'true') gets its error reply: exit 1, “the register rejected the request”. null/nn still need a value: Ort~null~'' (a bare Ort~null is ignored upstream and returns the unfiltered register, so the CLI rejects it). Every other operator needs a non-blank value: '' or ' ' is rejected (on a dropdown the register did not even answer). A value cannot contain ~: the register splits the whole filter on every ~ and has no escape or quoting for it (ct 'a~b' would silently become ct 'a'), so the CLI rejects it; search for a part of the text without the ~ instead. A single ' inside a value is fine (ct 'd'Arc'). Library users build specs from input with buildFilter()
• whitespace: next to a ~ it means nothing and is dropped — around a FilterName, an operator or and, and outside a quoted value ('Münster' ~and~…); inside the quotes it is kept
• checked before sending: every condition needs a FilterName, a known operator and a value, a value that opens a single quote must close it, conditions are joined by ~and~ only, and nothing may dangle at the end (…~and~). Anything else is a usage error (exit 2)
• checked against the category’s columns (one extra request for the column list): a FilterName the category doesn’t have, and for eq/neq a dropdown code its list doesn’t have (a label such as 'Wind' is named with its code), are a usage error (exit 2) — the register would ignore the name and return the unfiltered set, and answer an unknown code with 0 rows. A name is matched in Unicode NFC (a decomposed ä from macOS input counts as ä), without surrounding whitespace and in any case, and sent the register’s way
• conjunction: only and. There is no working or: the register keeps only the part before the first ~or~ and silently drops the rest (a wrong count, no error), so the CLI rejects ~or~ (exit 2). For an OR between codes of one dropdown column, list them comma-separated in one value: Energieträger~eq~'2497,2498'. The comma list works only for dropdown codes (Ort~eq~'Münster,Berlin' returns 0 rows); OR across different columns needs one query per condition
• discover the FilterNames and codes with mastr filters <category>

# Solar (Energieträger 2495) units in operation (Betriebs-Status 35)
mastr stromerzeugung --filter "Energieträger~eq~'2495'~and~Betriebs-Status~eq~'35'" --total

# Wind (2497) or solar (2495) units: a comma list inside one dropdown value
mastr stromerzeugung --filter "Energieträger~eq~'2497,2495'" --total

# Wind (2497) units above 5,000 kW gross
mastr stromerzeugung --filter "Energieträger~eq~'2497'~and~Bruttoleistung der Einheit~gt~'5000'" --total

The register ignores a FilterName it doesn’t know and returns the unfiltered result; the CLI refuses such a name before sending (with “did you mean”). --filter may be given several times; the conditions are joined with ~and~. Every other option given twice is a usage error (exit 2).

Examples

mastr stromerzeugung --total                        # 9562366 (2026-10-05)
mastr stromerzeugung --page-size 5 --iso-dates      # first 5 units, ISO dates
mastr filters stromerzeugung --compact | jq '.[] | {FilterName, Type}'
mastr gasverbrauch --sort "MaximaleGasbezugsLeistung-desc" --page-size 10 --compact | jq '.data'

Exit codes

Notes

• A wrong --sort field is refused by the register. On 2026-10-09 the register answered an unknown sort key (Bogus-desc, or the FilterName Bruttoleistung der Einheit-desc) with {"Error":true}: exit 1, and an ERROR record of mastr.api (“… the register rejected the request. It answers so to a sort key it doesn’t know …”). It used to answer with zero rows (total: 0), which reads like “no matches”; if a query returns 0 only after you add --sort, check the column key — the CLI logs a note (an INFO record of mastr.api) to stderr in this case. Sort keys are the record’s field names (Bruttoleistung, InbetriebnahmeDatum), not the FilterNames from mastr filters; list them with mastr stromerzeugung --page-size 1 --compact | jq '.data[0] | keys'. (Contrast --filter, where a wrong field or operator is rejected before sending; a filter that still gives 0 rows gets a stderr note, an INFO record, about its values.)
• Dates are Microsoft /Date(ms)/ strings; --iso-dates converts them, or use the library’s parseMsDate() (a Date) and formatMastrDate() (the --iso-dates text). Date-only fields (InbetriebnahmeDatum, EinheitRegistrierungsdatum, …) arrive as UTC midnight and print as YYYY-MM-DD; timestamps (DatumLetzteAktualisierung) print in German time with their offset (+01:00 winter, +02:00 summer) — the same instant as the UTC value, so the calendar day is the German one. A timestamp that happens to fall on UTC midnight exactly prints as a date.
• You cannot sum capacity server-side — there is no aggregate endpoint. Use --total for counts; sum the capacity field client-side only for small result sets.

Capacity fields per category

The rows differ per category; Bruttoleistung/Nettonennleistung exist only in stromerzeugung (sorting another category by them returns 0 rows).

The matching filters are Bruttoleistung der Einheit (stromerzeugung), Gaserzeugungsleistung and Maximale Gasbezugsleistung — check the exact names with mastr filters <category>.

• The data is © the Bundesnetzagentur under DL-DE-BY-2.0 — see DATA_LICENSE.md; attribution is required.