SIGN IN

New users get a free 3 month trial of all services.

Holidays API: Documentation

Get Started with our Holidays API

Get information on holidays and observances around the world – with a few lines of code in your language of choice.

Install Official Libraries

To get started, use one of timeanddate.com's official API libraries for your programming language. If your language isn't supported, you can send the requests manually over HTTP. If you would like to request an official library for your language, please contact us.


    $ dotnet add package TimeAndDate.Services

Build Query

The API library is now installed. Next, you specify the kind of holidays you want to request, the country, and the year. You can find all available countrys in our country overview.

To perform the query, you will need your access key and secret key: Get them from the Access Key page on My Account. Don't have a key? Sign up for our free trial and receive an access key to try it out.


    var country = "no";
    var service = new HolidaysService('accessKey', 'secretKey');
    service.Types = HolidayType.Federal | HolidayType.Weekdays;

Get Result

The result variable will now contain all national, state, and religious holidays for Norway in the year 2020.


    var result = service.GetHolidaysForCountry(country, 2020);

Where to go next?

See our GitHub repository for more information on the C#/.NET Library.


    <repository>
        <id>github</id>
        <name>Time and Date API Packages</name>
        <url>https://maven.pkg.github.com/timeanddate/libtad-jvm</url>
    </repository>
    <dependency>
        <groupId>com.timeanddate</groupId>
        <artifactId>services</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </dependency>

Build Query

The API library is now installed. Next, you specify the kind of holidays you want to request, the country, and the year. You can find all available countrys in our country overview.

To perform the query, you will need your access key and secret key: Get them from the Access Key page on My Account. Don't have a key? Sign up for our free trial and receive an access key to try it out.


    String country = "no";
    HolidaysService service = new HolidaysService('accessKey', 'secretKey');
    service.Types = EnumSet.of(HolidayType.Federal, HolidayType.Weekdays, HolidayType.Religious);

Get Result

The result variable will now contain all national, state, and religious holidays for Norway in the year 2020.


    List<Holiday> result = service.getHolidaysForCountry(country, 2020);

Where to go next?

See our GitHub repository for more information on the Java/JVM Library.


    # Carthage
    github "TimeAndDate/TadApi"
    # CocoaPods
    pod 'libtad-swift', '~> 1.0'

Build Query

The API library is now installed. Next, you specify the kind of holidays you want to request, the country, and the year. You can find all available countrys in our country overview.

To perform the query, you will need your access key and secret key: Get them from the Access Key page on My Account. Don't have a key? Sign up for our free trial and receive an access key to try it out.


    let service = HolidaysService(accessKey: accessKey, secretKey: secretKey)
    let request = HolidaysRequest()
    request.country = "no"
    request.year = 2020
    request.types = [HolidayTypes.federal, HolidayTypes.federallocal, HolidayTypes.religious]

Get Result

The result variable will now contain all national, state, and religious holidays for Norway in the year 2020.


    service.getHolidays(request: request, completionHandler: { (result, error) in
        print(result)
    })

Where to go next?

See our GitHub repository for more information on the Swift Library.

Build Query

You will need cURL installed in order to execute the following commands. The following samples also require you to have enabled "Insecure Methods" on your access key.


    $ ACCESSKEY="<Your Access Key>"
    $ SECRETKEY="<Your Secret Key>"
    $ curl -G \
        --data-urlencode "version=3" \
        --data-urlencode "prettyprint=1" \
        --data-urlencode "accesskey=$ACCESSKEY" \
        --data-urlencode "secretkey=$SECRETKEY" \
        --data-urlencode "country=ro" \
        --data-urlencode "year=2021" \
        --data-urlencode "types=federal,federallocal,religious" \
        https://api.xmltime.com/holidays

Get results

Execute cURL with the parameters set previously and receive the resulting calculation as a JSON object.


{
  "version": 3,
  "billing": {
    "credits": 1
  },
  "holidays": [{
    "id": 1687,
    "urlid": "romania/new-year-day",
    "url": "https://www.timeanddate.com/holidays/romania/new-year-day",
    "country": {
      "id": "ro",
      "name": "Romania"
    },
    "name": [{
      "lang": "en",
      "text": "New Year's Day"
    }],
    "oneliner": [{
      "lang": "en",
      "text": "New Year’s Day (Anul Nou) and the following day, on January 1 and 2 respectively, are annual holidays in Romania."
    }],
    "types": ["National holiday"],
    "subtype": null,
    "date": {
      "iso": "2021-01-01",
      "datetime": {
        "year": 2021,
        "month": 1,
        "day": 1
      }
    },
    "uid": "00069700000007e5"
  },{
       ....