holidays – Retrieve List of Holidays

The holidays service can be used to retrieve the list of holidays for a country.

This service can be tested with the Query Builder.

Note

Some countries (e.g. China and Russia) occasionally declare working days as non-working days to form longer periods of consecutive non-working days. In exchange, weekend days become normal working days. Those days are indicated with the holiday type weekend. Please see also the discussion of the holiday types.

Note

At least request version 2 shall be used for the holiday service. Request version 1 contains a problem for holidays with time stamps (affects e.g. time zone events and seasons): data has no time zone information attached but is output with inconsistent time zone.

Request Parameters. 

NameDescriptionRequired
country

Specify the country for which you would like to retrieve the list of holidays. A states ISO code can also be used when applicable (see a countrys state support on Holidays by Country).

The additional code fun can be used to retrieve fun holidays.

The additional code _all_ can be used to retrieve holidays for all countries. When you use _all_ the cost of the request will be the number of countries returned, instead of 1.

Type: String/ISO3166-1-alpha-2 country code/ISO3166-2 country state code

Yes
year

The year for which the holidays should be retrieved.

Type: Integer

Yes
lang

The preferred language(s) for the texts. An error will be raised if the language code cannot be recognized. In case the text for a specific event cannot be retrieved in any of the requested languages it will be returned in English instead. To query for multiple languages, specify them as comma separated list or repeat the parameter multiple times. In case a requested translation is not available, it will be omitted from the output.

It is possible to query all available languages in a single request by specifying a primary text language, followed by the special value _all_. This value can not be specified as the first language.

In case you have specific needs for a certain language/translation, please email api@timeanddate.com.

Type: String/ISO639 Language Code or _all_

Default value: en

No
types

Holiday types which should be returned. To combine multiple types, either separate them with commas or repeat the parameter with a different value. A negation can be expressed by prefixing the value with a tilde (~) character. Values are combined in the order they are supplied.

When the country parameter is a states ISO code then this parameter must include countrydefault to get valid result since the default value does not include local/state holidays

Type: String/Holiday type

Default value: default (combination of federal, weekday, obs1 and federallocal)

Example: all,~un (return all holidays, but no UN events)

No
readmore

(Only for plain text/iCalendar output) This parameter controls, if the text »Read more« followed by a URL pointing to the timeanddate.com web page is added to the holiday description.

Type: Boolean

Accepted values: 0 or 1

Default value: 1

No
tz

Add time zone information under the date object.

Type: Boolean

Accepted values: 0 or 1

Default value: 1

No
verbosetime

Adds verbose time specification to all ISO 8601 time stamps.

Type: Boolean

Accepted values: 0 or 1

Default value: 1

No
template

Specify the name of a template if you want the result rendered in a specific format (e.g. CSV).

Type: String

Accepted values: ics, csv or xlsx

Default value: None

No
calform

Choose whether the returned data should contain a list of dates in the entire year (full) or just dates which have holidays on them (simple).

Type: String

Accepted values: full and simple

Default value: simple

No
csvstyle

When returning a CSV template you can set this parameter to choose whether the result should be separated by a comma or a semicolon. Only applicable when the template parameter is set to csv.

Type: Number

Accepted values: 1 (comma) or 2 (semicolon)

Default value: 1

No

See also the section called “General Parameters”.

Response Elements. 

NameDescription
holidays

This element will contain a list of all holiday events within the requested year. If service was queried with calform=full it will also contain an element for every day of the year.

Type: Array of HolidayType

Supported Templates. 

In addition to retrieving these text templates via our API, you can also try out and download this data from our Data Download page.

ics

To use this template, specify this parameter combination: out=text&template=ics.

This template is used to retrieve the stream of calendar events in iCalendar [RFC5545] compliant format. By default, the description will include a link to further reading about the holiday. To control this behavior use the readmore parameter. Apart from the standardized data fields, the following x-name fields are used:

X-TAD-URLContains the URL associated with the event. The field is suppressed, if there is no associated URL.
X-TAD-TYPEList of holiday types associated with this event.
X-TAD-COUNTRYISO Code of the country (see ISO3166-1-alpha-2 country code).
X-TAD-STATESComma separated list of states within the country which observe this holiday. Exceptions or additional information will be added to the state separated by a star character (Example: CA*Berkeley – the holiday is only observed in Berkeley, California). The field will be suppressed, if the holiday affects the whole country, or if there is no further information available in the database.
csv

To use this template, specify this parameter combination: out=text&template=csv.

This template is used to retrieve the calendar events in CSV format. By default, the result will contain one line per holiday in the American CSV-format (comma as separator). It is possible to return the CSV in the European CSV-format (semicolon as separator) by including csvstyle=2 in the request. Unless the calform=full parameter is set, the csv template will return one line per holiday. If the calform is set to full the result will contain at least one line per day (more if there is more than one holiday on a day).

xlsx

To use this template, specify this parameter combination: out=blob&template=xlsx.

This template is used to retrieve a binary file of calendar events in an Excel/Office Open XML format. Unless the calform=full parameter is set, the template will return one line per holiday. If the calform is set to full then the result will contain at least one line per day (more if there is more than one holiday per day).

The template returns a binary file with the MIME type set to application/vnd.openxmlformats-officedocument.spreadsheetml.sheet. Ideally, the contents of this binary file would be saved to disk, or served to a user, as an .xlsx file.

Example JSON Request. 

https://api.xmltime.com/holidays?country=us&year=2011&version=3&out=json&prettyprint=1&accesskey={KEY}&expires={TIMESTAMP}&signature={SIGNATURE}

Example JSON response

{
	"version": 3,
	"billing": {
		"credits": 1
	},
	"holidays": [{
		"id": 2006,
		"urlid": "us/new-year-day",
		"url": "http://www.timeanddate.com/holidays/us/new-year-day",
		"country": {
			"id": "us",
			"name": "United States"
		},
		"name": [{
			"lang": "en",
			"text": "New Year's Day"
		}],
		"oneliner": [{
			"lang": "en",
			"text": "New Year's Day is the first day of the Gregorian calendar, which is widely used in many countries such as the USA."
		}],
		"types": ["National holiday"],
		"date": {
			"iso": "2011-01-01",
			"datetime": {
				"year": 2011,
				"month": 1,
				"day": 1
			}
		},
		"uid": "0007d600000007db"
	},{
		"id": 2022,
		"urlid": "us/martin-luther-king-day",
		"url": "http://www.timeanddate.com/holidays/us/martin-luther-king-day",
		"country": {
			"id": "us",
			"name": "United States"
		},
		"name": [{
			"lang": "en",
			"text": "Martin Luther King Jr. Day"
		}],
		"oneliner": [{
			"lang": "en",
			"text": "Martin Luther King Day marks the anniversary of the date of birth of the influential American civil right leader of the same name."
		}],
		"types": ["National holiday"],
		"date": {
			"iso": "2011-01-17",
			"datetime": {
				"year": 2011,
				"month": 1,
				"day": 17
			}
		},
		"uid": "0007e600800007db"
	}]
}

Example XML Request. 

https://api.xmltime.com/holidays?country=us&year=2011&version=3&out=xml&prettyprint=1&accesskey={KEY}&expires={TIMESTAMP}&signature={SIGNATURE}

Example XML response

<?xml version="1.0" encoding="UTF-8"?>
<data version="3">
  <billing>
    <credits>1</credits>
  </billing>
  <holidays>
    <holiday id="2006" urlid="us/new-year-day" url="http://www.timeanddate.com/holidays/us/new-year-day">
      <country id="us">United States</country>
      <name>
        <text lang="en">New Year's Day</text>
      </name>
      <oneliner>
        <text lang="en">New Year's Day is the first day of the Gregorian calendar, which is widely used in many countries such as the USA.</text>
      </oneliner>
      <types>
        <type>National holiday</type>
      </types>
      <date iso="2011-01-01">
        <datetime>
          <year>2011</year>
          <month>1</month>
          <day>1</day>
        </datetime>
      </date>
      <uid>0007d600000007db</uid>
    </holiday>
    <holiday id="2022" urlid="us/martin-luther-king-day" url="http://www.timeanddate.com/holidays/us/martin-luther-king-day">
      <country id="us">United States</country>
      <name>
        <text lang="en">Martin Luther King Jr. Day</text>
      </name>
      <oneliner>
        <text lang="en">Martin Luther King Day marks the anniversary of the date of birth of the influential American civil right leader of the same name.</text>
      </oneliner>
      <types>
        <type>National holiday</type>
      </types>
      <date iso="2011-01-17">
        <datetime>
          <year>2011</year>
          <month>1</month>
          <day>17</day>
        </datetime>
      </date>
      <uid>0007e600800007db</uid>
    </holiday>
  </holidays>
</data>

Example iCalendar Request. 

https://api.xmltime.com/holidays?country=us&year=2011&version=3&out=text&template=ics&accesskey={KEY}&expires={TIMESTAMP}&signature={SIGNATURE}

Example iCalendar [RFC5545] response

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//TIMEANDDATE AS//NONSGML//EN
BEGIN:VEVENT
DTSTAMP:20180109T114548Z
UID:0007d600000007db@timeanddate.com
DTSTART;VALUE=DATE:20110101
DTEND;VALUE=DATE:20110102
SUMMARY:New Year's Day
DESCRIPTION:\n\nRead more: http://www.timeanddate.com/holidays/us/new-year-
 day
LOCATION:United States
X-TAD-URL;VALUE=URI:http://www.timeanddate.com/holidays/us/new-year-day
X-TAD-TYPE;VALUE=TEXT:National holiday
X-TAD-COUNTRY;VALUE=TEXT:us
END:VEVENT
BEGIN:VEVENT
DTSTAMP:20180109T114548Z
UID:0007e600800007db@timeanddate.com
DTSTART;VALUE=DATE:20110117
DTEND;VALUE=DATE:20110118
SUMMARY:Martin Luther King Jr. Day
DESCRIPTION:\n\nRead more: http://www.timeanddate.com/holidays/us/martin-lu
 ther-king-day
LOCATION:United States
X-TAD-URL;VALUE=URI:http://www.timeanddate.com/holidays/us/martin-luther-ki
 ng-day
X-TAD-TYPE;VALUE=TEXT:National holiday
X-TAD-COUNTRY;VALUE=TEXT:us
END:VEVENT
END:VCALENDAR

Example Simple CSV Request. 

https://api.xmltime.com/holidays?country=us&year=2011&version=3&out=text&template=csv&accesskey={KEY}&expires={TIMESTAMP}&signature={SIGNATURE}

Example Simple CSV response

		
Date,Name,Year,Month,Day,Weekday,Types,IsObserved,Country,Locations,States
2011-01-01,"New Year's Day",2011,1,1,Sat,National holiday,,United States,,
2011-01-17,Martin Luther King Jr. Day,2011,1,17,Mon,National holiday,,United States,,
2011-02-14,"Valentine's Day",2011,2,14,Mon,Observance,,United States,,
2011-02-21,"Presidents' Day",2011,2,21,Mon,National holiday,,United States,,
2011-04-24,Easter Sunday,2011,4,24,Sun,"Observance,Christian",,United States,,
2011-05-08,"Mother's Day",2011,5,8,Sun,Observance,,United States,,
2011-05-30,Memorial Day,2011,5,30,Mon,National holiday,,United States,,
2011-06-19,"Father's Day",2011,6,19,Sun,Observance,,United States,,
2011-07-04,Independence Day,2011,7,4,Mon,National holiday,,United States,,
2011-09-05,Labor Day,2011,9,5,Mon,National holiday,,United States,,
2011-10-10,Columbus Day,2011,10,10,Mon,National holiday,,United States,Many regions,"Alabama,Arizona,Colorado,Connecticut,District of Columbia,Georgia,Idaho,Illinois,Indiana,Iowa,Kansas,Kentucky,Louisiana,Maine,Maryland,Massachusetts,Minnesota,Mississippi,Missouri,Montana,Nebraska,New Hampshire,New Jersey,New Mexico,New York,North Carolina,North Dakota,Northern Mariana Islands,Ohio,Oklahoma,Pennsylvania,Rhode Island,South Carolina,Tennessee,Utah,Vermont,Virginia,West Virginia,Wisconsin,Wyoming"
2011-10-31,Halloween,2011,10,31,Mon,Observance,,United States,,
2011-11-11,Veterans Day,2011,11,11,Fri,National holiday,,United States,,
2011-11-24,Thanksgiving Day,2011,11,24,Thu,National holiday,,United States,,
2011-12-24,Christmas Eve,2011,12,24,Sat,"Observance,Christian",,United States,,
2011-12-25,Christmas Day,2011,12,25,Sun,"National holiday,Christian",,United States,,
2011-12-26,Christmas Day,2011,12,26,Mon,"National holiday,Christian",1,United States,,
2011-12-31,"New Year's Eve",2011,12,31,Sat,Observance,,United States,,
		
	

Example Calendar CSV Request. 

https://api.xmltime.com/holidays?country=us&year=2011&version=3&out=text&template=csv&calform=full&accesskey={KEY}&expires={TIMESTAMP}&signature={SIGNATURE}

Example Calendar CSV response

		
Date,Name,Year,Month,Day,Weekday,Types,IsObserved,Country,Locations,States
2011-01-01,"New Year's Day",2011,1,1,Sat,National holiday,,United States,,
2011-01-02,,,,,,,,,,
2011-01-03,,,,,,,,,,
2011-01-04,,,,,,,,,,
2011-01-05,,,,,,,,,,
2011-01-06,,,,,,,,,,
2011-01-07,,,,,,,,,,
2011-01-08,,,,,,,,,,
2011-01-09,,,,,,,,,,
2011-01-10,,,,,,,,,,
2011-01-11,,,,,,,,,,
2011-01-12,,,,,,,,,,
2011-01-13,,,,,,,,,,
2011-01-14,,,,,,,,,,
2011-01-15,,,,,,,,,,
2011-01-16,,,,,,,,,,
2011-01-17,Martin Luther King Jr. Day,2011,1,17,Mon,National holiday,,United States,,
		
	

prev top | next >
Terms & Conditions Copyright © Time and Date AS
All data supplied by timeanddate.com