API-Dokumentation

Jahresdaten

Jahresdaten für 1 Ort auslesen

mittels GeoID mittels City-ID mittels LatLon Geokoordinaten Schweiz / Liechtenstein: mittels Postleitzahl

Schweiz / Liechtenstein: mittels BFS-Nummer

API: Data/CityId

Holt Feiertage und Schulferien für ein ganzes Jahr, basierend auf einer `cityId`.

Funktion

Diese API ermittelt, an welchen Tagen im Jahr an einem bestimmten Ort ein offizieller Feiertag oder Schulferien stattfinden. Erforderliche Parameter sind `api_key` und `cityId`. Der Parameter `year` ist optional – falls er nicht angegeben wird, wird automatisch das aktuelle Jahr verwendet. Zusätzlich kann die Ausgabe über weitere Parameter konfiguriert werden. Die Parameter werden als Query-Parameter in der URL übergeben. Alternativ kann die Autorisierung auch im Header erfolgen.

Die verfügbaren City-IDs finden Sie im API: GeoTree/ISO

Interaktive Anleitung und OpenAPI

OpenAPI 3.0 (Swagger) – Interaktive API-Dokumentation

Öffnet die interaktive API-Dokumentation mit Swagger, in der Sie API-Endpunkte testen und erkunden können.

OpenAPI JSON-Spezifikation herunterladen

API-Kapitel

URL für Anfragen
Parameter für Anfragen
Beispiele (URL / PHP / Python / JavaScript)
Rückgabewerte des API
Beispiele (JSON / XML / CSV)
Fehlermeldungen

URL für Anfragen

Zum Abrufen der Daten verwenden Sie folgende URL. Achten Sie bitte auf Gross-Kleinschrift.

POST / GET

https://feiertagskalender.ch/api/Data/CityId/index.php

Parameter für Anfragen

Mit den folgenden Variablen können Sie die Abfrage vervollständigen und die API-Ergebnisse steuern.

Parameter	Erläuterung	Beispiele
api_key erforderlich	Ihr API-Schlüssel	api_key=abc-123-def-456
cityId erforderlich	City-ID des gewünschten Ortes. Es wird die City-ID von Feiertagskalender.ch verwendet.	cityid=88
year oder jahr	Jahr der gewünschten Daten ohne Angabe: laufendes Kalenderjahr (= Standard)	year= 2026
class oder klasse	Umfang der Daten Varianten: 0 = nur Schulferien 3 = 0 + gesetzlich anerkannte Feiertage 4 = 0 + 3 + gesetzliche und gesetzlich nicht anerkannte Feiertage (religiöse, kulturelle) (= Standard) 5 = 0 + 3 + 4 + Ereignistage (z.B. Valentinstag, Muttertag, Advent)	klasse=5
charset	Die gewünschte Codierung der Antwort Varianten: UTF-8 (= Standard) ISO-8859-1	charset=iso-8859-1
format	Das gewünschte Ausgabeformat Varianten: JSON (= Standard) XML CSV	format=xml
date_format	Das gewünschte Datumsformat für die Antwort. Standard:`Y-m-d` (z.B., 2025-12-31) Das Format entspricht der Datumsformatierung der PHP-Anweisung date() Varianten: Y-m-d = YYYY-MM-DD (ISO-8601) (= Standard) d.m.Y = DD.MM.YYYY Ymd = YYYYMMDD dmY = DDMMYYYY d.m.y = DD.MM.YY j.n.y = D.M.YY	date_format=d.m.Y
hl	Gewünschte Sprache der Ausgabe Varianten: de = Deutsch (= Standard) fr = Französisch it = Italienisch en = Englisch	hl=en

Beispiele (URL / PHP / Python / JavaScript)

Beispiele anzeigen

Parameter in der URL

So können Parameter in der URL mitgegeben werden (z.B. über den Browser, oder in Excel):
Hinweis: Der erste Parameter wird mit ? eingeleitet, alle weiteren Parameter werden mit & getrennt.

Wichtig: Dieser Code darf nicht direkt in einer Webseite verwendet werden! API-Schlüssel müssen aus Sicherheitsgründen nur im Backend verarbeitet werden.

https://feiertagskalender.ch/api/Data/CityId/index.php?api_key=YOUR_API_KEY&cityid=89&year=2022

Beispiel PHP mit cURL (GET)

$api_url = "https://feiertagskalender.ch/api/Data/CityId/index.php?cityid=89&year=2022";
$api_key = "YOUR_API_KEY";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $api_url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
   "Authorization: Bearer $api_key",
   "Content-Type: application/json"
]);
$response = curl_exec($ch);
curl_close($ch);

echo $response;

Beispiel PHP mit cURL (POST)

$api_url = "https://feiertagskalender.ch/api/Data/CityId/index.php";
$api_key = "YOUR_API_KEY";

// POST-Daten
$post_data = json_encode([
    "cityid": "89", "year": "2022"	
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $api_url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer $api_key",
    "Content-Type: application/json"
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Beispiel Python mit requests (GET)

import requests

api_key = "YOUR_API_KEY"
api_url = "https://feiertagskalender.ch/api/Data/CityId/index.php?cityid=89&year=2022"
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

response = requests.get(api_url, headers=headers)

if response.status_code == 200:
    print(response.json())  # JSON
else:
    print(f"Error: {response.status_code}", response.text)

Beispiel Python mit requests (POST)

import requests

api_key = "YOUR_API_KEY"
api_url = "https://feiertagskalender.ch/api/Data/CityId/index.php"
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

payload = {
    "cityid": "89", "year": "2022"	
}

response = requests.post(api_url, headers=headers, json=payload)

if response.status_code == 200:
    print(response.json())  # JSON
else:
    print(f"Error: {response.status_code}", response.text)

Beispiel JavaScript mit Fetch API (GET)

Die Fetch API ist eine moderne Methode, um HTTP-Anfragen in JavaScript durchzuführen. Sie wird in aktuellen Browsern unterstützt.

Wichtig: Dieser Code darf nicht direkt in einer Webseite verwendet werden! API-Schlüssel müssen aus Sicherheitsgründen nur im Backend verarbeitet werden.

const apiUrl = "https://feiertagskalender.ch/api/Data/CityId/index.php?cityid=89&year=2022";
const apiKey = "YOUR_API_KEY";  								
const headers = new Headers({
    "Authorization": "Bearer " + apiKey,
    "Content-Type": "application/json"
});

fetch(apiUrl, { method: "GET", headers })
    .then(response => {
        if (!response.ok) {
            throw new Error(`Error: ${response.status} ${response.statusText}`);
        }
        return response.json();
    })
    .then(data => console.log(data))
    .catch(error => console.error("Error:", error));

Beispiel JavaScript mit Fetch API (POST)

Die Fetch API ist eine moderne Methode, um HTTP-Anfragen in JavaScript durchzuführen. Sie wird in aktuellen Browsern unterstützt.

const apiUrl = "https://feiertagskalender.ch/api/Data/CityId/index.php";
const apiKey = "YOUR_API_KEY";  
const requestData = {
    "cityid": "89", "year": "2022"	
};

fetch(apiUrl, {
    method: "POST",
    headers: {
        "Authorization": "Bearer " + apiKey,
        "Content-Type": "application/json"
    },
    body: JSON.stringify(requestData)
})
.then(response => {
    if (!response.ok) {
        throw new Error(`Error: ${response.status} ${response.statusText}`);
    }
    return response.json();
})
.then(data => console.log(data))
.catch(error => console.error("Error:", error));

Rückgabewerte des API

Die Inhalte der API-Antworten ergeben sich aus:
- den von Ihnen abonnierten Daten (Länder, Feiertage, Schulferien, Kalenderjahre)
- den offiziell bekannten Daten der Gesetzgeber
- der Verfügbarkeit aufgrund unserer Recherchen (IST-Situation unserer Datenbank)

Beachten Sie bitte, dass die Ausgabe im CSV-Format abweicht.

Array				Erläuterung	Beispiel
interface				Version des API
source:	href			URL zur Datenquelle (Website)
	description			Bezeichnung der Datenquelle
copyright	href			URL zum Inhaber des Copyrights (Website)
	description			Bezeichnung des Copyright-Inhabers
apiName				Identifikation des API	Data/CityId
apiStatus	description			Bezeichnung des API-Status. Für Varianten, siehe unter Fehlermeldungen	active
date				Datum des Datenexports	01.05.2025
request:	cityId			City-ID gemäss Anfrage	88
	year			Jahr der Daten in der Ausgabe	2015
	class			Klasse der Abfrage (betrifft den Umfang der Daten)	4
	charset			Schriftcodierung der Ausgabe	utf-8
	format			Datenformat der Ausgabe	json
	date_format			Datumformat der Ausgabe	d.m.Y
	hl			Sprache der Ausgabe, gemäss Anfrage	de
results	status	description		Status der Ausgabe. Für Varianten, siehe unter Fehlermeldungen	ok
	location	description		Bezeichnung der geografischen Einheit	Berlin
		cityId		Geo-ID der geografischen Einheit.	88
		iso		ISO-Landeskürzel, 2-stellig	DE
		iso-3166-2		Regionencode nach ISO 3166-2	DE-BE
		note		Besondere Hinweise
		events		Die Kalenderevents
			description	Bezeichnung des Feiertags, oder der Schulferien	Neujahr
			id	Eindeutige ID des Events. Feiertage haben jedes Jahr dieselbe ID. Schulferien haben alle ihre eigenen IDs.	1
			dateStart	Datum Beginn des Events	01.01.2015
			dateEnd	Datum Ende des Events	01.01.2015
			class	Klasse des Events: 0 = Schulferien 1 = gesetzlich anerkannter Feiertag 2 = Den Sonntagen gleichgestellter Feiertag 3 = halber, gesetzlich anerkannter Feiertag (meist ab Mittag) 4 = gesetzlich nicht anerkannter Feiertag (Geschäfte, Schulen, Verwaltungen meist geschlossen), Bankenfeiertag; im Sinne des Europäischen Übereinkommens über die Berechnung der Fristen wird dieser Tag wie ein gesetzlicher Feiertag behandelt (Art. 5). 5 = Ereignistag # = nur teilweise gültig	2
			percent	Umfang der betroffenen Einwohner / Schulklassen in Prozent	100
			prov	Flag für provisorisch festgelegte Daten 0 = definitiv 1 = provisorisch	0
			note	besondere hinweise

Beispiele (JSON / XML / CSV)

JSON

URL:
https://www.feiertagskalender.ch/api/Data/CityId/index.php?api_key=YOUR_API_KEY&cityid=89&year=2022

Antwort des APIs:

{
    "interface": "fcal API 2.02",
    "source": {
        "href": "https://feiertagskalender.ch",
        "description": "feiertagskalender.ch"
    },
    "copyright": {
        "href": "https://psc.ch",
        "description": "psc Peter Schuetz Informatik-Dienstleistungen, CH Arch"
    },
    "apiName": "Data/CityId",
    "apiStatus": {
        "description": "active"
    },
    "date": "2025-02-26",
    "request": {
        "cityId": "89",
        "year": 2022,
        "class": "4",
        "charset": "utf-8",
        "format": "json",
        "date_format": "Y-m-d",
        "hl": "de"
    },
    "results": {
        "status": {
            "description": "ok"
        },
        "location": {
            "description": "Zurich",
            "cityId": "89",
            "iso": "CH",
            "iso-3166-2": "CH-ZH",
            "note": "",
            "events": [
                {
                    "description": "Neujahr",
                    "id": "1",
                    "dateStart": "2022-01-01",
                    "dateEnd": "2022-01-01",
                    "class": "2",
                    "percent": "100",
                    "prov": "0",
                    "note": null
                },
                {
                    "description": "Berchtoldstag",
                    "id": "3",
                    "dateStart": "2022-01-02",
                    "dateEnd": "2022-01-02",
                    "class": "4",
                    "percent": "100",
                    "prov": "0",
                    "note": null
                },
                {
                    "description": "Karfreitag",
                    "id": "17",
                    "dateStart": "2022-04-15",
                    "dateEnd": "2022-04-15",
                    "class": "2",
                    "percent": "100",
                    "prov": "0",
                    "note": null
                },
                {
                    "description": "Ostern",
                    "id": "18",
                    "dateStart": "2022-04-17",
                    "dateEnd": "2022-04-17",
                    "class": "4",
                    "percent": "100",
                    "prov": "0",
                    "note": null
                },
                {
                    "description": "Ostermontag",
                    "id": "19",
                    "dateStart": "2022-04-18",
                    "dateEnd": "2022-04-18",
                    "class": "2",
                    "percent": "100",
                    "prov": "0",
                    "note": null
                },
                {
                    "description": "Sechseläuten",
                    "id": "20",
                    "dateStart": "2022-04-25",
                    "dateEnd": "2022-04-25",
                    "class": "4",
                    "percent": "100",
                    "prov": "0",
                    "note": null
                },
                {
                    "description": "Tag der Arbeit",
                    "id": "22",
                    "dateStart": "2022-05-01",
                    "dateEnd": "2022-05-01",
                    "class": "2",
                    "percent": "100",
                    "prov": "0",
                    "note": null
                },
                {
                    "description": "Auffahrt",
                    "id": "31",
                    "dateStart": "2022-05-26",
                    "dateEnd": "2022-05-26",
                    "class": "2",
                    "percent": "100",
                    "prov": "0",
                    "note": null
                },
                {
                    "description": "Pfingsten",
                    "id": "30",
                    "dateStart": "2022-06-05",
                    "dateEnd": "2022-06-05",
                    "class": "4",
                    "percent": "100",
                    "prov": "0",
                    "note": null
                },
                {
                    "description": "Pfingstmontag",
                    "id": "35",
                    "dateStart": "2022-06-06",
                    "dateEnd": "2022-06-06",
                    "class": "2",
                    "percent": "100",
                    "prov": "0",
                    "note": null
                },
                {
                    "description": "Nationalfeiertag Schweiz",
                    "id": "12",
                    "dateStart": "2022-08-01",
                    "dateEnd": "2022-08-01",
                    "class": "2",
                    "percent": "100",
                    "prov": "0",
                    "note": null
                },
                {
                    "description": "Knabenschiessen",
                    "id": "60",
                    "dateStart": "2022-09-12",
                    "dateEnd": "2022-09-12",
                    "class": "4",
                    "percent": "100",
                    "prov": "0",
                    "note": null
                },
                {
                    "description": "Weihnachten",
                    "id": "23",
                    "dateStart": "2022-12-25",
                    "dateEnd": "2022-12-25",
                    "class": "2",
                    "percent": "100",
                    "prov": "0",
                    "note": null
                },
                {
                    "description": "Stephanstag",
                    "id": "37",
                    "dateStart": "2022-12-26",
                    "dateEnd": "2022-12-26",
                    "class": "2",
                    "percent": "100",
                    "prov": "0",
                    "note": null
                }
            ]
        }
    }
}

XML

URL:
https://www.feiertagskalender.ch/api/Data/CityId/index.php?api_key=YOUR_API_KEY&cityid=89&year=2022&format=xml

Antwort des APIs:

<fcal_api>
<interface>fcal API 2.02</interface>
<source>
<href>https://feiertagskalender.ch</href>
<description>feiertagskalender.ch</description>
</source>
<copyright>
<href>https://psc.ch</href>
<description>psc Peter Schuetz Informatik-Dienstleistungen, CH Bern</description>
</copyright>
<apiStatus>
<description>active</description>
</apiStatus>
<apiName>Data/CityId</apiName>
<date>2025-02-26</date>
<request>
<cityId>89</cityId>
<year>2022</year>
<class>4</class>
<charset>utf-8</charset>
<format>xml</format>
<date_format>Y-m-d</date_format>
<hl>de</hl>
</request>
<results>
<status>
<description>ok</description>
</status>
<location>
<description>Zurich,</description>
<cityId>89</cityId>
<iso>CH</iso>
<iso-3166-2>CH-ZH</iso-3166-2>
<note></note>
<events>
<event>
<description>Neujahr</description>
<id>1</id>
<dateStart>2022-01-01</dateStart>
<dateEnd>2022-01-01</dateEnd>
<class>2</class>
<percent>100</percent>
<prov>0</prov>
<note></note>
</event>
<event>
<description>Berchtoldstag</description>
<id>3</id>
<dateStart>2022-01-02</dateStart>
<dateEnd>2022-01-02</dateEnd>
<class>4</class>
<percent>100</percent>
<prov>0</prov>
<note></note>
</event>
<event>
<description>Karfreitag</description>
<id>17</id>
<dateStart>2022-04-15</dateStart>
<dateEnd>2022-04-15</dateEnd>
<class>2</class>
<percent>100</percent>
<prov>0</prov>
<note></note>
</event>
<event>
<description>Ostern</description>
<id>18</id>
<dateStart>2022-04-17</dateStart>
<dateEnd>2022-04-17</dateEnd>
<class>4</class>
<percent>100</percent>
<prov>0</prov>
<note></note>
</event>
<event>
<description>Ostermontag</description>
<id>19</id>
<dateStart>2022-04-18</dateStart>
<dateEnd>2022-04-18</dateEnd>
<class>2</class>
<percent>100</percent>
<prov>0</prov>
<note></note>
</event>
<event>
<description>Sechseläuten</description>
<id>20</id>
<dateStart>2022-04-25</dateStart>
<dateEnd>2022-04-25</dateEnd>
<class>4</class>
<percent>100</percent>
<prov>0</prov>
<note></note>
</event>
<event>
<description>Tag der Arbeit</description>
<id>22</id>
<dateStart>2022-05-01</dateStart>
<dateEnd>2022-05-01</dateEnd>
<class>2</class>
<percent>100</percent>
<prov>0</prov>
<note></note>
</event>
<event>
<description>Auffahrt</description>
<id>31</id>
<dateStart>2022-05-26</dateStart>
<dateEnd>2022-05-26</dateEnd>
<class>2</class>
<percent>100</percent>
<prov>0</prov>
<note></note>
</event>
<event>
<description>Pfingsten</description>
<id>30</id>
<dateStart>2022-06-05</dateStart>
<dateEnd>2022-06-05</dateEnd>
<class>4</class>
<percent>100</percent>
<prov>0</prov>
<note></note>
</event>
<event>
<description>Pfingstmontag</description>
<id>35</id>
<dateStart>2022-06-06</dateStart>
<dateEnd>2022-06-06</dateEnd>
<class>2</class>
<percent>100</percent>
<prov>0</prov>
<note></note>
</event>
<event>
<description>Nationalfeiertag Schweiz</description>
<id>12</id>
<dateStart>2022-08-01</dateStart>
<dateEnd>2022-08-01</dateEnd>
<class>2</class>
<percent>100</percent>
<prov>0</prov>
<note></note>
</event>
<event>
<description>Knabenschiessen</description>
<id>60</id>
<dateStart>2022-09-12</dateStart>
<dateEnd>2022-09-12</dateEnd>
<class>4</class>
<percent>100</percent>
<prov>0</prov>
<note></note>
</event>
<event>
<description>Weihnachten</description>
<id>23</id>
<dateStart>2022-12-25</dateStart>
<dateEnd>2022-12-25</dateEnd>
<class>2</class>
<percent>100</percent>
<prov>0</prov>
<note></note>
</event>
<event>
<description>Stephanstag</description>
<id>37</id>
<dateStart>2022-12-26</dateStart>
<dateEnd>2022-12-26</dateEnd>
<class>2</class>
<percent>100</percent>
<prov>0</prov>
<note></note>
</event>
</events>
</location>
</results>
</fcal_api>

CSV

URL:
https://www.feiertagskalender.ch/api/Data/CityId/index.php?api_key=YOUR_API_KEY&cityid=89&year=2022&format=csv

Antwort des APIs:

"location";"cityId";"iso";"iso-3166-2";"description";"id";"dateStart";"dateEnd";"class";"percent";"prov";"note"
"Zurich";"89";"CH";"CH-ZH";"Neujahr";"1";"2022-01-01";"2022-01-01";"2";"100";"0";""
"Zurich";"89";"CH";"CH-ZH";"Berchtoldstag";"3";"2022-01-02";"2022-01-02";"4";"100";"0";""
"Zurich";"89";"CH";"CH-ZH";"Karfreitag";"17";"2022-04-15";"2022-04-15";"2";"100";"0";""
"Zurich";"89";"CH";"CH-ZH";"Ostern";"18";"2022-04-17";"2022-04-17";"4";"100";"0";""
"Zurich";"89";"CH";"CH-ZH";"Ostermontag";"19";"2022-04-18";"2022-04-18";"2";"100";"0";""
"Zurich";"89";"CH";"CH-ZH";"Sechseläuten";"20";"2022-04-25";"2022-04-25";"4";"100";"0";""
"Zurich";"89";"CH";"CH-ZH";"Tag der Arbeit";"22";"2022-05-01";"2022-05-01";"2";"100";"0";""
"Zurich";"89";"CH";"CH-ZH";"Auffahrt";"31";"2022-05-26";"2022-05-26";"2";"100";"0";""
"Zurich";"89";"CH";"CH-ZH";"Pfingsten";"30";"2022-06-05";"2022-06-05";"4";"100";"0";""
"Zurich";"89";"CH";"CH-ZH";"Pfingstmontag";"35";"2022-06-06";"2022-06-06";"2";"100";"0";""
"Zurich";"89";"CH";"CH-ZH";"Nationalfeiertag Schweiz";"12";"2022-08-01";"2022-08-01";"2";"100";"0";""
"Zurich";"89";"CH";"CH-ZH";"Knabenschiessen";"60";"2022-09-12";"2022-09-12";"4";"100";"0";""
"Zurich";"89";"CH";"CH-ZH";"Weihnachten";"23";"2022-12-25";"2022-12-25";"2";"100";"0";""
"Zurich";"89";"CH";"CH-ZH";"Stephanstag";"37";"2022-12-26";"2022-12-26";"2";"100";"0";""

Fehlermeldungen

Art der Ausgabe	Fehlermeldung	Erläuterung
results: status:
results: status: description	not subscribed	Sie haben die gewünschten Daten nicht abonniert.
results: status: description	unknown location	Die angeforderte City-ID ist nicht bekannt.
apiStatus
apiStatus: description	invalid usage	Die Verwendung dieses API ist für diesen Nutzer nicht freigeschaltet.
apiStatus: description	invalid key	Ungültiger API-Schlüssel.
apiStatus: description	invalid referer	Ungültiger Zugriff. Links ab Webseiten (Front-Ends) sind nicht zulässig.
apiStatus: description	inactive	Das API wurde für noch nicht zur Benutzung freigeschaltet.
apiStatus: description	expired	Die Nutzungsdauer nach Vertrag ist abgelaufen.

Entwickler-Ebene

Jahresdaten

Jahresdaten für 1 Ort auslesen

API: Data/CityId

Funktion

Interaktive Anleitung und OpenAPI

API-Kapitel

URL für Anfragen

Parameter für Anfragen

Beispiele (URL / PHP / Python / JavaScript)

Rückgabewerte des API

Beispiele (JSON / XML / CSV)

JSON

XML

CSV

Fehlermeldungen

Seiten

mehr von psc Informatik

Feiertagskalender.ch

Feiertagskalender unterstützen