API documentation

Read aggregated annual data using ISO country code

API: Data/Aggreg

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.

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 (= 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
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 (= standard) = 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 02.05.2024
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

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"
...
Pages
Partner projects
©2003 - 2024 psc Peter Schütz Informatik Dienstleistungen, CH-Bern