▣ VERIFICATION KIT

Public Holidays by Country and Stock Market API

What it does

The Public Holidays API returns the holidays of a country or stock exchange calendar. List every holiday in a year, get the next holidays after a date, or check whether one date is a holiday, a weekend day or a business day.

To list a year, call GET /v1/holidays/:year/:country with a year from 1900 to 2100 and a country code such as US. For the next holidays, call GET /v1/holidays/upcoming and set count (1 to 50, default 5) and after. Results stay within three years. To check one date, call GET /v1/holidays/check with date and a country or market.

Each holiday includes its date, weekday, English name, local name, categories, and whether an observance rule moved it. Set language for names in another language. Add subdivision for state, province or regional holidays. Use categories to include bank, government, optional or religious days. Use observed to switch observed dates on or off. Official weekend workdays, such as China's swapped working days, count as business days. Dates use YYYY-MM-DD and default to today in UTC.

Teams use the Public Holidays API in calendar and scheduling apps, HR and payroll tools, delivery estimates, and any feature that needs to know when people are off work.

To move dates by working days, use the Calculate Business Days Across Countries and Markets API. For exchange closures, use the Stock Exchange Calendars API.

▣ ENDPOINT 01 / 03

GET

List Holidays by Country and Year

https://api.eu.apyhub.com/callable-labs/public-holidays-country-stock-market/v1/holidays/:year/:country

QUICKSTART

GUIDE

Quickstart

List the public holidays of the United States in 2026.

curl -X GET "https://api.eu.apyhub.com/callable-labs/public-holidays-country-stock-market/v1/holidays/:year/:country" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with the year, the count of holidays and a holidays array sorted by date. Each holiday has its date, weekday, name, local_name, categories and an observed flag that is true when an observance rule moved the day off. Only the first holidays are shown here.

{
  "year": 2026,
  "count": 11,
  "country": "US",
  "subdivision": null,
  "categories": ["public"],
  "language": "en",
  "calendar_version": "2026.10",
  "holidays": [
    {
      "date": "2026-01-01",
      "weekday": "thursday",
      "name": "New Year's Day",
      "local_name": "New Year's Day",
      "categories": ["public"],
      "observed": false
    },
    {
      "date": "2026-01-19",
      "weekday": "monday",
      "name": "Martin Luther King Jr. Day",
      "local_name": "Martin Luther King Jr. Day",
      "categories": ["public"],
      "observed": false
    }
  ]
}

TRY ITLIVE · 5 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Returns every holiday of a country in a given year, sorted by date. Each holiday has its name in English (or the language you ask for), the local name, its categories and whether an observance rule moved it. Add subdivision for state, province or region holidays, and categories for bank, government, optional or religious days.

Path Parameter(s)

Attribute	Type	Description
year	Integer	Year, 1900 to 2100. Required.
country	String	ISO 3166-1 alpha-2 or alpha-3 country code, such as `US` or `DEU`. Required.

Query Parameter(s)

Attribute	Type	Description
subdivision	String	State, province or region code or name, such as `CA`, `BY` or `Bayern`.
categories	String	Comma-separated holiday categories, such as `public,bank`. Default: the calendar's main category (usually `public`).
language	String	Language for the holiday names, such as `en_US`, `de` or `fr`. Default: English when available.
observed	Boolean	Include days off moved by observance rules, for example a Sunday holiday observed on Monday. Default: `true`.

Response

Returns a JSON object with the holidays of the year.

Parameter	Type	Description
year	Integer	Year requested.
count	Integer	Number of holidays returned.
holidays	Object Array	The holidays, sorted by date.
holidays[].date	String	Date of the holiday (`YYYY-MM-DD`).
holidays[].weekday	String	Day of the week.
holidays[].name	String	Holiday name in English or the requested language.
holidays[].local_name	String	Holiday name in the local language.
holidays[].categories	String Array	Categories of the holiday.
holidays[].observed	Boolean	Whether an observance rule moved the day off.
country	String	Country code of the calendar.
subdivision	String	Subdivision used, if any.
categories	String Array	Holiday categories applied.
language	String	Language of the names.
calendar_version	String	Version of the calendar data used.

▣ ENDPOINT 02 / 03

GET

Find Upcoming Holidays

https://api.eu.apyhub.com/callable-labs/public-holidays-country-stock-market/v1/holidays/upcoming

QUICKSTART

GUIDE

Quickstart

Get the next 3 public holidays in the United States.

curl -X GET "https://api.eu.apyhub.com/callable-labs/public-holidays-country-stock-market/v1/holidays/upcoming?country=US&count=3" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with the after date the search started from, the count of holidays and a holidays array in date order. Each holiday has its date, weekday, name, local_name, categories and observed flag. Dates default to today in UTC.

{
  "after": "2026-10-15",
  "count": 3,
  "country": "US",
  "market": null,
  "categories": ["public"],
  "language": "en",
  "calendar_version": "2026.10",
  "holidays": [
    {
      "date": "2026-11-11",
      "weekday": "wednesday",
      "name": "Veterans Day",
      "local_name": "Veterans Day",
      "categories": ["public"],
      "observed": false
    },
    {
      "date": "2026-11-26",
      "weekday": "thursday",
      "name": "Thanksgiving Day",
      "local_name": "Thanksgiving Day",
      "categories": ["public"],
      "observed": false
    },
    {
      "date": "2026-12-25",
      "weekday": "friday",
      "name": "Christmas Day",
      "local_name": "Christmas Day",
      "categories": ["public"],
      "observed": false
    }
  ]
}

TRY ITLIVE · 5 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Returns the next holidays strictly after a date, looking up to three years ahead. Choose the calendar with country or market.

Query Parameter(s)

Attribute	Type	Description
after	String	Start after this date (`YYYY-MM-DD`). Default: today (UTC).
count	Integer	How many holidays to return, 1 to 50. Default: 5.
country	String	ISO 3166-1 alpha-2 or alpha-3 country code, such as `US` or `DEU`. Give `country` or `market`.
market	String	Exchange MIC or acronym, such as `XNYS` or `NYSE`. Give `country` or `market`.
subdivision	String	State, province or region code or name, such as `CA`, `BY` or `Bayern`.
categories	String	Comma-separated holiday categories, such as `public,bank`. Default: the calendar's main category (usually `public`).
language	String	Language for the holiday names, such as `en_US`, `de` or `fr`. Default: English when available.
observed	Boolean	Include days off moved by observance rules. Default: `true`.

Response

Returns a JSON object with the upcoming holidays in date order.

Parameter	Type	Description
after	String	Holidays are strictly after this date.
count	Integer	Number of holidays returned.
holidays	Object Array	The upcoming holidays.
holidays[].date	String	Date of the holiday (`YYYY-MM-DD`).
holidays[].weekday	String	Day of the week.
holidays[].name	String	Holiday name in English or the requested language.
holidays[].local_name	String	Holiday name in the local language.
holidays[].categories	String Array	Categories of the holiday.
holidays[].observed	Boolean	Whether an observance rule moved the day off.
country	String	Country code of the calendar, or `null`.
market	String	Exchange code of the calendar, or `null`.
calendar_version	String	Version of the calendar data used.

▣ ENDPOINT 03 / 03

GET

Check If a Date Is a Holiday or Business Day

https://api.eu.apyhub.com/callable-labs/public-holidays-country-stock-market/v1/holidays/check

QUICKSTART

GUIDE

Quickstart

Check whether 25 December 2026 is a holiday, a weekend day or a business day in the United States.

curl -X GET "https://api.eu.apyhub.com/callable-labs/public-holidays-country-stock-market/v1/holidays/check?date=2026-12-25&country=US" \
  -H "apy-token: $APY_TOKEN"

What you'll get back

Returns a JSON object with the date, its weekday, and three booleans: is_holiday, is_weekend and is_business_day. holidays lists the holidays that fall on that date.

{
  "date": "2026-12-25",
  "weekday": "friday",
  "is_holiday": true,
  "is_weekend": false,
  "is_business_day": false,
  "country": "US",
  "market": null,
  "subdivision": null,
  "categories": ["public"],
  "language": "en",
  "calendar_version": "2026.10",
  "holidays": [
    {
      "date": "2026-12-25",
      "weekday": "friday",
      "name": "Christmas Day",
      "local_name": "Christmas Day",
      "categories": ["public"],
      "observed": false
    }
  ]
}

TRY ITLIVE · 5 ATOMS

API key

Loading your default key…

The full key is used to call the gateway and stays in this tab — never sent to orbit or saved.

About this endpoint

What it does

Tells you whether a date is a holiday, a weekend day and a business day in one calendar, and lists the holidays that fall on it. Official weekend workdays, such as China's swapped working days, count as business days.

Query Parameter(s)

Attribute	Type	Description
date	String	Date to check (`YYYY-MM-DD`). Default: today (UTC).
country	String	ISO 3166-1 alpha-2 or alpha-3 country code, such as `US` or `DEU`. Give `country` or `market`.
market	String	Exchange MIC or acronym, such as `XNYS` or `NYSE`. Give `country` or `market`.
subdivision	String	State, province or region code or name, such as `CA`, `BY` or `Bayern`.
categories	String	Comma-separated holiday categories, such as `public,bank`. Default: the calendar's main category (usually `public`).
language	String	Language for the holiday names, such as `en_US`, `de` or `fr`. Default: English when available.
weekend	String	Override the weekend with weekday names or abbreviations, such as `sat,sun` or `fri,sat`, or `none`. Default: the calendar's own weekend.

Response

Returns a JSON object with the result for the date.

Parameter	Type	Description
date	String	The date checked.
weekday	String	Day of the week.
is_holiday	Boolean	Whether the date is a holiday.
is_weekend	Boolean	Whether the date is a weekend day.
is_business_day	Boolean	Whether the date is a business day.
holidays	Object Array	Holidays that fall on the date, with their name, local name, categories and observed flag.
country	String	Country code of the calendar, or `null`.
market	String	Exchange code of the calendar, or `null`.
subdivision	String	Subdivision used, if any.
categories	String Array	Holiday categories applied.
language	String	Language of the holiday names.
calendar_version	String	Version of the calendar data used.

▣ COMMON ERRORS

Errors any endpoint can return

400bad_request

Required parameter missing or malformed body.

401unauthorized

API key missing, revoked, or not authorized for this service.

429rate_limited

Your plan's per-second rate exceeded. Retry with exponential backoff.

503upstream_busy

Backend temporarily unavailable. Try again in a few seconds.

Similar APIs

Closest matches in the catalog based on this service.

CALLPublic Holidays APIApyHub CALLRetrieve Public Holidays by Country and YearCallable Labs CALLCalculate Business Days Across Countries and MarketsCallable Labs CALLBusiness Days Calculator APInick creighton

From the blog

Reads that touch this API.

Business Day Calculator in Python: Add Working Days with Holidays and ClosuresOct 25, 2026 What Is a Business Day? How to Calculate Business Days in CodeSep 18, 2026 How Many Working Days Are in 2027? By Country and MonthSep 18, 2026 Timezones Dictionary API: Global Timezone Data and Best Alternatives for 2026Jul 9, 2026