POST AI agent ready /v1/holidays/list

Public Holidays API - Holiday List by Country & Year

Returns all public holidays for a specified country and year. Each holiday includes the date, English name, local name, and types (Public, Bank, National, etc.). Supports 100+ countries with ISO 3166-1 alpha-2 country codes.

Endpoint

Code examples

curl -X POST https://api.botoi.com/v1/holidays/list \
  -H "Content-Type: application/json" \
  -d '{"country":"US","year":2026}'

When to use this API

Delivery date estimation

When calculating estimated delivery dates for an e-commerce order, exclude public holidays from the count of business days. Fetch the holiday list for the destination country and skip those dates in your date arithmetic.

Employee scheduling and payroll

Automatically flag public holidays in your scheduling system. Calculate holiday pay rates, prevent managers from scheduling shifts that overlap with statutory holidays, and generate accurate payroll reports.

Calendar integrations

Pre-populate calendar apps with public holidays for the user's country. Display holidays alongside personal events and work meetings so users can plan around days off without manually adding each holiday.

Frequently asked questions

How many countries are supported?

Over 100 countries are supported using ISO 3166-1 alpha-2 codes. Major countries like US, GB, DE, FR, JP, BR, IN, AU, and CA all have full holiday coverage.

Are regional or state holidays included?

The response focuses on national public holidays. Regional or state-specific holidays (like US state holidays) are not included in the default list.

What does the types array contain?

The types array classifies each holiday. Common values include "Public" (government-recognized day off), "Bank" (bank holiday), "National" (national observance), and "Optional" (optional or observance-only). A holiday can have multiple types.

Can I query holidays for past years?

Yes. You can query holidays for any year from 2000 to 2100. Historical data is useful for auditing past payroll calculations or verifying business day counts in prior periods.

What happens if I omit the year parameter?

The endpoint defaults to the current calendar year. If you need holidays for the next year (e.g., for planning), pass the year explicitly.

Get your API key

Free tier includes 5 requests per minute with no credit card required. Upgrade for higher limits.