Holidays API

Frequently Asked Questions

• 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, regions, and territories worldwide, with the /v2/holidays endpoint supporting any calendar year between 2005 and 2039 (not all countries have data going back to 2005). 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 more than 25 supported categories. 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. Note that querying historical or future years via the year and date parameters requires a premium subscription.