{
"openapi": "3.0.0",
"info": {
"title": "Feiertagskalender API",
"description": "Questa API determina se in una data specifica c'è una festività ufficiale o una vacanza scolastica in una località specifica. I parametri richiesti sono `api_key` e `plz`. Il parametro `date` è opzionale: se non viene specificato, viene automaticamente utilizzata la data odierna. Inoltre, l'output può essere configurato utilizzando altri parametri. I parametri vengono passati come parametri di query nell'URL. In alternativa, l'autorizzazione può avvenire anche nell'intestazione.
**Nota: ** L'output CSV contiene una struttura tabellare piatta in cui gli elementi JSON\/XML annidati non sono mappati. Alcuni campi di dati non sono disponibili in formato CSV.",
"version": "0.9.0"
},
"servers": [
{
"url": "https:\/\/feiertagskalender.ch\/api"
}
],
"paths": {
"\/CheckDate\/CH\/PLZ\/index.php": {
"get": {
"tags": [
"Leggi lo stato del giorno per data"
],
"summary": "Ottenere i giorni festivi e le vacanze scolastiche per una data specifica, in base a un codice postale svizzero (PLZ). (parametro della query)",
"description": "**CheckDate\/CH\/PLZ** Questa API determina se in una data specifica c'è una festività ufficiale o una vacanza scolastica in una località specifica. I parametri richiesti sono `api_key` e `plz`. Il parametro `date` è opzionale: se non viene specificato, viene automaticamente utilizzata la data odierna. Inoltre, l'output può essere configurato utilizzando altri parametri. I parametri vengono passati come parametri di query nell'URL. In alternativa, l'autorizzazione può avvenire anche nell'intestazione.",
"parameters": [
{
"name": "api_key",
"in": "query",
"required": true,
"description": "La vostra chiave API",
"schema": {
"type": "string"
}
},
{
"name": "plz",
"in": "query",
"required": true,
"description": "Codice postale svizzero (1000 - 9999) ",
"schema": {
"type": "integer",
"minimum": 1000,
"maximum": 9999
}
},
{
"name": "date",
"in": "query",
"required": false,
"description": "La data da controllare (YYYY-mm-dd)",
"schema": {
"type": "string",
"format": "date"
}
},
{
"name": "class",
"in": "query",
"required": false,
"description": "Tipo di classe per il filtraggio. Valori disponibili:\r\n- `0` = solo vacanze scolastiche\r\n- `3` = 0 + festività pubbliche riconosciute dalla legge\r\n- `4` = 0 + 3 + festività pubbliche e non pubbliche (religiose, culturali) (predefinito)\r\n- `5` = 0 + 3 + 4 + giorni di eventi (ad es. San Valentino, Festa della mamma, Avvento)",
"schema": {
"type": "integer",
"enum": [
0,
3,
4,
5
],
"default": 4
}
},
{
"name": "charset",
"in": "query",
"required": false,
"description": "La codifica desiderata della risposta",
"schema": {
"type": "string",
"enum": [
"utf-8",
"iso-8859-1"
],
"default": "utf-8"
}
},
{
"name": "format",
"in": "query",
"required": false,
"description": "Il formato di uscita desiderato",
"schema": {
"type": "string",
"enum": [
"json",
"xml",
"csv"
],
"default": "json"
}
},
{
"name": "date_format",
"in": "query",
"required": false,
"description": "Il formato della data desiderato per la risposta. Standard:`Y-m-d` (ad esempio, 2025-12-31).",
"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": "Lingua desiderata dell'uscita",
"schema": {
"type": "string",
"enum": [
"de",
"en",
"fr",
"it"
],
"default": "de"
}
}
],
"responses": {
"200": {
"description": "Risposta di successo con i risultati della query. L'output CSV contiene una struttura tabellare piatta in cui gli elementi JSON\/XML annidati non sono mappati. Si noti che alcuni campi di dati non sono disponibili in formato CSV. \n\n**JSON-Request:**\n`https:\/\/feiertagskalender.ch\/api\/CheckDate\/CH\/PLZ\/index.php?api_key=YOUR_API_KEY&plz=8000&date=2025-12-25`\n\n**XML-Request:**\n`https:\/\/feiertagskalender.ch\/api\/CheckDate\/CH\/PLZ\/index.php?api_key=YOUR_API_KEY&plz=8000&date=2025-12-25&format=XML`\n\n**CSV-Request:**\n`https:\/\/feiertagskalender.ch\/api\/CheckDate\/CH\/PLZ\/index.php?api_key=YOUR_API_KEY&plz=8000&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\/CH\/PLZ",
"apiStatus": {
"description": "active"
},
"date": "2025-02-25",
"request": {
"plz": "8000",
"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\/CH\/PLZ<\/apiName>\r\n2025-02-25<\/date>\r\n\r\n8000<\/plz>\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\";\"plz\";\"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\";\"8000\";\"CH\";\"CH-ZH\";\"2025-12-25\";\"433989\";\"433989\";\"100\";\"Weihnachten\";\"0\";\"0\";\"\";\"433989\";\"100\""
}
}
},
"400": {
"description": "Richiesta errata - parametri mancanti o non validi.",
"content": {
"application\/json": {
"examples": {
"not subscribed": {
"summary": "Non avete sottoscritto i dati desiderati.",
"value": {
"results": {
"status": {
"description": "not subscribed"
}
}
}
},
"unknown_location": {
"summary": "Il codice postale svizzero richiesto non è noto. ",
"value": {
"results": {
"status": {
"description": "unknown location"
}
}
}
}
}
}
}
},
"403": {
"description": "Accesso negato - Chiave API non valida.",
"content": {
"application\/json": {
"examples": {
"invalid_key": {
"summary": "Chiave API non valida.",
"value": {
"apiStatus": {
"description": "invalid key"
}
}
},
"invalid_usage": {
"summary": "L'uso di questa API non è abilitato per questo utente.",
"value": {
"apiStatus": {
"description": "invalid usage"
}
}
},
"invalid_referer": {
"summary": "Accesso non valido. Non sono ammessi link da pagine web (front-end).",
"value": {
"apiStatus": {
"description": "invalid referer"
}
}
},
"inactive": {
"summary": "L'API non è ancora stata attivata per l'uso.",
"value": {
"apiStatus": {
"description": "inactive"
}
}
},
"expired": {
"summary": "Il periodo di utilizzo secondo il contratto è scaduto.",
"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": [
"Leggi lo stato del giorno per data"
],
"summary": "Ottenere i giorni festivi e le vacanze scolastiche per una data specifica, in base a un codice postale svizzero (PLZ). (richiesta JSON)",
"description": "**CheckDate\/CH\/PLZ** Questa API determina se in una data specifica c'è una festività ufficiale o una vacanza scolastica in una località specifica. I parametri richiesti sono `api_key` e `plz`. Il parametro `date` è opzionale: se non viene specificato, viene automaticamente utilizzata la data odierna. L'output può essere configurato anche con parametri aggiuntivi. I parametri vengono trasferiti come JSON nel corpo della richiesta. In alternativa, l'autorizzazione può avvenire anche nell'intestazione. ",
"requestBody": {
"required": true,
"content": {
"application\/json": {
"schema": {
"type": "object",
"properties": {
"api_key": {
"type": "string"
},
"plz": {
"type": "integer",
"minimum": 1000,
"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",
"plz"
]
},
"example": {
"api_key": "YOUR_API_KEY",
"date": "2025-12-25",
"plz": 8000
}
}
}
},
"responses": {
"200": {
"description": "Risposta di successo con i risultati della query. L'output CSV contiene una struttura tabellare piatta in cui gli elementi JSON\/XML annidati non sono mappati. Si noti che alcuni campi di dati non sono disponibili in formato CSV.",
"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\/CH\/PLZ",
"apiStatus": {
"description": "active"
},
"date": "2025-02-25",
"request": {
"plz": "8000",
"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\/CH\/PLZ<\/apiName>\r\n2025-02-25<\/date>\r\n\r\n8000<\/plz>\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\";\"plz\";\"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\";\"8000\";\"CH\";\"CH-ZH\";\"2025-12-25\";\"433989\";\"433989\";\"100\";\"Weihnachten\";\"0\";\"0\";\"\";\"433989\";\"100\""
}
}
},
"400": {
"description": "Richiesta errata - parametri mancanti o non validi.",
"content": {
"application\/json": {
"examples": {
"not subscribed": {
"summary": "Non avete sottoscritto i dati desiderati.",
"value": {
"results": {
"status": {
"description": "not subscribed"
}
}
}
},
"unknown_location": {
"summary": "Il codice postale svizzero richiesto non è noto. ",
"value": {
"results": {
"status": {
"description": "unknown location"
}
}
}
}
}
}
}
},
"403": {
"description": "Accesso negato - Chiave API non valida.",
"content": {
"application\/json": {
"examples": {
"invalid_key": {
"summary": "Chiave API non valida.",
"value": {
"apiStatus": {
"description": "invalid key"
}
}
},
"invalid_usage": {
"summary": "L'uso di questa API non è abilitato per questo utente.",
"value": {
"apiStatus": {
"description": "invalid usage"
}
}
},
"invalid_referer": {
"summary": "Accesso non valido. Non sono ammessi link da pagine web (front-end).",
"value": {
"apiStatus": {
"description": "invalid referer"
}
}
},
"inactive": {
"summary": "L'API non è ancora stata attivata per l'uso.",
"value": {
"apiStatus": {
"description": "inactive"
}
}
},
"expired": {
"summary": "Il periodo di utilizzo secondo il contratto è scaduto.",
"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."
}
}
}
}
}
}
}
}
}
}