Public Holidays API

Frequently Asked Questions

• 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 from 1980 to 2050 for over 100 countries, accepting either a 2-letter ISO country code or a full country name in the country parameter. 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 where the holiday is observed, and a federal flag indicating whether it is a federal holiday. 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 and is a premium-only feature, so see pricing for access. For looking up country codes and names, the Country API can help.