Holidays API: Holidays Service

Request Parameters:

See also the section “General Parameters”.

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-URL	Contains the URL associated with the event. The field is suppressed, if there is no associated URL.
X-TAD-TYPE	List of holiday types associated with this event.
X-TAD-COUNTRY	ISO Code of the country (see ISO3166-1-alpha-2 country code).
X-TAD-STATES	Comma 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:

Example JSON response

{
  "version": 3,
  "billing": {
    "credits": 1
  },
  "holidays": [
    {
      "id": 2006,
      "urlid": "us/new-year-day",
      "url": "https://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": "https://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"
    }
  ]
}
    Expand code

Example XML Request:

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="https://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="https://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>
    Expand code

Example iCalendar Request:

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: https://www.timeanddate.com/holidays/us/new-year-
 day
LOCATION:United States
X-TAD-URL;VALUE=URI:https://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: https://www.timeanddate.com/holidays/us/martin-lu
 ther-king-day
LOCATION:United States
X-TAD-URL;VALUE=URI:https://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
    Expand code

Example Simple CSV Request:

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,,
    Expand code

Example Calendar CSV Request:

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,,
    Expand code