Can I use the Bank Holidays API for commercial purposes?

Yes, but you must have a premium subscription. Commercial use of the Bank 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 Bank 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 Bank 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 are some use cases for the Bank Holidays API?

The API lists the days on which banks close in 240+ countries and territories, so it suits payment scheduling, treasury and cash management, trading platforms, and loan interest accrual calendars. Regional holidays carry ISO 3166-2 codes in regions , so you can tell a nationwide closure from a regional one. For non-banking holidays such as religious dates and observances, use the Holidays API instead.

How do I retrieve all bank holidays for a specific country and year?

Call the /v1/bankholidays endpoint with the required country parameter (preferably a 2-letter ISO 3166-1 alpha-2 code, or a 3-letter code or exact English country name) and an optional year between 1980 and 2050 , which defaults to the current year. Free plans can request the current year; other years need a premium plan. To check a single date instead, see the /v1/isbankholiday endpoint, or for non-bank holidays try Public Holidays .

What does the /v1/isbankholiday endpoint return?

It returns a JSON object with is_bank_holiday (true or false), holiday_name (present only when true), the date in YYYY-MM-DD format, and the resolved 2-letter country code, given the required date and country parameters. To find the actual business days around a closure, pair it with the Working Days API .

What does the data cover and which response fields are returned by /v1/bankholidays?

The API covers each country's national banking calendar in 240+ countries and territories, mostly from 1980 to 2050. Each array entry includes the name of the bank holiday, its date in YYYY-MM-DD format, the 2-letter ISO 3166-1 alpha-2 country code, the calendar year , regions (the ISO 3166-2 codes of the regions where it applies, empty when it applies nationwide), and actual_date , observed , holiday_id and status . A country without bank holiday data returns a 400 error. To validate or look up country codes, see the Country API .

Bank Holidays API

The Bank Holidays API returns each country's national banking calendar: the days banks are closed for business, in 240+ countries and territories, mostly from 1980 to 2050. It includes bank-only closures (for example 31 December to 3 January in Japan) and leaves out public holidays on which banks open (for example, Federal Reserve Banks stay open on the Friday before a holiday that falls on a Saturday). Holidays that apply only in some states or regions list them in regions.

Common use cases include:

Payment and transfer scheduling around bank closures
Treasury and cash management systems
Trading and brokerage platforms
International payment scheduling
Loan amortization and interest accrual calendars

Available endpoints:

/v1/bankholidays - Get bank holidays for a given country and year
/v1/isbankholiday - Check if a specific date is a bank holiday

For other holiday categories — public, religious, observances, and more — see the Holidays API.

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

Online

(4.1)

From 2,430 users

2,400+

Applications using this API

API Status

Online - All Systems Operational

API Response Times

Average	P50	P75	P90	P95
391ms	417ms	453ms	753ms	1294ms

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

2 endpoints

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

Returns the bank holidays for a given country and year: nationwide closures and, with their regions, regional ones. When a holiday is observed on another day because it falls on a weekend, that day is a separate entry with observed set to true.

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 bank 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/bankholidays endpoint returns a JSON array of objects, each with the following fields, or an error if the request is unsuccessful.

name
Name of the bank holiday.
date
Date of the bank holiday 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).
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. GB.new_years_day).
status
confirmed, or tentative for dates that depend on a lunar sighting or have not yet been officially announced.

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

Sample response

[

{

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

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

"country": "GB",

"year": 2026,

"regions": [],

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

"observed": false,

"holiday_id": "GB.new_years_day",

"status": "confirmed"

{

"name": "New Year Holiday",

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

"country": "GB",

"year": 2026,

"regions": [

"GB-SCT"

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

"observed": false,

"holiday_id": "GB.new_year_holiday",

"status": "confirmed"

"..."

]

Code Examples

curl -X GET "https://api.api-ninjas.com/v1/bankholidays?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/isbankholiday

Returns whether banks are closed nationwide on a given date in a country. Pass subdivision to also count the bank holidays of one state, province or region.