Public Holidays by Country and Stock Market API

What it does

Public Holidays returns the holidays of any supported country or exchange calendar. Get every holiday of a year, find the next holidays after a date, or check whether a single date is a holiday, a weekend day or a business day.

Each holiday has its date, weekday, 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. Official weekend workdays, such as China's swapped working days, count as business days.

GET /v1/holidays/:year/:country lists a year, GET /v1/holidays/upcoming returns the next 1 to 50 holidays within three years, and GET /v1/holidays/check answers for one date. Dates use YYYY-MM-DD and default to today in UTC.

Use it for calendar and scheduling apps, HR and payroll tools, delivery estimates, and any feature that needs to know when people are off work.

▣ 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.

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 Getting Started with APIs: A Beginner’s Guide 2026Sep 17, 2026