Can I use the Public Holidays API for commercial purposes?

Yes, but you must have a premium subscription. Commercial use of the Public 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 Public 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 Public 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 date range and country coverage does the Public Holidays API support?

The /v1/publicholidays endpoint returns public holiday data for 240+ countries and territories, from 1980 to 2050 for most countries; a year outside a country's range returns a 400 error listing the available years. The country parameter accepts a 2-letter or 3-letter ISO code or an exact English country name, and a country without data returns a 400 error. For non-public, religious, or other special events, use the Holidays API instead.

What is the difference between the /v1/publicholidays and /v1/ispublicholiday endpoints?

The /v1/publicholidays endpoint returns a full list of public holidays for a given country and year , while /v1/ispublicholiday checks whether a single date (in YYYY-MM-DD format) is a public holiday and returns an is_public_holiday boolean plus the public_holiday_name . To count business days that exclude these holidays, see the Working Days API .

What fields are returned for each holiday from the /v1/publicholidays endpoint?

Each object in the JSON array includes name , local_name , date , country , year , a regions list of ISO 3166-2 codes where the holiday applies, a federal flag that is true when the holiday applies nationwide, the holiday's actual_date , an observed flag for days off moved from a weekend, a stable holiday_id and a status of confirmed or tentative . If a request is unsuccessful you will instead receive an error described in the error codes reference.

How do I query public holidays for a past or future year?

Pass the optional year parameter (any calendar year between 1980 and 2050 inclusive) to the /v1/publicholidays endpoint; it defaults to the current year. Free plans can request the current year, and other years need a premium plan, so see pricing for access. For looking up country codes and names, the Country API can help.

Public Holidays API

The Public Holidays API provides the statutory days off for 240+ countries and territories, including regional holidays for states and provinces and the day a holiday is observed when it falls on a weekend. Most countries are covered from 1980 to 2050.

Invalid input returns HTTP 400 with an error message: an unrecognized country, a country without public holiday data, a malformed date, or a year outside the country's range (the error lists the available years).

Available endpoints:

/v1/publicholidays - Get public holidays for a country and year
/v1/ispublicholiday - Check whether a date is a public holiday in a country

For non-public holidays, religious holidays, and other special events, please use the Holidays API instead.

Online

(4.7)

From 5,929 users

2,400+

Applications using this API

API Status

Online - All Systems Operational

API Response Times

Average	P50	P75	P90	P95
308ms	330ms	359ms	615ms	1103ms

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

2 endpoints

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

Returns a list of public holidays for a given country and year.

To look up whether a given date is a public holiday, use the /v1/ispublicholiday endpoint instead.

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. An unrecognized country, or one without public holiday data, returns a 400 error.
year optional Premium only
Calendar year between 1980 and 2050 (inclusive); a few countries cover fewer years. Defaults to the current year. Free plans can omit it or pass the current year; other years require a premium plan.

Headers

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

Response

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

name
Holiday name. When a holiday that falls on a weekend is observed on another day, that day off is a separate row named e.g. Independence Day (observed).
local_name
Local holiday name. This is often (but not always) the same as the name.
date
Date of the day off in YYYY-MM-DD format.
country
2-letter ISO 3166-1 alpha-2 country code.
year
Calendar year of date.
regions
ISO 3166-2 codes of the states, provinces or regions where the holiday applies (e.g. GB-SCT).
federal
true when the holiday applies nationwide. When false, regions lists where it applies.
actual_date
Calendar date of the holiday itself. Differs from date only on observed days.
observed
true when date is an observed or substitute day off for a holiday that falls on another day.
holiday_id
Stable identifier of the holiday, the same every year (e.g. US.independence_day). An observed day shares the id of its holiday.
status
confirmed, or tentative for dates that depend on a lunar sighting or have not yet been officially announced. Tentative dates may move by a day.

Live Demo

Live demo · no API key required

Query parameters

country

year Premium only

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/v1/publicholidays?country=US

Sample response

[

{

"name": "New Year's Day",

"local_name": "New Year's Day",

"date": "2026-01-01",

"country": "US",

"year": 2026,

"regions": [],

"federal": true,

"actual_date": "2026-01-01",

"observed": false,

"holiday_id": "US.new_years_day",

"status": "confirmed"

"...",

{

"name": "Independence Day (observed)",

"local_name": "Independence Day (observed)",

"date": "2026-07-03",

"country": "US",

"year": 2026,

"regions": [],

"federal": true,

"actual_date": "2026-07-04",

"observed": true,

"holiday_id": "US.independence_day",

"status": "confirmed"

"..."

]

Code Examples

curl -X GET "https://api.api-ninjas.com/v1/publicholidays?country=US" \
  -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/ispublicholiday

Returns whether a given date is a nationwide public holiday in a country. Pass subdivision to also count the holidays of one state, province or region.