Grundlagen

Antworten, Formate und CSV

Wie Antworten aufgebaut sind, wie Zahlen und Daten codiert sind und wie du Listen als CSV in Excel oder deine Datenbank bekommst.

JSON

Alle Antworten kommen als JSON in UTF-8 mit dem Header Content-Type: application/json; charset=utf-8. Feldnamen sind deutsch, kleingeschrieben und mit Unterstrich, zum Beispiel mindestlohn_brutto_stunde. REST-API, SDK, CLI mit --format json und MCP (im Feld structuredContent) liefern dieselben Felder in derselben Form.

Ein Beispiel, die Feiertage in Hessen 2027 (die Liste ist hier auf zwei Einträge gekürzt):

Antwort, gekürzt

{
  "datensatz": "feiertage",
  "jahr": 2027,
  "land": "HE",
  "land_name": "Hessen",
  "anzahl": 10,
  "anzahl_landesweit_montag_bis_freitag": 6,
  "feiertage": [
    {
      "datum": "2027-01-01",
      "id": "neujahr",
      "name": "Neujahr",
      "wochentag": "Freitag",
      "regional": false,
      "regional_hinweis": null,
      "sonntag": false
    },
    {
      "datum": "2027-03-26",
      "id": "karfreitag",
      "name": "Karfreitag",
      "wochentag": "Freitag",
      "regional": false,
      "regional_hinweis": null,
      "sonntag": false
    }
  ],
  "rechtsgrundlage": "Hessisches Feiertagsgesetz (HFeiertagsG)",
  "quelle": {
    "titel": "Hessisches Feiertagsgesetz (HFeiertagsG), Hessen",
    "url": "https://www.rv.hessenrecht.hessen.de/bshe/document/jlr-FeiertGHE1952pP1"
  },
  "quellen": [
    {
      "titel": "Hessisches Feiertagsgesetz (HFeiertagsG), Hessen",
      "url": "https://www.rv.hessenrecht.hessen.de/bshe/document/jlr-FeiertGHE1952pP1"
    }
  ],
  "hinweise": [
    "Regionale Feiertage gelten nur in Teilen des Landes und sind mit regional: true gekennzeichnet.",
    "sonntag: true steht für gesetzliche Feiertage, die immer auf einen Sonntag fallen. Das ist für Zuschläge nach § 3b EStG wichtig.",
    "Einmalige Feiertage sind enthalten, soweit sie bis zum Datenstand beschlossen sind. Neue Beschlüsse trägt der wöchentliche Prüflauf nach."
  ],
  "stand": "2026-09-23",
  "lizenz": "Berechnung nach den genannten Normen. Nutzung nach den Nutzungsbedingungen von Quellenkontor.",
  "zitat": "Gesetzliche Feiertage 2027 in Hessen: 10, davon 6 landesweit von Montag bis Freitag. Landesweit: Neujahr Fr 01.01., Karfreitag Fr 26.03., Ostermontag Mo 29.03., Tag der Arbeit Sa 01.05., Christi Himmelfahrt Do 06.05., Pfingstmontag Mo 17.05., Fronleichnam Do 27.05., Tag der Deutschen Einheit So 03.10., 1. Weihnachtstag Sa 25.12., 2. Weihnachtstag So 26.12.. Regionale Feiertage stehen in der Antwort. Rechtsgrundlage: Hessisches Feiertagsgesetz (HFeiertagsG). Quelle: Hessisches Feiertagsgesetz (HFeiertagsG), Hessen, https://www.rv.hessenrecht.hessen.de/bshe/document/jlr-FeiertGHE1952pP1. Daten: Quellenkontor (quellenkontor.dev).",
  "datenstand": "2026-09-23.1"
}

Zahlen, Beträge und Daten

Art	Darstellung	Beispiel
Geldbeträge	Zahl in Euro mit Punkt als Dezimaltrenner, ohne Währungszeichen	`13.9`
Prozentsätze	Zahl in Prozent, nicht als Anteil	`14.6` steht für 14,6 Prozent
Daten	Zeichenkette im Format JJJJ-MM-TT	`2027-01-01`
Wahrheitswerte	true oder false	`true`
Kein Wert	null, wenn ein Feld für diesen Fall nicht zutrifft oder offen ist	`null`
Listen	JSON-Array, auch wenn es nur einen Eintrag hat	`[]`

Rechne mit Geldbeträgen in deiner Software am besten in Cent oder mit Dezimaltypen, nicht mit Gleitkommazahlen. Die API liefert Beträge genau so, wie sie in der Rechtsquelle stehen.

Einheiten der Bestandteile

Datensätze aus Bestandteilen, etwa Minijob-Abgaben oder steuerfreie Beträge, nennen je Wert das Feld einheit:

einheit	Bedeutung
`euro`	Euro
`euro_stunde`	Euro je Stunde
`euro_tag`	Euro je Tag
`euro_monat`	Euro im Monat
`euro_jahr`	Euro im Jahr
`euro_km`	Euro je Kilometer
`euro_uebernachtung`	Euro je Übernachtung
`prozent`	Prozent
`prozent_listenpreis`	Prozent des Bruttolistenpreises
`tage`	Tage
`anzahl`	reine Anzahl ohne Einheit
`fahrten`	Fahrten
`arbeitsplaetze`	Arbeitsplätze
`km`	Kilometer

Felder in jeder Antwort

Feld	Bedeutung
`datensatz`	Kennung des Datensatzes, zum Beispiel mindestlohn
`rechtsgrundlage`	Norm, auf der Wert oder Berechnung beruht
`hinweise`	Liste mit Einschränkungen und Annahmen, die du deinen Nutzern zeigen solltest
`datenstand`	Datum und laufende Nummer der letzten Änderung im Änderungsprotokoll, die diesen Datensatz betrifft, zum Beispiel 2026-09-24.14

Tabellen-Datensätze liefern zusätzlich gueltig_ab, gueltig_bis, quelle und stand, siehe Gültigkeit in der Antwort. Alle Felder jedes Datensatzes stehen in der Referenz.

datenstand ist für Prüfer gedacht: Zwei Antworten mit demselben Datenstand beruhen auf demselben geprüften Bestand, unabhängig davon, wann du sie abgerufen hast. Die id führt direkt zum Eintrag im Änderungsprotokoll. Denselben Wert trägt auch der Header X-Datenstand und, bei CSV, nur dieser Header (CSV hat kein Feld dafür).

CSV

Listen gibt es mit format=csv auch als CSV-Datei: jeden Verlauf, die Feiertage, die Feiertage an Arbeitstagen beim Arbeitstage-Rechner und die Bestandteile der Beitragssätze. Für einzelne Werte gibt es kein CSV, die API antwortet dann mit ungueltiger_parameter.

Aufbau nach RFC 4180: erste Zeile mit Spaltennamen, Zeilenende CRLF, Felder mit Trennzeichen oder Anführungszeichen in Anführungszeichen.
UTF-8 mit BOM, damit Excel Umlaute richtig anzeigt.
Verschachtelte Felder werden zu eigenen Spalten: aus quelle.titel wird quelle_titel.
Der Dateiname kommt im Header Content-Disposition, zum Beispiel feiertage.csv.

Terminal

curl "https://api.quellenkontor.dev/v1/hr/feiertage?jahr=2027&land=HE&format=csv" \
  -H "Authorization: Bearer $QK_KEY" -o feiertage-2027-he.csv

feiertage-2027-he.csv, erste Zeilen

datum,id,name,wochentag,regional,regional_hinweis,sonntag
2027-01-01,neujahr,Neujahr,Freitag,false,,false
2027-03-26,karfreitag,Karfreitag,Freitag,false,,false
2027-03-29,ostermontag,Ostermontag,Montag,false,,false

CSV in Excel

Ein Excel mit deutschen Einstellungen erwartet Semikolons als Trennzeichen und Kommas in Dezimalzahlen. Mit trennzeichen=semikolon bekommst du genau das, und die Datei öffnet sich per Doppelklick richtig:

Terminal

curl "https://api.quellenkontor.dev/v1/hr/mindestlohn/verlauf?format=csv&trennzeichen=semikolon" \
  -H "Authorization: Bearer $QK_KEY" -o mindestlohn.csv

mindestlohn.csv, letzte Zeilen

gueltig_ab;mindestlohn_brutto_stunde;minijob_grenze_monat;rechtsgrundlage;quelle_url
2025-01-01;12,82;556;Vierte Mindestlohnanpassungsverordnung vom 24. November 2023 (BGBl. 2023 I Nr. 321), Stufe 2;https://www.recht.bund.de/bgbl/1/2023/321/VO.html
2026-01-01;13,9;603;Fünfte Mindestlohnanpassungsverordnung vom 5. November 2025 (BGBl. 2025 I Nr. 268), Stufe 1;https://www.recht.bund.de/bgbl/1/2025/268/VO.html
2027-01-01;14,6;633;Fünfte Mindestlohnanpassungsverordnung vom 5. November 2025 (BGBl. 2025 I Nr. 268), Stufe 2;https://www.recht.bund.de/bgbl/1/2025/268/VO.html

Google Sheets kann mit IMPORTDATA keinen Header mitschicken und damit keinen Schlüssel. Lade die CSV-Datei herunter und importiere sie, oder nutze Apps Script mit UrlFetchApp und dem Header Authorization.

Header der Antwort

Header	Inhalt
`Content-Type`	application/json oder text/csv, jeweils mit charset=utf-8
`X-Kontingent-Limit`	Abfragen im Monat laut Tarif, bei jeder Antwort mit Schlüssel
`X-Kontingent-Verbraucht`	Verbrauchte Abfragen im laufenden Monat, einschließlich dieser
`X-Datenstand`	derselbe Wert wie das Feld datenstand, auch bei CSV
`Cache-Control`	bei Datensatz-Antworten `private, max-age=…, must-revalidate` bis zur nächsten Mitternacht deutscher Zeit, siehe Abfragen sparen; sonst `no-store`
`ETag`	aus Datenstand und Anfrage, für If-None-Match, siehe Abfragen sparen
`Access-Control-Allow-Origin`	*, Aufrufe aus dem Browser sind technisch möglich, siehe REST-API
`WWW-Authenticate`	nur bei Status 401

Komplettexport und Offline-Daten

GET https://api.quellenkontor.dev/v1/export liefert den gesamten Tabellenbestand auf einmal: für jeden Datensatz mit Verlauf (15 von 23) den vollständigen Verlauf als JSON, dazu einen Link auf die CSV-Datei des Datensatzes. Praktisch für einen ersten Import in eine eigene Datenbank oder ein Backup. Reine Rechner ohne Tabelle, etwa Kündigungsfrist oder Dienstwagen, gehören nicht dazu, sie haben keinen Verlauf zum Exportieren.

Der Export braucht einen Schlüssel und zählt als eine einzelne Abfrage, unabhängig davon, wie viele Datensätze er enthält.

Terminal

curl "https://api.quellenkontor.dev/v1/export" \
  -H "Authorization: Bearer $QK_KEY" -o quellenkontor-export.json

Aufbau, gekürzt

{
  "datenstand": "2026-09-24.16",
  "erzeugt_am": "2026-09-24T18:00:00.000Z",
  "datensaetze": [
    {
      "id": "mindestlohn",
      "name": "Mindestlohn und Minijob-Grenze",
      "anzahl": 7,
      "csv_url": "https://api.quellenkontor.dev/v1/hr/mindestlohn/verlauf?format=csv",
      "verlauf": [
        "…"
      ]
    },
    "…"
  ]
}

Offline-Stand in JavaScript- und Python-SDK

Beide SDKs bringen denselben Verlauf, den auch /export liefert, fest im Paket mit. Ist die API nach allen Wiederholungen nicht erreichbar, rechnet das SDK die passende Stufe für den angefragten Stichtag selbst aus dem mitgelieferten Stand aus, statt einen Fehler zu werfen. Die Antwort trägt dann offline: true und den datenstand des Pakets, nicht den der gerade amtlichen Quelle, und es fehlen die berechneten Zusatzfelder wie zitat, vorheriger_wert oder naechster_wert. Reine Rechner ohne Verlauf bleiben ohne Verbindung ein Netzwerkfehler, für sie gibt es keinen Offline-Stand. Details und die Option zum Abschalten stehen unter SDK JavaScript und SDK Python.

Der Offline-Stand steckt im Quelltext des Pakets und wird beim Bauen einer neuen Paketversion aus dem aktuellen Bestand erzeugt. Zwischen zwei Paketversionen altert er wie jede lokale Kopie, deshalb der eigene Datenstand in der Antwort.

Fehlt etwas oder ist etwas unklar? Schreib uns, wir ergänzen die Doku.