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.

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

Yes
year

The year for which the holidays should be retrieved.

Type: Integer

Yes
lang

The preferred language 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 the requested language it will be returned in English instead. This is also the default language.

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

Type: String/ISO639 Language Code

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.

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

When returning templates with support for calendar-like output, choose whether the returned data should contain a list of dates in the entire year or just dates which have holidays on them. Only applicable when template is set to csv or xlsx

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.

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=2&out=json&prettyprint=1&accesskey={KEY}&expires={TIMESTAMP}&signature={SIGNATURE}

Example JSON response

{
  "version": 2,
  "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": "New Year's Day",
    "oneliner": "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",
  }
}

Example XML Request. 

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

Example XML response

<?xml version="1.0" encoding="UTF-8"?>
<data version="2">
  <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>New Year's Day</name>
      <oneliner>New Year's Day is the first day of the Gregorian calendar, which is widely used in many countries such as the USA.</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>
  </holidays>
</data>

Example iCalendar Request. 

https://api.xmltime.com/holidays?country=us&year=2011&version=2&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:20110822T120649Z
UID:0007d600000007db@timeanddate.com
DTSTART;VALUE=DATE:20110101
DTEND;VALUE=DATE:20110102
SUMMARY:New Year's Day
DESCRIPTION:New Year's Day is the first day of the Gregorian calendar\, whi
 ch is widely used in many countries such as the USA.\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
END:VCALENDAR

Example Simple CSV Request. 

https://api.xmltime.com/holidays?country=us&year=2011&version=2&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 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,,
		
	

Example Calendar CSV Request. 

https://api.xmltime.com/holidays?country=us&year=2011&version=2&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 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