Holidays API

The Holidays API provides holiday information on over 230 countries, regions, and territories around the world. It contains holiday data going back previous years as well as calendars in the future. The data incudes public holidays, different religious dates, bank holidays, and many other categories.

/v1/holidays

HTTP GET

Returns a list of holiday entries for a given country and year. Each entry in the response contains the holiday name, date, day of the week, and the type of holiday.

Parameters

country (required) - country name or ISO 3166-2 country code (preferred).

year (required) - calendar year between 2010 and 2030 (inclusive). Note: not all countries are guarenteed contain data going back to 2010.

type (optional) - holiday type filter. Possible values are:

  • major_holiday - combination of public_holiday, national_holiday, and federal_holiday.
  • public_holiday
  • observance
  • national_holiday
  • federal_holiday (US only)
  • season
  • state_holiday
  • optional_holiday
  • clock_change_daylight_saving_time
  • local_holiday
  • united_nations_observance
  • observance_christian
  • bank_holiday
  • common_local_holiday
  • national_holiday_christian
  • christian
  • observance_hebrew
  • jewish_holiday
  • muslim
  • hindu_holiday
  • restricted_holiday
  • official_holiday
  • national_holiday_orthodox
  • local_observance

Headers

X-Api-Key (required) - API Key associated with your account.

Sample Request URL

Live Demo!

https://api.api-ninjas.com/v1/holidays?country=&year=&type=

Sample Response

[
  {
    "country": "Canada",
    "iso": "CA",
    "year": 2021,
    "date": "2021-04-02",
    "day": "Friday",
    "name": "Good Friday",
    "type": "PUBLIC_HOLIDAY"
  },
  {
    "country": "Canada",
    "iso": "CA",
    "year": 2021,
    "date": "2021-09-06",
    "day": "Monday",
    "name": "Labour Day",
    "type": "PUBLIC_HOLIDAY"
  },
  {
    "country": "Canada",
    "iso": "CA",
    "year": 2021,
    "date": "2021-12-25",
    "day": "Saturday",
    "name": "Christmas Day",
    "type": "PUBLIC_HOLIDAY"
  },
  {
    "country": "Canada",
    "iso": "CA",
    "year": 2021,
    "date": "2021-01-01",
    "day": "Friday",
    "name": "New Year's Day",
    "type": "PUBLIC_HOLIDAY"
  },
  {
    "country": "Canada",
    "iso": "CA",
    "year": 2021,
    "date": "2021-04-05",
    "day": "Monday",
    "name": "Easter Monday",
    "type": "PUBLIC_HOLIDAY"
  },
  {
    "country": "Canada",
    "iso": "CA",
    "year": 2021,
    "date": "2021-05-24",
    "day": "Monday",
    "name": "Victoria Day",
    "type": "PUBLIC_HOLIDAY"
  },
  {
    "country": "Canada",
    "iso": "CA",
    "year": 2021,
    "date": "2021-07-01",
    "day": "Thursday",
    "name": "Canada Day",
    "type": "PUBLIC_HOLIDAY"
  },
  {
    "country": "Canada",
    "iso": "CA",
    "year": 2021,
    "date": "2021-11-11",
    "day": "Thursday",
    "name": "Remembrance Day",
    "type": "PUBLIC_HOLIDAY"
  }
]

import requests
country = 'ca' # Canada.
year = '2022'
api_url = 'https://api.api-ninjas.com/v1/holidays?country={}&year={}'.format(country, year)
response = requests.get(api_url, headers={'X-Api-Key': 'YOUR_API_KEY'})
if response.status_code == requests.codes.ok:
    print(response.text)
else:
    print("Error:", response.status_code, response.text)
var country = 'ca'
var year = '2022'
$.ajax({
    method: 'GET',
    url: url: 'https://api.api-ninjas.com/v1/holidays?country=' + query + '&year=' + year;
    headers: { 'X-Api-Key': 'YOUR_API_KEY'},
    contentType: 'application/json',
    success: function(result) {
        console.log(result);
    },
    error: function ajaxError(jqXHR) {
        console.error('Error: ', jqXHR.responseText);
    }
});
const request = require('request');
var country = 'ca'
var year = '2022'
request.get({
  url: 'https://api.api-ninjas.com/v1/holidays?country=' + query + '&year=' + year;
  headers: {
    'X-Api-Key': 'YOUR_API_KEY'
  },
}, function(error, response, body) {
  if(error) return console.error('Request failed:', error);
  else if(response.statusCode != 200) return console.error('Error:', response.statusCode, body.toString('utf8'));
  else console.log(body)
});
import java.io.InputStream;
import java.net.HttpURLConnection;
import java.net.URL;

import com.fasterxml.jackson.databind.ObjectMapper;

URL url = new URL("https://api.api-ninjas.com/v1/holidays?country=ca&year=2022");
HttpURLConnection connection = (HttpURLConnection) url.openConnection();
connection.setRequestProperty("accept", "application/json");
InputStream responseStream = connection.getInputStream();
ObjectMapper mapper = new ObjectMapper();
JsonNode root = mapper.readTree(responseStream);
System.out.println(root.path("fact").asText());

let url = URL(string: "https://api.api-ninjas.com/v1/holidays?country=ca&year=2022")!
var request = URLRequest(url: url)
request.setValue("YOUR_API_KEY", forHTTPHeaderField: "X-Api-Key")
let task = URLSession.shared.dataTask(with: request) {(data, response, error) in
    guard let data = data else { return }
    print(String(data: data, encoding: .utf8)!)
}
task.resume()
If your programming language is not listed in the Code Example above, you can still make API calls by using a HTTP request library written in your programming language and following the above documentation.