API documentation

Daily data

Read out day status by date

using Geo-ID using City-ID Switzerland / Liechtenstein: using postcode

Switzerland / Liechtenstein: using FSO community number

API: CheckDate/CityId

Get public holidays and school holidays for a specific date, based on a `cityId`.

Function

This API determines whether an official public holiday or school holidays are taking place on a specified date at a specified location. The required parameters are `api_key` and `cityId`. The `date` parameter is optional - if it is not specified, today's date is automatically used. In addition, the output can be configured using further parameters. The parameters are passed as query parameters in the URL. Alternatively, authorisation can also take place in the header.

The available City-IDs can be found in the API: GeoTree/ISO

Interactive guide and OpenAPI

OpenAPI 3.0 (Swagger) – Interactive API documentation

Opens the interactive API documentation with Swagger, where you can test and explore API endpoints.

Download OpenAPI JSON specification

API Chapters

URL for requests
Request parameters
Examples (URL / PHP / Python / JavaScript)
Return values of the API
Examples (JSON / XML / CSV)
Error messages

URL for requests

To retrieve the data, use the following URL. Please pay attention to upper case lower case.

POST / GET

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

Request parameters

With the following variables you can complete the query and control the API results.

Parameter	Explanation	Examples
api_key required	Your API Key	api_key=abc-123-def-456
cityId required	City-ID of the desired location. The city ID from Feiertagskalender.ch is used.	cityid=88
date	The date to check without specification: today (= default)	date=2025-06-01
class or klasse	Scope of the data Variants: 0 = school holidays only 3 = 0 + public holidays recognised by law 4 = 0 + 3 + public and non-statutory holidays (religious, cultural) (= default) 5 = 0 + 3 + 4 + event days (e.g. Valentine's Day, Mother's Day, Advent Sundays)	klasse=5
charset	The desired coding of the response Variants: UTF-8 (= default) ISO-8859-1	charset=iso-8859-1
format	The desired output format Variants: JSON (= default) XML CSV	format=xml
date_format	The desired date format for the response. Default: `Y-m-d` (e.g., 2025-12-31) The format corresponds to the date formatting of the PHP instruction date() Variants: Y-m-d = YYYY-MM-DD (ISO-8601) (= default) 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	Desired language of the output Variants: de = German (= default) fr = French it = Italian en = English	hl=en

Examples (URL / PHP / Python / JavaScript)

Show examples

Parameters in the URL

Parameters can be included in the URL (e.g. via the browser or in Excel):
Note: The first parameter is introduced with ?, all other parameters are introduced with &.

Important: This code must not be used directly in a website! For security reasons, API keys must only be processed in the backend.

https://feiertagskalender.ch/api/CheckDate/CityId/index.php?api_key=YOUR_API_KEY&cityid=89&date=2025-12-25

Example PHP with cURL (GET)

$api_url = "https://feiertagskalender.ch/api/CheckDate/CityId/index.php?cityid=89&date=2025-12-25";
$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;

Example PHP with cURL (POST)

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

// POST-Daten
$post_data = json_encode([
    "cityid": "89", "date": "2025-12-25"	
]);

$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;

Example Python with requests (GET)

import requests

api_key = "YOUR_API_KEY"
api_url = "https://feiertagskalender.ch/api/CheckDate/CityId/index.php?cityid=89&date=2025-12-25"
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)

Example Python with requests (POST)

import requests

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

payload = {
    "cityid": "89", "date": "2025-12-25"	
}

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)

Example JavaScript with Fetch API (GET)

The Fetch API is a modern method for executing HTTP requests in JavaScript. It is supported in current browsers.

Important: This code must not be used directly in a website! For security reasons, API keys must only be processed in the backend.

const apiUrl = "https://feiertagskalender.ch/api/CheckDate/CityId/index.php?cityid=89&date=2025-12-25";
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));

Example JavaScript with Fetch API (POST)

The Fetch API is a modern method for executing HTTP requests in JavaScript. It is supported in current browsers.

const apiUrl = "https://feiertagskalender.ch/api/CheckDate/CityId/index.php";
const apiKey = "YOUR_API_KEY";  
const requestData = {
    "cityid": "89", "date": "2025-12-25"	
};

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));

Return values of the API

The contents of the API responses result from:
- the data you have subscribed to (countries, public holidays, school holidays, calendar years)
- the officially known data of the legislators
- the availability based on our research (ACTUAL situation of our database)

Please note that the output in CSV format differs.

Array				Explanation	Example
interface				Version of the API
source:	href			URL to the data source (website)
	description			Name of the data source
copyright	href			URL to the copyright holder (website)
	description			Designation of the copyright holder
apiName				Identification of the API	CheckDate/CityId
apiStatus	description			Designation of the API status. For variants, see the Error messages	active
date				Date of the data export	01.05.2025
request:	cityId			City-ID according to request	88
	date			Date of the data in the output	2019-04-18
	charset			Font coding of the output	utf-8
	format			Output data format	json
	date_format			Output date format	d.m.Y
	hl			Language of issue, according to request	en
results	status	description		Output status. For variants, see the Error messages	ok
	location	description		Designation of the geographical unit	Berlin
		type		Designation of the type of geographical unit	Stadt
		cityId			Geo-ID of the geographical unit.	89
		iso		ISO country code, 2 digits	DE
		iso-3166-2		Region code according to ISO 3166-2	DE-BE
		note		Special notes
		date_status		Day status
			date	Date	2019-04-18
			total_population	Total number of inhabitants	3601131
			public_holiday_population	Number of inhabitants with public holiday	0
			public_holiday_percent	Percent Inhabitants with public holiday	0
			public_holiday_description	Designation of the public holiday
			school_holiday_population	Number of inhabitants with school holidays	3601131
			school_holiday_percent	Percent Inhabitants with school holidays	100
			school_holiday_description	Designation school holidays	Osterferien
			sum_population	Total number of inhabitants affected	3601131
			percent_population	Percentage of inhabitants affected	100

Examples (JSON / XML / CSV)

JSON

URL:
https://www.feiertagskalender.ch/api/CheckDate/CityId/index.php?api_key=YOUR_API_KEY&cityid=89&date=2025-12-25

Response from the API:

{
    "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": "CheckDate/CityId",
    "apiStatus": {
        "description": "active"
    },
    "date": "2025-02-25",
    "request": {
        "cityId": "89",
        "date": "2025-12-25",
        "charset": "utf-8",
        "format": "json",
        "date_format": "Y-m-d",
        "hl": "de"
    },
    "results": {
        "status": {
            "description": "ok"
        },
        "location": {
            "description": "Zürich",
            "type": "Stadt",
            "cityId": "89",
            "iso": "CH",
            "iso-3166-2": "CH-ZH",
            "note": "",
            "date_status": {
                "date": "2025-12-25",
                "total_population": 433989,
                "public_holiday_population": 433989,
                "public_holiday_percent": 100,
                "public_holiday_description": "Weihnachten",
                "school_holiday_population": 0,
                "school_holiday_percent": 0,
                "school_holiday_description": null,
                "sum_population": 433989,
                "sum_percent": 100
            }
        }
    }
}

XML

URL:
https://www.feiertagskalender.ch/api/CheckDate/CityId/index.php?api_key=YOUR_API_KEY&cityid=89&date=2025-12-25&format=XML

Response from the API:

<fcal_api>
<interface>fcal API 2.01</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>CheckDate/CityId</apiName>
<date>2025-02-25</date>
<request>
<cityId>89</cityId>
<date>2025-12-25</date>
<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>Zürich</description>
<type>Stadt</type>
<cityId>89</cityId>
<iso>CH</iso>
<iso-3166-2>CH-ZH</iso-3166-2>
<note></note>
<date_status>
<date>2025-12-25</date>
<total_population>433989</total_population>
<public_holiday_population>433989</public_holiday_population>
<public_holiday_percent>100</public_holiday_percent>
<public_holiday_description>Weihnachten</public_holiday_description>
<school_holiday_population>0</school_holiday_population>
<school_holiday_percent>0</school_holiday_percent>
<school_holiday_description></school_holiday_description>
<sum_population>433989</sum_population>
<sum_percent>100</sum_percent>
</date_status>
</location>
</results>
</fcal_api>

CSV

URL:
https://www.feiertagskalender.ch/api/CheckDate/CityId/index.php?api_key=YOUR_API_KEY&cityid=89&date=2025-12-25&format=CSV

Response from the API:

"location";"cityId";"iso";"iso-3166-2";"date";"total_population";"public_holiday_population";"public_holiday_percent";"public_holiday_description";"school_holiday_population";"school_holiday_percent";"school_holiday_description";"sum_population";"sum_percent"
"Zürich";"89";"CH";"CH-ZH";"2025-12-25";"433989";"433989";"100";"Weihnachten";"0";"0";"";"433989";"100"

Error messages

Output location	Error message	Explanation
results: status:
results: status: description	not subscribed	You have not subscribed to the desired data.
results: status: description	unknown location	The requested City-ID is not known.
apiStatus
apiStatus: description	invalid usage	The use of this API is not enabled for this user.
apiStatus: description	invalid key	Invalid API key.
apiStatus: description	invalid referer	Invalid access. Links from web pages (front-ends) are not allowed.
apiStatus: description	inactive	The API has not yet been activated for use.
apiStatus: description	expired	The period of use according to the contract has expired.

Developer area

Daily data

Read out day status by date

API: CheckDate/CityId

Function

Interactive guide and OpenAPI

API Chapters

URL for requests

Request parameters

Examples (URL / PHP / Python / JavaScript)

Return values of the API

Examples (JSON / XML / CSV)

JSON

XML

CSV

Error messages

Pages

more from psc Informatik

Feiertagskalender.ch

Support public holiday calendar