Documentazione API

Dati giornalieri

Leggi lo stato del giorno per data

utilizzando Geo-ID utilizzando City-ID Svizzera / Liechtenstein: utilizzando codice postale

Svizzera / Liechtenstein: utilizzando numero del comune dell'UST

API: CheckDate/CH/PLZ

Ottenere i giorni festivi e le vacanze scolastiche per una data specifica, in base a un codice postale svizzero (PLZ).

Funzione

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.

Guida interattiva e OpenAPI aperta

OpenAPI 3.0 (Swagger) – Documentazione API interattiva

Apre la documentazione interattiva dell'API con Swagger, dove è possibile testare ed esplorare gli endpoint dell'API.

Scarica le specifiche JSON di OpenAPI

URL per le richieste

Per recuperare i dati, utilizzare il seguente URL. Si prega di prestare attenzione alle maiuscole e alle minuscole.

POST / GET

https://feiertagskalender.ch/api/CheckDate/CH/PLZ/index.php

Parametri per le richieste

Con le seguenti variabili è possibile completare la query e controllare i risultati delle API.

Parametro	Spiegazione	Esempi
api_key richiesto	La vostra chiave API	api_key=abc-123-def-456
plz richiesto	Codice postale svizzero	plz=8000
date	La data da controllare senza specifica: oggi (= Standard)	date=2025-06-01
class o klasse	Portata dei dati Varianti: 0 = solo vacanze scolastiche 3 = 0 + giorni festivi riconosciuti dalla legge 4 = 0 + 3 + festività pubbliche e non (religiose, culturali) (= Standard) 5 = 0 + 3 + 4 + giorni di evento (ad es. San Valentino, Festa della mamma, Avvento)	klasse=5
charset	La codifica desiderata della risposta Varianti: UTF-8 (= Standard) ISO-8859-1	charset=iso-8859-1
format	Il formato di uscita desiderato Varianti: JSON (= Standard) XML CSV	format=xml
date_format	Il formato della data desiderato per la risposta. Standard:`Y-m-d` (ad esempio, 2025-12-31). Il formato corrisponde alla formattazione della data dell'istruzione PHP date() Varianti: 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	Lingua desiderata dell'uscita Varianti: de = Tedesco (= Standard) fr = Francese it = Italiano en = Inglese	hl=en

Esempi (URL / PHP / Python / JavaScript)

Mostra esempi

Parametri nell'URL

I parametri possono essere inclusi nell'URL (ad esempio, tramite il browser o in Excel):
Nota: Il primo parametro è introdotto con ?, tutti gli altri parametri sono introdotti con &.

Importante: questo codice non deve essere utilizzato direttamente in un sito web! Per motivi di sicurezza, le chiavi API devono essere elaborate solo nel backend.

https://feiertagskalender.ch/api/CheckDate/CH/PLZ/index.php?api_key=YOUR_API_KEY&plz=8000&date=2025-12-25

Esempio PHP con cURL (GET)

$api_url = "https://feiertagskalender.ch/api/CheckDate/CH/PLZ/index.php?plz=8000&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;

Esempio PHP con cURL (POST)

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

// POST-Daten
$post_data = json_encode([
    "plz": "8000", "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;

Esempio Python con requests (GET)

import requests

api_key = "YOUR_API_KEY"
api_url = "https://feiertagskalender.ch/api/CheckDate/CH/PLZ/index.php?plz=8000&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)

Esempio Python con requests (POST)

import requests

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

payload = {
    "plz": "8000", "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)

Esempio JavaScript con Fetch API (GET)

L'API Fetch è un metodo moderno per eseguire richieste HTTP in JavaScript. È supportata dai browser attuali.

Importante: questo codice non deve essere utilizzato direttamente in un sito web! Per motivi di sicurezza, le chiavi API devono essere elaborate solo nel backend.

const apiUrl = "https://feiertagskalender.ch/api/CheckDate/CH/PLZ/index.php?plz=8000&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));

Esempio JavaScript con Fetch API (POST)

L'API Fetch è un metodo moderno per eseguire richieste HTTP in JavaScript. È supportata dai browser attuali.

const apiUrl = "https://feiertagskalender.ch/api/CheckDate/CH/PLZ/index.php";
const apiKey = "YOUR_API_KEY";  
const requestData = {
    "plz": "8000", "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));

Valori di ritorno dell'API

Il contenuto delle risposte API deriva da:
- i dati che hai sottoscritto (paesi, vacanze, vacanze scolastiche, anni solari)
- i dati ufficialmente noti dei legislatori
- la disponibilità in base alle nostre ricerche (situazione effettiva del nostro database)

Si prega di notare che l'output in formato CSV è diverso.

Array				Spiegazione	Esempio
interface				Versione dell'API
source:	href			URL della fonte dei dati (sito web)
	description			Nome della fonte dei dati
copyright	href			URL al titolare del copyright (sito web)
	description			Designazione del titolare del diritto d'autore
apiName				Identificazione dell'API	CheckDate/CH/PLZ
apiStatus	description			Designazione dello stato API. Per le varianti, vedere i Messaggi di errore	active
date				Data di esportazione dei dati	01.05.2025
request:	plz			Codice postale svizzero	8000
	date			Data dei dati nell'output	2025-12-25
	charset			Codifica dei caratteri di output	utf-8
	format			Formato dei dati di uscita	json
	date_format			Formato data dell'output	d.m.Y
	hl			Lingua di emissione, secondo la richiesta	it
results	status	description		Stato dell'output. Per le varianti, vedere i Messaggi di errore	ok
	location	description		Nome dell'unità geografica	Bienna
		type		Designazione del tipo di unità geografica	Città
		geoId		Geo-ID dell'unità geografica.	424
		iso		Codice ISO del paese, 2 cifre	CH
		iso-3166-2		Codice regione secondo ISO 3166-2	CH-BE
		note		Note speciali
		date_status		Stato del giorno
			date	Data	2025-12-25
			total_population	Numero totale di abitanti	54640
			public_holiday_population	Numero di abitanti con giorni festivi	0
			public_holiday_percent	Percentuale di abitanti con giorni festivi	0
			public_holiday_description	Designazione della festa
			school_holiday_population	Numero di abitanti con vacanze scolastiche	54640
			school_holiday_percent	Percentuale di popolazione con vacanze scolastiche	100
			school_holiday_description	Designazione Vacanze scolastiche	Vacanze di primavera
			sum_population	Numero totale di abitanti interessati	54640
			percent_population	Percentuale di abitanti interessati	100

Esempi (JSON / XML / CSV)

JSON

URL:
https://www.feiertagskalender.ch/api/CheckDate/CH/PLZ/index.php?api_key=YOUR_API_KEY&plz=8000&date=2025-12-25

Risposta delle 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/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
            }
        }
    }
}

XML

URL:
https://www.feiertagskalender.ch/api/CheckDate/CH/PLZ/index.php?api_key=YOUR_API_KEY&plz=8000&date=2025-12-25&format=XML

Risposta delle 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/CH/PLZ</apiName>
<date>2025-02-25</date>
<request>
<plz>8000</plz>
<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>
<geoId>3055</geoId>
<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/CH/PLZ/index.php?api_key=YOUR_API_KEY&plz=8000&date=2025-12-25&format=csv

Risposta delle API:

"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"
"Zürich";"8000";"CH";"CH-ZH";"2025-12-25";"433989";"433989";"100";"Weihnachten";"0";"0";"";"433989";"100"

Messaggi di errore

Posizione di uscita	Messaggio di errore	Spiegazione
results: status:
results: status: description	not subscribed	Non avete sottoscritto i dati desiderati.
results: status: description	unknown location	Il codice postale svizzero richiesto non è noto.
apiStatus
apiStatus: description	invalid usage	L'uso di questa API non è abilitato per questo utente.
apiStatus: description	invalid key	Chiave API non valida.
apiStatus: description	invalid referer	Accesso non valido. Non sono ammessi link da pagine web (front-end).
apiStatus: description	inactive	L'API non è ancora stata attivata per l'uso.
apiStatus: description	expired	Il periodo di utilizzo secondo il contratto è scaduto.

Area sviluppatori

Dati giornalieri

Leggi lo stato del giorno per data

API: CheckDate/CH/PLZ

Funzione

Guida interattiva e OpenAPI aperta

Capitoli API

URL per le richieste

Parametri per le richieste

Esempi (URL / PHP / Python / JavaScript)

Valori di ritorno dell'API

Esempi (JSON / XML / CSV)

JSON

XML

CSV

Messaggi di errore

Pagine

altro da psc Informatik

Feiertagskalender.ch

Supportare il calendario dei giorni festivi