API documentation

Function

Allows you to query a country by ISO country code. Displays all municipalities (Switzerland), or regions (other countries) with their holidays and school holidays, from 1.01. - 31.12. of a year.

Chapters

URL for requests Parameters for requests Return values of the API Error messages Examples

URL for requests

URL

To retrieve the data, use the following URL.
Please pay attention to capital letters.

GET

POST

Parameters for requests

The following variables can be used to complete the query and affect the API results.

Parameter	Explanation	Examples
api_key required	Your API key	?api_key=abc-123-def-456
iso required	ISO country code (2 digits)	&iso=DE
year or jahr	Year of the desired data. Available according to contract Without specification: current calendar year (= standard)	&year= 2025
class or klasse	Scope of the holidays by significance. Variants: 0 = only school holidays 3 = 0 + legally recognized holidays 4 = 0 + 3 + legal and non-recognised holidays (religious, cultural) (=standard) 5 = 0 + 3 + 4 + Event days (e.g. Valentine's Day, Mother's Day, Advent)	&klasse=5
charset	The desired encoding of the answer. Variants: UTF-8 (= standard) ISO-8859-1	&charset=iso-8859-1
format	The desired output format. Variants: JSON (= standard) XML CSV	&format=xml
date_format	The desired date format. The format corresponds to the formatting of the PHP statement date(). Variants: Y-m-d = YYYY-MM-DD, according to 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	Desired output language. Variants: de (= standard) fr it en	&hl=en

Return values of the API

Data

The contents of the API answers result from:
- the dates you subscribe to (countries, holidays, school holidays, calendar years)
- the official known data of the legislators
- availability based on our research (actual situation of our database)

Please note that the output in CSV format differs

Parameter					Explanation	Example
interface					Version of the API
source:	href				URL to data source (website)
	description				Name of the data source
copyright:	href				URL to the copyright owner (website)
	description				Designation of the copyright holder
apiName					Identification of the API	Data/Country
apiStatus	description				Description of the API status	active
date					Date of data export	02.05.2024
request:	iso				Länderkürzel	DE
	year				Year of the data in the output	2015
	class				Class of the query, concerns scope of data, by significance	4
	charset				Font encoding of the output	utf-8
	format				Data format of the output	json
	date_format			Date format, according to request	d.m.Y
	hl				Output language	de
results	status	description			Output status	ok
	locations	location	description		Name of the geographical unit	Baden-Württemberg
			type		Designation of the type of geographical unit	Bundesland
			geoId		Id of the geographical unit (Id by Feiertagskalender.ch)	3060
			iso		ISO country code, 2 digits	DE
			iso-3166-2		Region code according to ISO 3166-2	DE-BW
			events		the calendar events
				description	Name of the holiday, or school holidays	Neujahrstag
				id	Unique ID of the event	1
				dateStart	Start date of the event	01.01.2015
				dateEnd	End date of the event	01.01.2015
				class	Class of the event: 0 = school holidays 1 = legally recognized public holiday (public rest day) 2 = holiday equivalent to Sundays 3 = half, legally recognized holiday (usually from noon) 4 = not legally recognized public holiday (shops, schools, administrations mostly closed), bank holiday; For the purposes of the European Convention on the Calculation of Time Limits, this day is treated as a public holiday (Article 5). 5 = event day # = only partially valid	2
				percent	Percentage of inhabitants / school classes	100
				prov	Flag for provisional data 0 = definitely 1 = provisional	0
				note	Special notes

Error messages

Place of issue	Error message	Explanation
results: status: description	not subscribed	You have not subscribed to the required data. Please contact our support.
results: status: description	unknown location	The requested ISO country code is not known Please check the ISO country code.
apiStatus: description	invalid usage	The use of this API is not intended for you. Please contact our support.
apiStatus: description	invalid key	Invalid API key. Please check your API key.
apiStatus: description	invalid referer	Invalid access. Links from websites (front-ends) are not permitted. Set up your query so that it comes from a protected back-end. If necessary, please contact the Feiertagskalender.ch support.
apiStatus: description	inactive	The API has not yet been unlocked for use. Please try again later.
apiStatus: description	expired	The useful life according to the contract has expired. Please contact the Feiertagskalender.ch Administration for a contract extension.

Examples

JSON

Call:
https://feiertagskalender.ch/api/Data/Country/?api_key=YOUR_API_KEY&jahr=2015&class=ç&date_format=d.m.Y&iso=DE

Reply in JSON / UTF-8:

{
	"interface": "fcal API 2.0",
	"source": {
		"href": "https://feiertagskalender.ch",
		"description": "feiertagskalender.ch"
	},
	"copyright": {
		"href": "https://psc.ch",
		"description": "psc Peter Schuetz Informatik-Dienstleistungen, CH Bern"
	},
	"apiName": "Data/Country",
	"apiStatus": {
		"description": "active"
	},
	"date": "13.03.2019",
	"request": {
		"iso": "DE",
		"year": "2015",
		"class": "4",
		"charset": "utf-8",
		"format": "json",
		"date_format": "d.m.Y",
		"hl": "de"
	},
	"results": {
		"status": {
			"description": "ok"
		},
		"locations": [{
			"description": "Baden-Württemberg",
			"type": "Bundesland",
			"geoId": "3060",
			"iso": "DE",
			"iso-3166-2": "DE-BW",
			"events": [{
				"description": "Neujahr",
				"id": "1",
				"dateStart": "01.01.2015",
				"dateEnd": "01.01.2015",
				"class": "1",
				"percent": "100",
				"prov": "0",
				"note": null
			}, {
				"description": "Heilige drei Könige",
				"id": "4",
				"dateStart": "06.01.2015",
				"dateEnd": "06.01.2015",
				"class": "1",
				"percent": "100",
				"prov": "0",
				"note": null
			}, {
				"description": "Karfreitag",
				"id": "17",
				"dateStart": "03.04.2015",
				"dateEnd": "03.04.2015",
				"class": "1",
				"percent": "100",
				"prov": "0",
				"note": null
			}, {
				"description": "Ostern",
				"id": "18",
				"dateStart": "05.04.2015",
				"dateEnd": "05.04.2015",
				"class": "4",
				"percent": "100",
				"prov": "0",
				"note": null
			}, {
				"description": "Ostermontag",
				"id": "19",
				"dateStart": "06.04.2015",
				"dateEnd": "06.04.2015",
				"class": "1",
				"percent": "100",
				"prov": "0",
				"note": null
			}, {
				"description": "Tag der Arbeit",
				"id": "22",
				"dateStart": "01.05.2015",
				"dateEnd": "01.05.2015",
				"class": "1",
				"percent": "100",
				"prov": "0",
				"note": null
			}, {
				"description": "Christi Himmelfahrt",
				"id": "31",
				"dateStart": "14.05.2015",
				"dateEnd": "14.05.2015",
				"class": "1",
				"percent": "100",
				"prov": "0",
				"note": null
			}, {
				"description": "Pfingsten",
				"id": "30",
				"dateStart": "24.05.2015",
				"dateEnd": "24.05.2015",
				"class": "4",
				"percent": "100",
				"prov": "0",
				"note": null
			}, {
				"description": "Pfingstmontag",
				"id": "35",
				"dateStart": "25.05.2015",
				"dateEnd": "25.05.2015",
				"class": "1",
				"percent": "100",
				"prov": "0",
				"note": null
			}, {
				"description": "Fronleichnam",
				"id": "38",
				"dateStart": "04.06.2015",
				"dateEnd": "04.06.2015",
				"class": "1",
				"percent": "100",
				"prov": "0",
				"note": null
			}, {
				"description": "Tag der Deutschen Einheit",
				"id": "92",
				"dateStart": "03.10.2015",
				"dateEnd": "03.10.2015",
				"class": "1",
				"percent": "100",
				"prov": "0",
				"note": null
			}, {
				"description": "Allerheiligen",
				"id": "47",
				"dateStart": "01.11.2015",
				"dateEnd": "01.11.2015",
				"class": "1",
				"percent": "100",
				"prov": "0",
				"note": null
			}, {
				"description": "Volkstrauertag",
				"id": "216",
				"dateStart": "15.11.2015",
				"dateEnd": "15.11.2015",
				"class": "4",
				"percent": "100",
				"prov": "0",
				"note": null
			}, {
				"description": "Weihnachten",
				"id": "23",
				"dateStart": "25.12.2015",
				"dateEnd": "25.12.2015",
				"class": "1",
				"percent": "100",
				"prov": "0",
				"note": null
			}, {
				"description": "Zweiter Weihnachtsfeiertag",
				"id": "37",
				"dateStart": "26.12.2015",
				"dateEnd": "26.12.2015",
				"class": "1",
				"percent": "100",
				"prov": "0",
				"note": null
			}, {
				"description": "Weihnachtsferien",
				"id": "243767",
				"dateStart": "22.12.2014",
				"dateEnd": "05.01.2015",
				"class": "0",
				"percent": "100",
				"prov": "0",
				"note": null
			}, {
				"description": "Osterferien",
				"id": "243768",
				"dateStart": "30.03.2015",
				"dateEnd": "10.04.2015",
				"class": "0",
				"percent": "100",
				"prov": "0",
				"note": null
			}, {
				"description": "Pfingstferien",
				"id": "243769",
				"dateStart": "26.05.2015",
				"dateEnd": "06.06.2015",
				"class": "0",
				"percent": "100",
				"prov": "0",
				"note": null
			}, {
				"description": "Sommerferien",
				"id": "248076",
				"dateStart": "30.07.2015",
				"dateEnd": "12.09.2015",
				"class": "0",
				"percent": "100",
				"prov": "0",
				"note": null
			}, {
				"description": "Herbstferien",
				"id": "291421",
				"dateStart": "31.10.2015",
				"dateEnd": "06.11.2015",
				"class": "0",
				"percent": "100",
				"prov": "0",
				"note": null
			}, {
				"description": "Weihnachtsferien",
				"id": "291418",
				"dateStart": "23.12.2015",
				"dateEnd": "09.01.2016",
				"class": "0",
				"percent": "100",
				"prov": "0",
				"note": null
			}]
		}, {
			"description": "Bayern",
			"type": "Freistaat",
			"geoId": "3061",
			"iso": "DE",
			"iso-3166-2": "DE-BY",
			"events": [{
			...
			}]
		}]
	}
}

XML

Call:
https://feiertagskalender.ch/api/Data/Country/?api_key=YOUR_API_KEY&jahr=2015&charset=ISO-8859-1&date_format=d.m.Y&format=xml&iso=DE

Reply in XML / ISO-8859-1:

<fcal_api>
	<interface>fcal API 2.0</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/Country</apiName>
	<date>13.03.2019</date>
	<request>
		<iso>DE</iso>
		<year>2015</year>
		<class>4</class>
		<charset>utf-8</charset>
		<format>xml</format>
		<date_format>d.m.Y</date_format>
		<hl>de</hl>
	</request>
	<results>
		<status>
			<description>ok</description>
		</status>
		<locations>
			<location>
				<description>Baden-Württemberg</description>
				<type>Bundesland</type>
				<geoId>3060</geoId>
				<iso>DE</iso>
				<iso-3166-2>DE-BW</iso-3166-2>
				<events>
					<event>
						<description>Neujahr</description>
						<id>1</id>
						<dateStart>01.01.2015</dateStart>
						<dateEnd>01.01.2015</dateEnd>
						<class>1</class>
						<percent>100</percent>
						<prov>0</prov>
						<note></note>
					</event>
					<event>
						<description>Heilige drei Könige</description>
						<id>4</id>
						<dateStart>06.01.2015</dateStart>
						<dateEnd>06.01.2015</dateEnd>
						<class>1</class>
						<percent>100</percent>
						<prov>0</prov>
						<note></note>
					</event>
					<event>
						<description>Karfreitag</description>
						<id>17</id>
						<dateStart>03.04.2015</dateStart>
						<dateEnd>03.04.2015</dateEnd>
						<class>1</class>
						<percent>100</percent>
						<prov>0</prov>
						<note></note>
					</event>
					<event>
						<description>Ostern</description>
						<id>18</id>
						<dateStart>05.04.2015</dateStart>
						<dateEnd>05.04.2015</dateEnd>
						<class>4</class>
						<percent>100</percent>
						<prov>0</prov>
						<note></note>
					</event>
					<event>
						<description>Ostermontag</description>
						<id>19</id>
						<dateStart>06.04.2015</dateStart>
						<dateEnd>06.04.2015</dateEnd>
						<class>1</class>
						<percent>100</percent>
						<prov>0</prov>
						<note></note>
					</event>
					<event>
						<description>Tag der Arbeit</description>
						<id>22</id>
						<dateStart>01.05.2015</dateStart>
						<dateEnd>01.05.2015</dateEnd>
						<class>1</class>
						<percent>100</percent>
						<prov>0</prov>
						<note></note>
					</event>
					<event>
						<description>Christi Himmelfahrt</description>
						<id>31</id>
						<dateStart>14.05.2015</dateStart>
						<dateEnd>14.05.2015</dateEnd>
						<class>1</class>
						<percent>100</percent>
						<prov>0</prov>
						<note></note>
					</event>
					<event>
						<description>Pfingsten</description>
						<id>30</id>
						<dateStart>24.05.2015</dateStart>
						<dateEnd>24.05.2015</dateEnd>
						<class>4</class>
						<percent>100</percent>
						<prov>0</prov>
						<note></note>
					</event>
					<event>
						<description>Pfingstmontag</description>
						<id>35</id>
						<dateStart>25.05.2015</dateStart>
						<dateEnd>25.05.2015</dateEnd>
						<class>1</class>
						<percent>100</percent>
						<prov>0</prov>
						<note></note>
					</event>
					<event>
						<description>Fronleichnam</description>
						<id>38</id>
						<dateStart>04.06.2015</dateStart>
						<dateEnd>04.06.2015</dateEnd>
						<class>1</class>
						<percent>100</percent>
						<prov>0</prov>
						<note></note>
					</event>
					<event>
						<description>Tag der Deutschen Einheit</description>
						<id>92</id>
						<dateStart>03.10.2015</dateStart>
						<dateEnd>03.10.2015</dateEnd>
						<class>1</class>
						<percent>100</percent>
						<prov>0</prov>
						<note></note>
					</event>
					<event>
						<description>Allerheiligen</description>
						<id>47</id>
						<dateStart>01.11.2015</dateStart>
						<dateEnd>01.11.2015</dateEnd>
						<class>1</class>
						<percent>100</percent>
						<prov>0</prov>
						<note></note>
					</event>
					<event>
						<description>Volkstrauertag</description>
						<id>216</id>
						<dateStart>15.11.2015</dateStart>
						<dateEnd>15.11.2015</dateEnd>
						<class>4</class>
						<percent>100</percent>
						<prov>0</prov>
						<note></note>
					</event>
					<event>
						<description>Weihnachten</description>
						<id>23</id>
						<dateStart>25.12.2015</dateStart>
						<dateEnd>25.12.2015</dateEnd>
						<class>1</class>
						<percent>100</percent>
						<prov>0</prov>
						<note></note>
					</event>
					<event>
						<description>Zweiter Weihnachtsfeiertag</description>
						<id>37</id>
						<dateStart>26.12.2015</dateStart>
						<dateEnd>26.12.2015</dateEnd>
						<class>1</class>
						<percent>100</percent>
						<prov>0</prov>
						<note></note>
					</event>
					<event>
						<description>Weihnachtsferien</description>
						<id>243767</id>
						<dateStart>22.12.2014</dateStart>
						<dateEnd>05.01.2015</dateEnd>
						<class>0</class>
						<percent>100</percent>
						<prov>0</prov>
						<note></note>
					</event>
					<event>
						<description>Osterferien</description>
						<id>243768</id>
						<dateStart>30.03.2015</dateStart>
						<dateEnd>10.04.2015</dateEnd>
						<class>0</class>
						<percent>100</percent>
						<prov>0</prov>
						<note></note>
					</event>
					<event>
						<description>Pfingstferien</description>
						<id>243769</id>
						<dateStart>26.05.2015</dateStart>
						<dateEnd>06.06.2015</dateEnd>
						<class>0</class>
						<percent>100</percent>
						<prov>0</prov>
						<note></note>
					</event>
					<event>
						<description>Sommerferien</description>
						<id>248076</id>
						<dateStart>30.07.2015</dateStart>
						<dateEnd>12.09.2015</dateEnd>
						<class>0</class>
						<percent>100</percent>
						<prov>0</prov>
						<note></note>
					</event>
					<event>
						<description>Herbstferien</description>
						<id>291421</id>
						<dateStart>31.10.2015</dateStart>
						<dateEnd>06.11.2015</dateEnd>
						<class>0</class>
						<percent>100</percent>
						<prov>0</prov>
						<note></note>
					</event>
					<event>
						<description>Weihnachtsferien</description>
						<id>291418</id>
						<dateStart>23.12.2015</dateStart>
						<dateEnd>09.01.2016</dateEnd>
						<class>0</class>
						<percent>100</percent>
						<prov>0</prov>
						<note></note>
					</event>
				</events>
			</location>
			<location>
				<description>Bayern</description>
				<type>Freistaat</type>
				<geoId>3061</geoId>
				<iso>DE</iso>
				<iso-3166-2>DE-BY</iso-3166-2>
				<events>				
					...	
				</events>
			</location>
		</locations>
	</results>
</fcal_api>

CSV

Aufruf:
https://feiertagskalender.ch/api/Data/Country/?api_key=YOUR_API_KEY&charset=iso-8859-1&iso=DE&jahr=2015&format=csv

Reply in CSV / ISO-8859-1:

"location";"geoId";"iso";"iso_3166_2";"description";"id";"dateStart";"dateEnd";"class";"percent";"prov";"note"
"Baden-Württemberg";"3060";"DE";"DE-BW";"Neujahr";"1";"01.01.2015";"01.01.2015";"1";"100";"0";""
"Baden-Württemberg";"3060";"DE";"DE-BW";"Heilige drei Könige";"4";"06.01.2015";"06.01.2015";"1";"100";"0";""
"Baden-Württemberg";"3060";"DE";"DE-BW";"Karfreitag";"17";"03.04.2015";"03.04.2015";"1";"100";"0";""
"Baden-Württemberg";"3060";"DE";"DE-BW";"Ostern";"18";"05.04.2015";"05.04.2015";"4";"100";"0";""
"Baden-Württemberg";"3060";"DE";"DE-BW";"Ostermontag";"19";"06.04.2015";"06.04.2015";"1";"100";"0";""
"Baden-Württemberg";"3060";"DE";"DE-BW";"Tag der Arbeit";"22";"01.05.2015";"01.05.2015";"1";"100";"0";""
"Baden-Württemberg";"3060";"DE";"DE-BW";"Christi Himmelfahrt";"31";"14.05.2015";"14.05.2015";"1";"100";"0";""
"Baden-Württemberg";"3060";"DE";"DE-BW";"Pfingsten";"30";"24.05.2015";"24.05.2015";"4";"100";"0";""
"Baden-Württemberg";"3060";"DE";"DE-BW";"Pfingstmontag";"35";"25.05.2015";"25.05.2015";"1";"100";"0";""
"Baden-Württemberg";"3060";"DE";"DE-BW";"Fronleichnam";"38";"04.06.2015";"04.06.2015";"1";"100";"0";""
"Baden-Württemberg";"3060";"DE";"DE-BW";"Tag der Deutschen Einheit";"92";"03.10.2015";"03.10.2015";"1";"100";"0";""
"Baden-Württemberg";"3060";"DE";"DE-BW";"Allerheiligen";"47";"01.11.2015";"01.11.2015";"1";"100";"0";""
"Baden-Württemberg";"3060";"DE";"DE-BW";"Volkstrauertag";"216";"15.11.2015";"15.11.2015";"4";"100";"0";""
"Baden-Württemberg";"3060";"DE";"DE-BW";"Weihnachten";"23";"25.12.2015";"25.12.2015";"1";"100";"0";""
"Baden-Württemberg";"3060";"DE";"DE-BW";"Zweiter Weihnachtsfeiertag";"37";"26.12.2015";"26.12.2015";"1";"100";"0";""
"Baden-Württemberg";"3060";"DE";"DE-BW";"Weihnachtsferien";"243767";"22.12.2014";"05.01.2015";"0";"100";"0";""
"Baden-Württemberg";"3060";"DE";"DE-BW";"Osterferien";"243768";"30.03.2015";"10.04.2015";"0";"100";"0";""
"Baden-Württemberg";"3060";"DE";"DE-BW";"Pfingstferien";"243769";"26.05.2015";"06.06.2015";"0";"100";"0";""
"Baden-Württemberg";"3060";"DE";"DE-BW";"Sommerferien";"248076";"30.07.2015";"12.09.2015";"0";"100";"0";""
"Baden-Württemberg";"3060";"DE";"DE-BW";"Herbstferien";"291421";"31.10.2015";"06.11.2015";"0";"100";"0";""
"Baden-Württemberg";"3060";"DE";"DE-BW";"Weihnachtsferien";"291418";"23.12.2015";"09.01.2016";"0";"100";"0";""
"Bayern";"3061";"DE";"DE-BY";"Neujahr";"1";"01.01.2015";"01.01.2015";"1";"100";"0";""
...

Read annual data of all units of a country using ISO country code

API: Data/Country

URL for requests

Parameters for requests

Return values of the API

Error messages

Examples

JSON

XML

CSV

Folgen Sie uns auf Facebook

Feiertagskalender.ch

Advertisement

Pages

Partner projects