{
"openapi": "3.0.0",
"info": {
"title": "Feiertagskalender API",
"description": "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 `geoId`. 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.
**CSV note:** The CSV output contains a flat table structure in which nested JSON\/XML elements are not mapped. Some data fields are not available in CSV format.",
"version": "0.9.0"
},
"servers": [
{
"url": "https:\/\/feiertagskalender.ch\/api"
}
],
"paths": {
"\/CheckDate\/GeoId\/index.php": {
"get": {
"tags": [
"Read out day status by date"
],
"summary": "Get public holidays and school holidays for a specific date, based on a `geoId`. (query parameter)",
"description": "**CheckDate\/GeoId** 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 `geoId`. 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.",
"parameters": [
{
"name": "api_key",
"in": "query",
"required": true,
"description": "Your API Key",
"schema": {
"type": "string"
}
},
{
"name": "geoId",
"in": "query",
"required": true,
"description": "Geo-ID of the desired locality. The Geo-ID of Feiertagskalender.ch The available Geo-IDs can be found in the API: [GeoTree\/ISO](https:\/\/feiertagskalender.ch\/api\/GeoTree\/ISO\/docs.php?hl=en).",
"schema": {
"type": "integer"
}
},
{
"name": "date",
"in": "query",
"required": false,
"description": "The date to check (YYYY-mm-dd)",
"schema": {
"type": "string",
"format": "date"
}
},
{
"name": "class",
"in": "query",
"required": false,
"description": "Class type for filtering. Available values:\r\n- `0` = school holidays only\r\n- `3` = 0 + public holidays recognised by law\r\n- `4` = 0 + 3 + public and non-public holidays (religious, cultural) (default)\r\n- `5` = 0 + 3 + 4 + event days (e.g. Valentine's Day, Mother's Day, Advent)",
"schema": {
"type": "integer",
"enum": [
0,
3,
4,
5
],
"default": 4
}
},
{
"name": "charset",
"in": "query",
"required": false,
"description": "The desired coding of the response",
"schema": {
"type": "string",
"enum": [
"utf-8",
"iso-8859-1"
],
"default": "utf-8"
}
},
{
"name": "format",
"in": "query",
"required": false,
"description": "The desired output format",
"schema": {
"type": "string",
"enum": [
"json",
"xml",
"csv"
],
"default": "json"
}
},
{
"name": "date_format",
"in": "query",
"required": false,
"description": "The desired date format for the response. Default: `Y-m-d` (e.g., 2025-12-31)\r\n",
"schema": {
"type": "string",
"enum": [
"Y-m-d",
"d.m.Y",
"dmY",
"Ymd",
"d.n.y",
"j.n.y"
],
"default": "Y-m-d"
}
},
{
"name": "hl",
"in": "query",
"required": false,
"description": "Desired language of the output",
"schema": {
"type": "string",
"enum": [
"de",
"en",
"fr",
"it"
],
"default": "de"
}
}
],
"responses": {
"200": {
"description": "Successful response with the query results. The CSV output contains a flat table structure in which nested JSON\/XML elements are not mapped. Please note that some data fields are not available in CSV format. \n\n**JSON-Request:**\n`https:\/\/feiertagskalender.ch\/api\/CheckDate\/GeoId\/index.php?api_key=YOUR_API_KEY&geoid=3055&date=2025-12-25`\n\n**XML-Request:**\n`https:\/\/feiertagskalender.ch\/api\/CheckDate\/GeoId\/index.php?api_key=YOUR_API_KEY&geoid=3055&date=2025-12-25&format=XML`\n\n**CSV-Request:**\n`https:\/\/feiertagskalender.ch\/api\/CheckDate\/GeoId\/index.php?api_key=YOUR_API_KEY&geoid=3055&date=2025-12-25&format=CSV`\n\n",
"content": {
"application\/json": {
"example": {
"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\/GeoId",
"apiStatus": {
"description": "active"
},
"date": "2025-02-25",
"request": {
"geoId": "3055",
"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",
"geoId": "3055",
"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
}
}
}
}
},
"application\/xml": {
"schema": {
"type": "object",
"xml": {
"name": "fcal_api"
}
},
"example": "\r\nfcal API 2.01<\/interface>\r\n\r\nhttps:\/\/feiertagskalender.ch<\/href>\r\nfeiertagskalender.ch<\/description>\r\n<\/source>\r\n\r\nhttps:\/\/psc.ch<\/href>\r\npsc Peter Schuetz Informatik-Dienstleistungen, CH Bern<\/description>\r\n<\/copyright>\r\n\r\nactive<\/description>\r\n<\/apiStatus>\r\nCheckDate\/GeoId<\/apiName>\r\n2025-02-25<\/date>\r\n\r\n3055<\/geoId>\r\n2025-12-25<\/date>\r\nutf-8<\/charset>\r\nxml<\/format>\r\nY-m-d<\/date_format>\r\nde<\/hl>\r\n<\/request>\r\n\r\n\r\nok<\/description>\r\n<\/status>\r\n\r\nZürich<\/description>\r\nStadt<\/type>\r\n3055<\/geoId>\r\nCH<\/iso>\r\nCH-ZH<\/iso-3166-2>\r\n<\/note>\r\n\r\n2025-12-25<\/date>\r\n433989<\/total_population>\r\n433989<\/public_holiday_population>\r\n100<\/public_holiday_percent>\r\nWeihnachten<\/public_holiday_description>\r\n0<\/school_holiday_population>\r\n0<\/school_holiday_percent>\r\n<\/school_holiday_description>\r\n433989<\/sum_population>\r\n100<\/sum_percent>\r\n<\/date_status>\r\n<\/location>\r\n<\/results>\r\n<\/fcal_api>"
},
"application\/csv": {
"example": "\"location\";\"geoId\";\"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\"\r\n\"Zürich\";\"3055\";\"CH\";\"CH-ZH\";\"2025-12-25\";\"433989\";\"433989\";\"100\";\"Weihnachten\";\"0\";\"0\";\"\";\"433989\";\"100\""
}
}
},
"400": {
"description": "Incorrect request - missing or invalid parameters.",
"content": {
"application\/json": {
"examples": {
"not subscribed": {
"summary": "You have not subscribed to the desired data.",
"value": {
"results": {
"status": {
"description": "not subscribed"
}
}
}
},
"unknown_location": {
"summary": "The requested Geo-ID is not known.",
"value": {
"results": {
"status": {
"description": "unknown location"
}
}
}
}
}
}
}
},
"403": {
"description": "Access denied - Invalid API key.",
"content": {
"application\/json": {
"examples": {
"invalid_key": {
"summary": "Invalid API key.",
"value": {
"apiStatus": {
"description": "invalid key"
}
}
},
"invalid_usage": {
"summary": "The use of this API is not enabled for this user.",
"value": {
"apiStatus": {
"description": "invalid usage"
}
}
},
"invalid_referer": {
"summary": "Invalid access. Links from web pages (front-ends) are not allowed.",
"value": {
"apiStatus": {
"description": "invalid referer"
}
}
},
"inactive": {
"summary": "The API has not yet been activated for use.",
"value": {
"apiStatus": {
"description": "inactive"
}
}
},
"expired": {
"summary": "The period of use according to the contract has expired.",
"value": {
"apiStatus": {
"description": "expired"
}
}
}
}
}
}
},
"500": {
"description": "Interner Serverfehler – ein unerwarteter Fehler ist aufgetreten.",
"content": {
"application\/json": {
"example": {
"error": {
"code": 500,
"message": "Interner Serverfehler. Bitte versuchen Sie es später erneut."
}
}
}
}
}
}
},
"post": {
"tags": [
"Read out day status by date"
],
"summary": "Get public holidays and school holidays for a specific date, based on a `geoId`. ((JSON request)",
"description": "**CheckDate\/GeoId** 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 `geoId`. The `date` parameter is optional - if it is not specified, today's date is automatically used. The output can also be configured using additional parameters. The parameters are transferred as JSON in the request body. Alternatively, authorisation can also take place in the header. ",
"requestBody": {
"required": true,
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"api_key": {
"type": "string"
},
"geoid": {
"type": "integer",
"minimum": 1,
"maximum": 9999
},
"date": {
"type": "string",
"format": "date"
},
"class": {
"type": "integer",
"enum": [
0,
3,
4,
5
],
"default": 4
},
"charset": {
"type": "string",
"enum": [
"utf-8",
"iso-8859-1"
],
"default": "utf-8"
},
"format": {
"type": "string",
"enum": [
"json",
"xml",
"csv"
],
"default": "json"
},
"date_format": {
"type": "string",
"enum": [
"Y-m-d",
"d.m.Y"
],
"default": "Y-m-d"
},
"hl": {
"type": "string",
"enum": [
"de",
"fr",
"it",
"en"
],
"default": "de"
}
},
"required": [
"api_key",
"geoId"
]
},
"example": {
"api_key": "YOUR_API_KEY",
"date": "2025-12-25",
"geoId": 3055
}
}
}
},
"responses": {
"200": {
"description": "Successful response with the query results. The CSV output contains a flat table structure in which nested JSON\/XML elements are not mapped. Please note that some data fields are not available in CSV format.",
"content": {
"application\/json": {
"example": {
"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\/GeoId",
"apiStatus": {
"description": "active"
},
"date": "2025-02-25",
"request": {
"geoId": "3055",
"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",
"geoId": "3055",
"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
}
}
}
}
},
"application\/xml": {
"schema": {
"type": "object",
"xml": {
"name": "fcal_api"
}
},
"example": "\r\nfcal API 2.01<\/interface>\r\n\r\nhttps:\/\/feiertagskalender.ch<\/href>\r\nfeiertagskalender.ch<\/description>\r\n<\/source>\r\n\r\nhttps:\/\/psc.ch<\/href>\r\npsc Peter Schuetz Informatik-Dienstleistungen, CH Bern<\/description>\r\n<\/copyright>\r\n\r\nactive<\/description>\r\n<\/apiStatus>\r\nCheckDate\/GeoId<\/apiName>\r\n2025-02-25<\/date>\r\n\r\n3055<\/geoId>\r\n2025-12-25<\/date>\r\nutf-8<\/charset>\r\nxml<\/format>\r\nY-m-d<\/date_format>\r\nde<\/hl>\r\n<\/request>\r\n\r\n\r\nok<\/description>\r\n<\/status>\r\n\r\nZürich<\/description>\r\nStadt<\/type>\r\n3055<\/geoId>\r\nCH<\/iso>\r\nCH-ZH<\/iso-3166-2>\r\n<\/note>\r\n\r\n2025-12-25<\/date>\r\n433989<\/total_population>\r\n433989<\/public_holiday_population>\r\n100<\/public_holiday_percent>\r\nWeihnachten<\/public_holiday_description>\r\n0<\/school_holiday_population>\r\n0<\/school_holiday_percent>\r\n<\/school_holiday_description>\r\n433989<\/sum_population>\r\n100<\/sum_percent>\r\n<\/date_status>\r\n<\/location>\r\n<\/results>\r\n<\/fcal_api>"
},
"application\/csv": {
"example": "\"location\";\"geoId\";\"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\"\r\n\"Zürich\";\"3055\";\"CH\";\"CH-ZH\";\"2025-12-25\";\"433989\";\"433989\";\"100\";\"Weihnachten\";\"0\";\"0\";\"\";\"433989\";\"100\""
}
}
},
"400": {
"description": "Incorrect request - missing or invalid parameters.",
"content": {
"application\/json": {
"examples": {
"not subscribed": {
"summary": "You have not subscribed to the desired data.",
"value": {
"results": {
"status": {
"description": "not subscribed"
}
}
}
},
"unknown_location": {
"summary": "The requested Geo-ID is not known.",
"value": {
"results": {
"status": {
"description": "unknown location"
}
}
}
}
}
}
}
},
"403": {
"description": "Access denied - Invalid API key.",
"content": {
"application\/json": {
"examples": {
"invalid_key": {
"summary": "Invalid API key.",
"value": {
"apiStatus": {
"description": "invalid key"
}
}
},
"invalid_usage": {
"summary": "The use of this API is not enabled for this user.",
"value": {
"apiStatus": {
"description": "invalid usage"
}
}
},
"invalid_referer": {
"summary": "Invalid access. Links from web pages (front-ends) are not allowed.",
"value": {
"apiStatus": {
"description": "invalid referer"
}
}
},
"inactive": {
"summary": "The API has not yet been activated for use.",
"value": {
"apiStatus": {
"description": "inactive"
}
}
},
"expired": {
"summary": "The period of use according to the contract has expired.",
"value": {
"apiStatus": {
"description": "expired"
}
}
}
}
}
}
},
"500": {
"description": "Interner Serverfehler – ein unerwarteter Fehler ist aufgetreten.",
"content": {
"application\/json": {
"example": {
"error": {
"code": 500,
"message": "Interner Serverfehler. Bitte versuchen Sie es später erneut."
}
}
}
}
}
}
}
}
}
}