The Holidays & Business Days API is the easiest way to get public holidays for 200+ countries and their states, check whether a date is a holiday, and do business-day math that skips weekends and holidays.

Please see the official API documentation on RapidAPI for the complete, up-to-date specification, including response formats and pricing plans.

Overview

The Holidays & Business Days API covers public holidays for 200+ countries, plus state and regional holidays where they exist (US states, Canadian provinces, the UK’s nations, German Länder, and more), for any year from 1900 to 2100. It is hosted on RapidAPI, and allows for different calls to be made based on what your needs are.

The API is perfect for the following use cases:

“Are we open today?” checks for stores, support desks, and booking systems
Delivery and shipping estimates (“arrives in 5 business days”)
Payroll, invoicing, and SLA deadlines that must skip holidays
Scheduling tools that avoid booking meetings on public holidays
Reminders and marketing calendars keyed to upcoming holidays

Key Features

Business-Day Math: Add N business days to a date, or count the business days between two dates, with holidays and weekends already accounted for
Holiday Checks: Find out whether any date is a holiday, or get the next upcoming one
Observed Days: When a holiday falls on a weekend and is observed on a Friday or Monday, you get the observed day too, flagged with substitute: true
State-Level Holidays: British Columbia Day, Family Day in Ontario, St Andrew’s Day in Scotland, and the rest
Your Language: Holiday names in English by default, or in another language with lang
Predictable: Dates are always YYYY-MM-DD, and errors are always JSON with a single message

Getting Started

Requests go through RapidAPI, so every call needs your RapidAPI key. Subscribe to the API on RapidAPI to get one, then send it with each request:

curl "https://holidays-business-days-api.p.rapidapi.com/is-holiday?country=US&date=2026-07-03" \
  -H "X-RapidAPI-Key: YOUR_RAPIDAPI_KEY" \
  -H "X-RapidAPI-Host: holidays-business-days-api.p.rapidapi.com"

{
  "holiday": true,
  "date": "2026-07-03",
  "holidays": [
    {
      "date": "2026-07-03",
      "name": "Independence Day (substitute day)",
      "type": "public",
      "substitute": true
    }
  ]
}

Country codes are 2-letter ISO codes (US, GB, DE), state codes come from /states/{country}, and both are case-insensitive. Dates are YYYY-MM-DD.

Every holiday has a type:

public: public holiday; most businesses are closed
bank: banks and offices are closed
optional: many people take the day off
school: schools are closed
observance: commemorated, but not a day off (e.g. Valentine’s Day)

Errors are always JSON with a single message, like { "error": "message" }. A 400 means a parameter is missing or invalid (for example, a year outside 1900–2100, a date that isn’t YYYY-MM-DD, or days out of range), and the message says which. A 404 means the country or state code isn’t supported.

Endpoints

Holidays for a Year

GET /holidays/{country}/{year}

Lists every holiday for a country in a year, in date order. Filter on type if you only want days off.

Example:

GET /holidays/GB/2026

[
  { "date": "2026-01-01", "name": "New Year's Day", "type": "public" },
  { "date": "2026-03-15", "name": "Mother's Day", "type": "observance" },
  { "date": "2026-04-03", "name": "Good Friday", "type": "public" }
]

The first three holidays are shown; the full list runs through December.

Holidays for a State or Region

GET /holidays/{country}/{state}/{year}

The same list, plus that state’s or region’s own holidays.

Example:

GET /holidays/GB/SCT/2026

Check a Date

GET /is-holiday?country={country}&date={date}&state={state}

Checks whether a date is a holiday. state is optional. Returns holiday: false and the date when it isn’t one.

Example:

GET /is-holiday?country=CA&date=2026-07-01

{
  "holiday": true,
  "date": "2026-07-01",
  "holidays": [{ "date": "2026-07-01", "name": "Canada Day", "type": "public" }]
}

Next Holiday

GET /next?country={country}&state={state}

Returns the next holiday after today, where “today” is in the country’s own timezone. state is optional.

Example:

GET /next?country=AU

Add Business Days

GET /business-days/add?country={country}&date={date}&days={days}

Returns the date days business days after date (-1000 to 1000; negative counts backwards). The start date isn’t counted, so days=1 is the next business day.

Example:

GET /business-days/add?country=US&date=2026-12-23&days=5

{ "date": "2026-12-23", "days": 5, "result": "2026-12-31" }

Christmas Day and the weekend are skipped.

Count Business Days

GET /business-days/between?country={country}&start={start}&end={end}

Counts the business days after start up to and including end, at most about 10 years apart. Monday to Friday of the same week is 4.

Example:

GET /business-days/between?country=US&start=2026-01-01&end=2026-12-31

{ "start": "2026-01-01", "end": "2026-12-31", "business_days": 250 }

Countries and States

GET /countries and GET /states/{country}

List the supported country codes, and the state or region codes for a country.

Example:

GET /states/CA

Options

state: Add a state’s or region’s holidays. Works on every holiday and business-day endpoint
lang: 2-letter language code for holiday names (default en), e.g. lang=de for German. Names without a translation come back in the country’s own language
weekend: For the business-day endpoints, the days that are never business days. Defaults to sat,sun; use weekend=fri,sat for countries such as Egypt or Bangladesh

On the business-day endpoints, public and bank holidays (including observed substitute days) are days off; other types are not.

Data Notes

Coverage: 200+ countries, with state or regional holidays where a country has them. Years 1900–2100
Moving holidays such as Easter, Thanksgiving, Chinese New Year, and Eid are calculated for each year. Islamic holidays follow the calculated calendar and can differ by a day from the dates announced locally
Multi-day holidays are listed once, with date as the first day; /is-holiday and the business-day endpoints count every day
Weekends default to Saturday and Sunday for every country; pass weekend when that’s not right for yours
Updates: Holiday rules are updated periodically as governments add or move holidays

Holiday data from the open-source date-holidays project, licensed under CC BY 3.0.

Support

Please contact us with any issues you are having by emailing us at support@moonlabs.app. If there is a feature you’d like us to add, please let us know!