Bank Holidays API

Frequently Asked Questions

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

  Because every entry is of type BANK_HOLIDAY (banking-relevant closures only), the API is well suited for settlement and clearing calendars (ACH, wire, SWIFT), treasury and cash management, trading platforms, international payment scheduling, and loan interest accrual calendars. For non-banking holidays such as public, religious, 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 (a country name or, preferably, an ISO 3166-2 code) and an optional year between 1980 and 2050, which defaults to the current year and is a premium feature. 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), bank_holiday_name (the holiday name when true, otherwise null), the date in YYYY-MM-DD format, and the 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 over 230 countries, regions, and territories, and each array entry includes the name of the bank holiday, its date in YYYY-MM-DD format, the 2-letter ISO 3166 alpha-2 country code, and the year observed. To validate or look up country codes, see the Country API.