SDK for Python

The package quellenkontor runs on Python 3.9 and later and only uses the standard library. So there are no dependencies that could conflict with your project.

pip install quellenkontor

uv add quellenkontor
poetry add quellenkontor

from quellenkontor import Quellenkontor

# reads the key from QK_KEY
qk = Quellenkontor()

# or explicitly, with options
qk = Quellenkontor(api_key="qk_live_…", timeout=10.0, wiederholungen=3)

Cache and ETag

Within cache_ttl seconds, a repeated request with the same parameters comes back from this instance's cache without any network call. After that, the SDK asks again with the stored ETag in the If-None-Match header: if the value has not changed, the API responds with 304, the SDK returns the cached response, and the request does not count against your quota. More on saving requests under Quotas and limits.

qk = Quellenkontor(cache=False)  # always a fresh request

# or clear the cache on purpose, for example after a webhook
qk2 = Quellenkontor()
qk2.cache_leeren()

Offline data

If the API is unreachable after every retry, the SDK falls back to bundled offline data: the history of every table with a history, generated into the package from the current data set (the same data as /export). That response then carries offline: True and the package's own datenstand instead of the currently official one, without the computed extra fields such as zitat. Plain calculators without a table, for example notice period, vacation entitlement or company car, have no offline data and stay a QuellenkontorFehler with code netzwerk without a connection.

qk = Quellenkontor(offline=False)  # always throw the network error instead

# with the offline fallback (default): recognizable by the offline field
qk_mit_fallback = Quellenkontor()
ml = qk_mit_fallback.hr.mindestlohn(datum="2027-01-15")
if ml.get("offline"):
    print("Offline data from", ml["datenstand"])

Every dataset is a method under qk.hr. It returns a dict with the same fields as the API. You can leave out optional parameters or pass None.

Pass booleans as True or False; the SDK writes them for the API as true and false.

Notice period (Kündigungsfrist)

frist = qk.hr.kuendigungsfrist(eintritt="2017-03-01", zugang="2026-11-10")
print(frist["ende"])  # 2027-02-28

Vacation entitlement for part-time work

urlaub = qk.hr.urlaubsanspruch(arbeitstage_pro_woche=3, jahr=2027)
print(urlaub["anspruch_tage_jahr"])

Contribution rates on an effective date

saetze = qk.hr.beitragssaetze(datum="2026-07-01")
for b in saetze["bestandteile"]:
    print(b["name"], b["satz_prozent"])

If the API responds with an error, the SDK raises QuellenkontorFehler, with the attributes status, code and parameter. Without a connection, the status is 0 and the code is netzwerk.

from quellenkontor import Quellenkontor, QuellenkontorFehler

try:
    r = qk.hr.rechengroessen(jahr=2030)
except QuellenkontorFehler as e:
    if e.code == "kein_wert":
        print("Not promulgated yet:", e)
    elif e.status == 429:
        print("Quota used up")
    else:
        raise

With format="csv", anfrage returns the CSV text. The SDK removes the byte order mark, so you can read the text directly:

import io
import pandas as pd

csv = qk.anfrage("/hr/mindestlohn/verlauf", {}, format="csv")
df = pd.read_csv(io.StringIO(csv), parse_dates=["gueltig_ab"])
print(df[["gueltig_ab", "mindestlohn_brutto_stunde"]].tail())