NewConnect Claude, Gemini, ChatGPT, and other AI agents to API Ninjas via our MCP server →

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:

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
391ms417ms453ms753ms1294ms

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.

Parameters

  • date  required

    Date in YYYY-MM-DD format (e.g. 2026-12-25). Note: dates in future calendar years are Premium only. Free plans can query past years and the current year.

  • 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.

  • subdivision  optional

    ISO 3166-2 code of a state, province or region (e.g. GB-SCT, or just SCT). Regional bank holidays count only when you pass the region they apply to. An unknown code returns a 400 error.

Headers

  • X-Api-Key  required

    API Key associated with your account.

Response

The /v1/isbankholiday endpoint returns a JSON object with the following fields, or an error if the request is unsuccessful.

  • is_bank_holiday

    Whether banks are closed on the date nationwide, or in subdivision when given.

  • holiday_name

    Name of the bank holiday.

  • date

    The queried date in YYYY-MM-DD format.

  • country

    The resolved 2-letter ISO 3166-1 alpha-2 country code (e.g. GB when you pass UK).

  • subdivision

    The ISO 3166-2 code you passed, normalized (e.g. GB-SCT).

Live Demo

Live demo · no API key required
Query parameters
date
country

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/isbankholiday?date=2026-12-25&country=US
Sample response
{
"date": "2026-12-25",
"country": "US",
"is_bank_holiday": true,
"holiday_name": "Christmas Day"
}

Code Examples

curl -X GET "https://api.api-ninjas.com/v1/isbankholiday?date=2026-12-25&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.

Bank Holidays by Country

Browse bank holidays for the world's most populous countries:

Frequently Asked Questions

  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.

Explore API integration use cases for recommended APIs and workflow examples.