Can I use the Holidays API for commercial purposes?

Yes, but you must have a premium subscription. Commercial use of the Holidays API is not permitted on the free tier. See our pricing page to choose a plan that fits your needs.

How do I get an API key and start using the Holidays API?

Sign up for a free account to instantly get your API key, then pass it in the X-Api-Key header on every request. The documentation above includes ready-to-run examples in cURL, Python, JavaScript, Node.js, and more.

What happens if I exceed my quota for the month?

Your API requests will simply be denied once you hit your monthly quota — you will never be charged more than the plan you signed up for. To increase your quota, you can upgrade your plan any time on our pricing page .

What happens if a request to the Holidays API fails?

The API responds with a standard HTTP status code and a JSON error message describing the problem. See our error codes reference for the full list of codes and how to resolve each one, or contact support if you need help.

What countries and years does the Holidays API cover?

The Holidays API provides holiday information for over 230 countries and territories worldwide, with the /v2/holidays endpoint supporting any calendar year between 2005 and 2039 . Territories have their own ISO codes, for example Curaçao ( CW ) and Guadeloupe ( GP ). If you only need public holidays across a wider range of years, consider the dedicated Public Holidays API instead.

What is the difference between the /v2/holidays and /v1/isholiday endpoints?

The /v2/holidays endpoint returns a list of all holidays for a given country and year , while /v1/isholiday returns the holidays that fall on a specific date (returning matches across all countries if country is omitted). To simply check whether a date is a business day instead, see the Working Days API .

How do I filter holidays by category, such as bank holidays or religious dates?

Pass the optional type parameter to the /v2/holidays endpoint with a value like PUBLIC_HOLIDAY , BANK_HOLIDAY , CHRISTIAN_HOLIDAY , or OBSERVANCE , among 26 supported categories. The filter is not case-sensitive. PUBLIC_HOLIDAY covers every national day off, including national holidays with a religious origin such as Good Friday in Germany. If you specifically only need bank closures, the Bank Holidays API may be a better fit.

What fields are included in the Holidays API response?

Each holiday object includes country , the iso alpha-2 code, year , the date in YYYY-MM-DD format, the day of the week, the holiday name , and its type ; a failed request returns an error instead. Free plans can request the current year; other years via year , and dates in future years via date , require a premium subscription .

Holidays API

The Holidays API provides holiday information for over 230 countries and territories around the world, from 2005 to 2039. The data includes public holidays, religious dates, bank holidays, and many other categories.

If you are only interested in public holidays over a longer range of years, please use the Public Holidays API instead, which covers 1980 to 2050 for over 100 countries.

Invalid input returns HTTP 400 with an error message: an unrecognized country, a country without data, a malformed date, a year outside the supported range, or an unknown type.

Available endpoints:

/v2/holidays - Get holidays for a given country and year
/v1/isholiday - Check if a specific date is a holiday

Online

(4.2)

From 5,149 users

3,600+

Applications using this API

API Status

Online - All Systems Operational

API Response Times

Average	P50	P75	P90	P95
345ms	392ms	442ms	602ms	1158ms

Didn't find what you were looking for? Suggest an improvement

2 endpoints

https://api.api-ninjas.com/v2/holidays

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
2-letter ISO 3166-1 alpha-2 country code (preferred, e.g. US), 3-letter alpha-3 code (e.g. USA), or English country name (e.g. United States). Not case-sensitive. Names must match exactly; common short names such as UK, USA, UAE and South Korea also work. Territories have their own codes: for example, Curaçao is CW and Sint Maarten is SX, not NL. An unrecognized country returns a 400 error.
year optionalPremium only
Calendar year between 2005 and 2039 (inclusive). Defaults to the current year. Free plans can omit it or pass the current year; other years require a premium plan.

`type` optional

Return only one type of holiday. Not case-sensitive: PUBLIC_HOLIDAY and public_holiday are equivalent, and major_holiday is accepted as an alias of public_holiday. An unknown value returns a 400 error. Possible values:

Type	Description
`PUBLIC_HOLIDAY`	A national day off for the general population. Includes national holidays with a religious origin, such as Good Friday and Christmas Day in Germany.
`STATE_HOLIDAY`	A holiday observed at the state or regional level within a country, applicable to residents of that state but not necessarily the nation as a whole.
`LOCAL_HOLIDAY`	A holiday observed only within a specific city, district, or municipality, with no broader regional or national application.
`PROVINCE_TERRITORY_HOLIDAY`	A holiday specific to a province or territory within a federal state, such as those observed in Canadian provinces or Australian territories.
`DE_FACTO_HOLIDAY`	A day that is widely treated as a holiday in practice (through informal tradition, employer convention, or cultural norm) without a formal legal mandate.
`SUBSTITUTE_HOLIDAY`	A replacement day off granted when an official holiday falls on a weekend or non-working day, or when a holiday is moved to another date.
`BANK_HOLIDAY`	A day on which banks and financial institutions are officially closed. May or may not align with a general public holiday.
`GOVERNMENT_HOLIDAY`	A day off that applies specifically to government employees and public sector workers, which may not extend to the private sector or general population.
`PRIVATE_SECTOR_HOLIDAY`	A day off that applies specifically to private sector employees, which may differ from public sector or general population holidays.
`OPTIONAL_HOLIDAY`	A holiday that individuals or employers may choose to observe, but which carries no universal legal obligation.
`RESTRICTED_TRADING_DAY`	A day on which commercial or retail activity is permitted but subject to legal restrictions, such as limited trading hours. Not a full day off.
`CHRISTIAN_HOLIDAY`	A Western Christian (Catholic or Protestant) religious observance that is not a national day off.
`ORTHODOX_HOLIDAY`	An Eastern Orthodox Christian religious observance that is not a national day off.
`MUSLIM_HOLIDAY`	An Islamic religious observance that is not a national day off.
`JEWISH_HOLIDAY`	A Jewish religious observance that is not a national day off.
`HINDU_HOLIDAY`	A Hindu religious observance that is not a national day off.
`OBSERVANCE`	A recognized day of cultural, civic, or commemorative significance that is not an official day off. A holiday that is suspended or cancelled in a given year is also typed `OBSERVANCE` for that year.
`UNITED_NATIONS_OBSERVANCE`	An observance designated by the United Nations or another international body, recognised globally rather than within a single country or region.
`FLAG_DAY`	A day designated to honour a nation's flag, often marked by ceremonies or displays.
`SILENT_DAY`	A day on which noise, public gatherings, or commercial activity is restricted by law or strong cultural convention, typically for remembrance or mourning.
`HALF_DAY`	A partial holiday on which businesses or institutions close for only part of the day, typically the afternoon.
`WORKING_DAY`	A regular working day that may coincide with a notable calendar event but is not a day off.
`SEASON`	An astronomical event marking the start of a new season: an equinox or solstice.
`CLOCK_CHANGE`	A day on which clocks are adjusted for daylight saving time. Not a day off, but a notable calendar event affecting daily schedules.
`COVID_19_MEASURE`	A non-working day or closure introduced in response to the COVID-19 pandemic, such as a lockdown, work suspension, or emergency public holiday.
`SPORTING_EVENT`	A day designated around a major sporting event, which may result in altered working hours, public gatherings, or unofficial closures.

Headers

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

Response

The /v2/holidays endpoint returns a JSON array of objects, each with the following fields, or an error if the request is unsuccessful.

country
Name of the country or territory.
iso
2-letter ISO 3166-1 alpha-2 code of the country or territory, in upper case.
year
The year for which the holiday is observed.
date
Date of the holiday in YYYY-MM-DD format.
day
Day of the week.
name
Name of the holiday.
type
Type of holiday, in upper case (e.g. PUBLIC_HOLIDAY). See the type parameter for possible values.

Live Demo

Live demo · no API key required

Query parameters

country

year Premium only

type

Get a free API key to get started — no credit card required.

Headers

X-Api-KeyLog in or sign up to get your API key

GET

https://api.api-ninjas.com/v2/holidays?country=CA&type=public_holiday

Sample response

[

{

"country": "Canada",

"iso": "CA",

"year": 2025,

"date": "2025-05-19",

"day": "Monday",

"name": "Victoria Day",

"type": "PUBLIC_HOLIDAY"

{

"country": "Canada",

"iso": "CA",

"year": 2025,

"date": "2025-07-01",

"day": "Tuesday",

"name": "Canada Day",

"type": "PUBLIC_HOLIDAY"

{

"country": "Canada",

"iso": "CA",

"year": 2025,

"date": "2025-09-01",

"day": "Monday",

"name": "Labour Day",

"type": "PUBLIC_HOLIDAY"

"..."

]

Code Examples

curl -X GET "https://api.api-ninjas.com/v2/holidays?country=US&type=public_holiday" \
  -H "X-Api-Key: YOUR_API_KEY"

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.

https://api.api-ninjas.com/v1/isholiday

Returns a list of all holidays that fall on a given date. If no country is specified, holidays from all countries matching the date are returned.