Reference

Reference: Vacation entitlement

Statutory minimum vacation for part-time work and for joining or leaving during the year.

Calculates the statutory minimum vacation (Mindesturlaub) under the Federal Vacation Act (Bundesurlaubsgesetz, BUrlG) for any number of working days per week. With a start or end date, the calculator returns the partial vacation (Teilurlaub) under § 5 BUrlG, including rounding.

Endpoints and calls

Access	Call
REST API	`GET /hr/urlaubsanspruch`
SDK JavaScript	`qk.hr.urlaubsanspruch(…)`
SDK Python	`qk.hr.urlaubsanspruch(…)`
CLI	`qk urlaubsanspruch --arbeitstage-pro-woche 3`
MCP tool	`hr_urlaubsanspruch`

Parameters

Name	Type	Required	Default	Allowed	Description
`arbeitstage_pro_woche`	number	yes		0.5 to 6	Working days per week, 0.5 to 6
`jahr`	year	no	laufendes Jahr	2015 to 2035	Calendar year for the partial vacation calculation. Defaults to the year of leaving or joining.
`eintritt`	date (YYYY-MM-DD)	no			Start of employment (optional)
`austritt`	date (YYYY-MM-DD)	no			End of employment (optional)

The API rejects unknown parameters with unbekannter_parameter. In addition there are format and trennzeichen, see CSV.

Response fields

Field	Type	Meaning
`datensatz`	Text	Dataset id
`arbeitstage_pro_woche`	Decimal	Working days per week, as given
`anspruch_tage_jahr`	Decimal	Statutory yearly vacation in working days
`formel`	Text	The calculation in words or as a formula
`rechtsgrundlage`	Text	Law or ordinance
`hinweise`	List	Limits of the values or the calculation, in sentences
`quelle`	Object	Title and URL of the source the value is based on
`quellen`	List	All legal provisions the response is based on, with title and URL
`stand`	Date	Date of the last check against the source
`lizenz`	Text	Terms of use for the values
`zitat`	Text	Ready-made sentence for citing, with value, validity, legal basis and source
`datenstand`	Text	Id of the data snapshot: date and sequence number of the last changelog entry (/v1/aenderungen) affecting this dataset. The same datenstand means unchanged content, useful for auditors and for comparing two requests
`anspruch_tage_im_jahr`	Decimal	Entitlement in the year in question, rounded for partial vacation
`teilurlaub`	Boolean	Whether § 5 BUrlG applies
`volle_monate`	Integer	Full months for partial vacation

Example

Call with arbeitstage_pro_woche = 3. The response is generated by the same code that answers the API.

api.quellenkontor.dev/v1/hr/urlaubsanspruch?arbeitstage_pro_woche=3

Zur API-Doku →

curl "https://api.quellenkontor.dev/v1/hr/urlaubsanspruch?arbeitstage_pro_woche=3" \
  -H "Authorization: Bearer $QK_KEY"

import { Quellenkontor } from "@quellenkontor/sdk";

const qk = new Quellenkontor(process.env.QK_KEY);
const daten = await qk.hr.urlaubsanspruch({ arbeitstage_pro_woche: 3 });

import os
from quellenkontor import Quellenkontor

qk = Quellenkontor(api_key=os.environ["QK_KEY"])
daten = qk.hr.urlaubsanspruch(arbeitstage_pro_woche=3)

$ qk urlaubsanspruch --arbeitstage-pro-woche 3

{
  "name": "hr_urlaubsanspruch",
  "arguments": {
    "arbeitstage_pro_woche": 3
  }
}

This is how an agent calls the tool. Server setup is described in the MCP docs.

Antwort200 OK · JSON

{
  "datensatz": "urlaubsanspruch",
  "arbeitstage_pro_woche": 3,
  "anspruch_tage_jahr": 12,
  "formel": "24 Werktage × 3 ÷ 6 = 12 Arbeitstage",
  "rechtsgrundlage": "§ 3 BUrlG",
  "hinweise": [
    "Mindesturlaub nach dem Bundesurlaubsgesetz. Vertraglicher oder tariflicher Mehrurlaub ist nicht berücksichtigt.",
    "Jugendliche haben je nach Alter zu Beginn des Kalenderjahrs 30, 27 oder 25 Werktage (§ 19 JArbSchG), schwerbehinderte Menschen bei einer Fünf-Tage-Woche fünf Arbeitstage Zusatzurlaub (§ 208 SGB IX), Pflegekräfte Mehrurlaub nach der Pflegearbeitsbedingungenverordnung (Datensatz pflegemindestlohn)."
  ],
  "quelle": {
    "titel": "§ 3 BUrlG (Dauer des Urlaubs)",
    "url": "https://www.gesetze-im-internet.de/burlg/__3.html"
  },
  "quellen": [
    {
      "titel": "§ 3 BUrlG (Dauer des Urlaubs)",
      "url": "https://www.gesetze-im-internet.de/burlg/__3.html"
    },
    {
      "titel": "§ 4 BUrlG (Wartezeit)",
      "url": "https://www.gesetze-im-internet.de/burlg/__4.html"
    },
    {
      "titel": "§ 5 BUrlG (Teilurlaub)",
      "url": "https://www.gesetze-im-internet.de/burlg/__5.html"
    }
  ],
  "stand": "2026-09-23",
  "lizenz": "Berechnung nach den genannten Normen. Nutzung nach den Nutzungsbedingungen von Quellenkontor.",
  "zitat": "Mindesturlaub nach § 3 BUrlG bei 3 Arbeitstagen pro Woche: 12 Arbeitstage im Jahr. Ohne vertraglichen Mehrurlaub; für Jugendliche und schwerbehinderte Menschen gilt mehr. Rechtsgrundlage: § 3 BUrlG. Quelle: § 3 BUrlG (Dauer des Urlaubs), https://www.gesetze-im-internet.de/burlg/__3.html. Daten: Quellenkontor (quellenkontor.dev).",
  "datenstand": "2026-09-23.1"
}

Error cases

Status	Code	When
400	`parameter_fehlt`	if arbeitstage_pro_woche is missing
400	`ungueltiger_parameter`	wrong format or a value outside: arbeitstage_pro_woche (0.5 to 6); jahr (2015 to 2035)
400	`unbekannter_parameter`	a parameter this dataset does not have
404	`kein_wert`	outside the coverage (current law) or the value for this period has not been promulgated yet
401, 429	see errors	all error codes

Schema for MCP

This is how the MCP server describes the arguments of the tool hr_urlaubsanspruch:

inputSchema

{
  "type": "object",
  "properties": {
    "arbeitstage_pro_woche": {
      "description": "Arbeitstage pro Woche, 0,5 bis 6",
      "type": "number",
      "minimum": 0.5,
      "maximum": 6,
      "examples": [
        5
      ]
    },
    "jahr": {
      "description": "Kalenderjahr für die Teilurlaubsberechnung. Ohne Angabe das Jahr von Austritt oder Eintritt.",
      "type": "integer",
      "minimum": 2015,
      "maximum": 2035
    },
    "eintritt": {
      "description": "Beginn des Arbeitsverhältnisses (optional)",
      "type": "string",
      "format": "date",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "austritt": {
      "description": "Ende des Arbeitsverhältnisses (optional)",
      "type": "string",
      "format": "date",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    }
  },
  "required": [
    "arbeitstage_pro_woche"
  ],
  "additionalProperties": false
}

Source and freshness

Item	Content
Source	§§ 3 to 5 Federal Vacation Act (Bundesurlaubsgesetz)
License	Calculation under the cited provisions. Use under the Quellenkontor terms of use.
Updates	when the law changes
Coverage	Germany, current law
Last checked	September 23, 2026
Next expected change	only if the law changes

Overview with tables and questions about the dataset: Vacation entitlement calculator. Report an error through the contact form.

Something missing or unclear? Write to us and we will extend the docs.