API documentation

Function

Enables queries of aggregated annual data by ISO country code or ISO-3166-2 region code.

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, or ISO 3166-2 region code	&iso=DE-BW
year or jahr	Year of the desired data. Available according to contract Without specification: current calendar year (= default)	&year= 2026
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 (= 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. 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 (= default) fr it en	&hl=en
compact	Flag for compact data output. Variants: 0 = Output includes all days of the year, even if no event occurs 1 = Output includes only days, on which school holidays, and/or a public holiday are due (=standard)	&compact=0
filter	Filter setting for events in percent Variants: 0 = the output contains all registered events 5 (= default) = The issue contains only events whose share is > 5%. x = The filtering works with integer numbers up to and including 100%.	&filter=0

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/Aggreg
apiStatus	description			Description of the API status	active
date				Date of data export	01.05.2025
request:	iso			ISO country code, according to request	DE
	year			Year of the data in the output, according to request	2019
	charset			Font encoding of the output, according to request	utf-8
	format			Data format of the output, according to request	json
	date_format			Date format, according to request	d.m.Y
	hl			Language, according to request	de
	compact			Flag for compact data output, according to request	1
	filter			Filter setting for events in percent	0
results	status	description		Output status	ok
	location	description		Name of the geographical unit	Deutschland
		type		Designation of the type of geographical unit	Land
		geoId		Id of the geographical unit (Id by Feiertagskalender.ch)	3059
		iso		ISO country code, 2 digits	DE
		iso-3166-2		Region code according to ISO 3166-2
		calendar		the calendar output
			date	Date of calendar	2019-01-06
			total_population	Number of inhabitants in the selected area	81835000
			public_holiday_population	Number of inhabitants affected by a holiday	25346076
			public_holiday_percent	Percentage of population affected by a holiday	30.97217083155129
			public_holiday_description	Description Public holiday	Heilige drei Könige
			school_holiday_population	Number of inhabitants affected by school holidays	81835000
			school_holiday_percent	Percentage of inhabitants affected by school holidays	100
			school_holiday_description	Description School holidays	Weihnachtsferien
			sum_population	Sum of public_holiday_population and school_holiday_population	81835000
			sum_percent	Sum of public_holiday_percent and school_holiday_percent	100

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 parameter: iso
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/Aggreg/?api_key=YOUR_API_KEY&iso=DE&charset=ISO8859-1

Reply in JSON / ISO8859-1:

{
   "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/Aggreg",
   "apiStatus":{
      "description":"active"
   },
   "date":"2019-04-11",
   "request":{
      "iso":"DE",
      "year":"2019",
      "charset":"iso8859-1",
      "format":"json",
      "date_format":"Y-m-d",
	   "hl":"de",
      "compact":"1",
      "filter":"5"
   },
   "results":{
      "status":{
         "description":"ok"
      },
      "location":{
         "description":"Deutschland",
         "type":"Land",
         "geoId":"3059",
         "iso":"DE",
         "iso-3166-2":"",
         "calendar":[
            {
               "datum":"2019-01-01",
               "total_population":81835000,
               "public_holiday_population":81835000,
               "public_holiday_percent":100,
               "public_holiday_description":"Neujahr",
               "school_holiday_population":81835000,
               "school_holiday_percent":100,
               "school_holiday_description":"Weihnachtsferien",
               "sum_population":81835000,
               "sum_percent":100
            },
            {
               "datum":"2019-01-02",
               "total_population":81835000,
               "public_holiday_population":0,
               "public_holiday_percent":0,
               "public_holiday_description":"",
               "school_holiday_population":81835000,
               "school_holiday_percent":100,
               "school_holiday_description":"Weihnachtsferien",
               "sum_population":81835000,
               "sum_percent":100
            },
            {
               "datum":"2019-01-03",
               "total_population":81835000,
               "public_holiday_population":0,
               "public_holiday_percent":0,
               "public_holiday_description":"",
               "school_holiday_population":81835000,
               "school_holiday_percent":100,
               "school_holiday_description":"Weihnachtsferien",
               "sum_population":81835000,
               "sum_percent":100
            },
            {
               "datum":"2019-01-04",
               "total_population":81835000,
               "public_holiday_population":0,
               "public_holiday_percent":0,
               "public_holiday_description":"",
               "school_holiday_population":81835000,
               "school_holiday_percent":100,
               "school_holiday_description":"Weihnachtsferien",
               "sum_population":81835000,
               "sum_percent":100
            },
            {
               "datum":"2019-01-05",
               "total_population":81835000,
               "public_holiday_population":0,
               "public_holiday_percent":0,
               "public_holiday_description":"",
               "school_holiday_population":81835000,
               "school_holiday_percent":100,
               "school_holiday_description":"Weihnachtsferien",
               "sum_population":81835000,
               "sum_percent":100
            },
            {
               "datum":"2019-01-06",
               "total_population":81835000,
               "public_holiday_population":25346076,
               "public_holiday_percent":30.972170831551292,
               "public_holiday_description":"Heilige drei Könige",
               "school_holiday_population":81835000,
               "school_holiday_percent":100,
               "school_holiday_description":"Weihnachtsferien",
               "sum_population":81835000,
               "sum_percent":100
            },
            {
               "datum":"2019-01-31",
               "total_population":81835000,
               "public_holiday_population":0,
               "public_holiday_percent":0,
               "public_holiday_description":"",
               "school_holiday_population":8528242,
               "school_holiday_percent":10.421264740025661,
               "school_holiday_description":"Semesterferien",
               "sum_population":8528242,
               "sum_percent":10.421264740025661
            },
            {
               "datum":"2019-02-01",
               "total_population":81835000,
               "public_holiday_population":0,
               "public_holiday_percent":0,
               "public_holiday_description":"",
               "school_holiday_population":10358673,
               "school_holiday_percent":12.657998411437649,
               "school_holiday_description":"Semesterferien",
               "sum_population":10358673,
               "sum_percent":12.657998411437649
            },
            {
               "datum":"2019-02-02",
               "total_population":81835000,
               "public_holiday_population":0,
               "public_holiday_percent":0,
               "public_holiday_description":"",
               "school_holiday_population":18064053,
               "school_holiday_percent":22.073749618134052,
               "school_holiday_description":"Winterferien",
               "sum_population":18064053,
               "sum_percent":22.073749618134052
            },
            {
               "datum":"2019-02-03",
               "total_population":81835000,
               "public_holiday_population":0,
               "public_holiday_percent":0,
               "public_holiday_description":"",
               "school_holiday_population":18064053,
               "school_holiday_percent":22.073749618134052,
               "school_holiday_description":"Winterferien",
               "sum_population":18064053,
               "sum_percent":22.073749618134052
            },
            {
               "datum":"2019-02-04",
               "total_population":81835000,
               "public_holiday_population":0,
               "public_holiday_percent":0,
               "public_holiday_description":"",
               "school_holiday_population":7705380,
               "school_holiday_percent":9.4157512066964024,
               "school_holiday_description":"Winterferien",
               "sum_population":7705380,
               "sum_percent":9.4157512066964024
            },
            {
               "datum":"2019-02-05",
               "total_population":81835000,
               "public_holiday_population":0,
               "public_holiday_percent":0,
               "public_holiday_description":"",
               "school_holiday_population":7705380,
               "school_holiday_percent":9.4157512066964024,
               "school_holiday_description":"Winterferien",
               "sum_population":7705380,
               "sum_percent":9.4157512066964024
            },
            {
               "datum":"2019-02-06",
               "total_population":81835000,
               "public_holiday_population":0,
               "public_holiday_percent":0,
               "public_holiday_description":"",
               "school_holiday_population":7705380,
               "school_holiday_percent":9.4157512066964024,
               "school_holiday_description":"Winterferien",
               "sum_population":7705380,
               "sum_percent":9.4157512066964024
            },
            {
               "datum":"2019-02-07",
               "total_population":81835000,
               "public_holiday_population":0,
               "public_holiday_percent":0,
               "public_holiday_description":"",
               "school_holiday_population":7705380,
               "school_holiday_percent":9.4157512066964024,
               "school_holiday_description":"Winterferien",
               "sum_population":7705380,
               "sum_percent":9.4157512066964024
            },
            {
               "datum":"2019-02-08",
               "total_population":81835000,
               "public_holiday_population":0,
               "public_holiday_percent":0,
               "public_holiday_description":"",
               "school_holiday_population":7705380,
               "school_holiday_percent":9.4157512066964024,
               "school_holiday_description":"Winterferien",
               "sum_population":7705380,
               "sum_percent":9.4157512066964024
            },
            {
               "datum":"2019-02-09",
               "total_population":81835000,
               "public_holiday_population":0,
               "public_holiday_percent":0,
               "public_holiday_description":"",
               "school_holiday_population":12099760,
               "school_holiday_percent":14.785556302315635,
               "school_holiday_description":"Winterferien",
               "sum_population":12099760,
               "sum_percent":14.785556302315635
            },
            {
               "datum":"2019-02-10",
               "total_population":81835000,
               "public_holiday_population":0,
               "public_holiday_percent":0,
               "public_holiday_description":"",
               "school_holiday_population":12099760,
               "school_holiday_percent":14.785556302315635,
               "school_holiday_description":"Winterferien",
               "sum_population":12099760,
               "sum_percent":14.785556302315635
            },
            ...
         ]
      }
   }
}

XML

Call:
https://feiertagskalender.ch/api/Data/Aggreg/?api_key=YOUR_API_KEY&iso=DE&charset=ISO8859-1&format=xml

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/Aggreg</apiName>
	<date>2019-04-11</date>
	<request>
		<iso>DE</iso>
		<year>2019</year>
		<charset>iso8859-1</charset>
		<format>xml</format>
		<date_format>Y-m-d</date_format>
		<hl>de</hl>
		<compact>1</compact>
		<filter>5</filter>
	</request>
	<results>
		<status>
			<description>ok</description>
		</status>
		<location>
			<description>Deutschland</description>
			<type>Land</type>
			<geoId>3059</geoId>
			<iso>DE</iso>
			<iso-3166-2/>
			<events>
				<day>
					<datum>2019-01-01</datum>
					<total_population>81835000</total_population>
					<public_holiday_population>81835000</public_holiday_population>
					<public_holiday_percent>100</public_holiday_percent>
					<public_holiday_description>Neujahr</public_holiday_description>
					<school_holiday_population>81835000</school_holiday_population>
					<school_holiday_percent>100</school_holiday_percent>
					<school_holiday_description>Weihnachtsferien</school_holiday_description>
					<sum_population>81835000</sum_population>
					<sum_percent>100</sum_percent>
				</day>
				<day>
					<datum>2019-01-02</datum>
					<total_population>81835000</total_population>
					<public_holiday_population>0</public_holiday_population>
					<public_holiday_percent>0</public_holiday_percent>
					<public_holiday_description/>
					<school_holiday_population>81835000</school_holiday_population>
					<school_holiday_percent>100</school_holiday_percent>
					<school_holiday_description>Weihnachtsferien</school_holiday_description>
					<sum_population>81835000</sum_population>
					<sum_percent>100</sum_percent>
				</day>
				<day>
					<datum>2019-01-03</datum>
					<total_population>81835000</total_population>
					<public_holiday_population>0</public_holiday_population>
					<public_holiday_percent>0</public_holiday_percent>
					<public_holiday_description/>
					<school_holiday_population>81835000</school_holiday_population>
					<school_holiday_percent>100</school_holiday_percent>
					<school_holiday_description>Weihnachtsferien</school_holiday_description>
					<sum_population>81835000</sum_population>
					<sum_percent>100</sum_percent>
				</day>
				<day>
					<datum>2019-01-04</datum>
					<total_population>81835000</total_population>
					<public_holiday_population>0</public_holiday_population>
					<public_holiday_percent>0</public_holiday_percent>
					<public_holiday_description/>
					<school_holiday_population>81835000</school_holiday_population>
					<school_holiday_percent>100</school_holiday_percent>
					<school_holiday_description>Weihnachtsferien</school_holiday_description>
					<sum_population>81835000</sum_population>
					<sum_percent>100</sum_percent>
				</day>
				<day>
					<datum>2019-01-05</datum>
					<total_population>81835000</total_population>
					<public_holiday_population>0</public_holiday_population>
					<public_holiday_percent>0</public_holiday_percent>
					<public_holiday_description/>
					<school_holiday_population>81835000</school_holiday_population>
					<school_holiday_percent>100</school_holiday_percent>
					<school_holiday_description>Weihnachtsferien</school_holiday_description>
					<sum_population>81835000</sum_population>
					<sum_percent>100</sum_percent>
				</day>
				<day>
					<datum>2019-01-06</datum>
					<total_population>81835000</total_population>
					<public_holiday_population>25346076</public_holiday_population>
					<public_holiday_percent>30.972170831551</public_holiday_percent>
					<public_holiday_description>Heilige drei Könige</public_holiday_description>
					<school_holiday_population>81835000</school_holiday_population>
					<school_holiday_percent>100</school_holiday_percent>
					<school_holiday_description>Weihnachtsferien</school_holiday_description>
					<sum_population>81835000</sum_population>
					<sum_percent>100</sum_percent>
				</day>
				<day>
					<datum>2019-01-31</datum>
					<total_population>81835000</total_population>
					<public_holiday_population>0</public_holiday_population>
					<public_holiday_percent>0</public_holiday_percent>
					<public_holiday_description/>
					<school_holiday_population>8528242</school_holiday_population>
					<school_holiday_percent>10.421264740026</school_holiday_percent>
					<school_holiday_description>Semesterferien</school_holiday_description>
					<sum_population>8528242</sum_population>
					<sum_percent>10.421264740026</sum_percent>
				</day>
				<day>
					<datum>2019-02-01</datum>
					<total_population>81835000</total_population>
					<public_holiday_population>0</public_holiday_population>
					<public_holiday_percent>0</public_holiday_percent>
					<public_holiday_description/>
					<school_holiday_population>10358673</school_holiday_population>
					<school_holiday_percent>12.657998411438</school_holiday_percent>
					<school_holiday_description>Semesterferien</school_holiday_description>
					<sum_population>10358673</sum_population>
					<sum_percent>12.657998411438</sum_percent>
				</day>
				...
			</events>
		</location>
	</results>
</fcal_api>

CSV

Call:
https://feiertagskalender.ch/api/Data/Aggreg/?api_key=YOUR_API_KEY&iso=DE&format=csv

Reply in CSV / UTF-8:

"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"
"Deutschland";"3059";"DE";"";"2019-01-01";"81835000";"81835000";"100";"Neujahr";"81835000";"100";"Weihnachtsferien";"81835000";"100"
"Deutschland";"3059";"DE";"";"2019-01-02";"81835000";"0";"0";"";"81835000";"100";"Weihnachtsferien";"81835000";"100"
"Deutschland";"3059";"DE";"";"2019-01-03";"81835000";"0";"0";"";"81835000";"100";"Weihnachtsferien";"81835000";"100"
"Deutschland";"3059";"DE";"";"2019-01-04";"81835000";"0";"0";"";"81835000";"100";"Weihnachtsferien";"81835000";"100"
"Deutschland";"3059";"DE";"";"2019-01-05";"81835000";"0";"0";"";"81835000";"100";"Weihnachtsferien";"81835000";"100"
"Deutschland";"3059";"DE";"";"2019-01-06";"81835000";"25346076";"30.972170831551";"Heilige drei Könige";"81835000";"100";"Weihnachtsferien";"81835000";"100"
"Deutschland";"3059";"DE";"";"2019-01-31";"81835000";"0";"0";"";"8528242";"10.421264740026";"Semesterferien";"8528242";"10.421264740026"
"Deutschland";"3059";"DE";"";"2019-02-01";"81835000";"0";"0";"";"10358673";"12.657998411438";"Semesterferien";"10358673";"12.657998411438"
"Deutschland";"3059";"DE";"";"2019-02-02";"81835000";"0";"0";"";"18064053";"22.073749618134";"Winterferien";"18064053";"22.073749618134"
"Deutschland";"3059";"DE";"";"2019-02-03";"81835000";"0";"0";"";"18064053";"22.073749618134";"Winterferien";"18064053";"22.073749618134"
"Deutschland";"3059";"DE";"";"2019-02-04";"81835000";"0";"0";"";"7705380";"9.4157512066964";"Winterferien";"7705380";"9.4157512066964"
"Deutschland";"3059";"DE";"";"2019-02-05";"81835000";"0";"0";"";"7705380";"9.4157512066964";"Winterferien";"7705380";"9.4157512066964"
"Deutschland";"3059";"DE";"";"2019-02-06";"81835000";"0";"0";"";"7705380";"9.4157512066964";"Winterferien";"7705380";"9.4157512066964"
"Deutschland";"3059";"DE";"";"2019-02-07";"81835000";"0";"0";"";"7705380";"9.4157512066964";"Winterferien";"7705380";"9.4157512066964"
"Deutschland";"3059";"DE";"";"2019-02-08";"81835000";"0";"0";"";"7705380";"9.4157512066964";"Winterferien";"7705380";"9.4157512066964"
"Deutschland";"3059";"DE";"";"2019-02-09";"81835000";"0";"0";"";"12099760";"14.785556302316";"Winterferien";"12099760";"14.785556302316"
"Deutschland";"3059";"DE";"";"2019-02-10";"81835000";"0";"0";"";"12099760";"14.785556302316";"Winterferien";"12099760";"14.785556302316"
"Deutschland";"3059";"DE";"";"2019-02-11";"81835000";"0";"0";"";"6003981";"7.3366909024256";"Winterferien";"6003981";"7.3366909024256"
"Deutschland";"3059";"DE";"";"2019-02-12";"81835000";"0";"0";"";"6003981";"7.3366909024256";"Winterferien";"6003981";"7.3366909024256"
"Deutschland";"3059";"DE";"";"2019-02-13";"81835000";"0";"0";"";"6003981";"7.3366909024256";"Winterferien";"6003981";"7.3366909024256"
"Deutschland";"3059";"DE";"";"2019-02-14";"81835000";"81835000";"100";"Valentinstag";"6003981";"7.3366909024256";"Winterferien";"81835000";"100"
...

Read aggregated annual data using ISO country code

API: Data/Aggreg

URL for requests

Parameters for requests

Return values of the API

Error messages

Examples

Examples

JSON

XML

CSV

Folgen Sie uns auf Facebook

Feiertagskalender.ch

Advertisement

Pages

Partner projects