▣ VERIFICATION KIT

Retrieve Public Holidays by Country and Year

What it does

The Country Holidays API returns the public holidays of a country for one year, plus reference data for every supported calendar. It covers 250 countries and territories, for years 1900 to 2100.

Call GET /v1/holidays/:year/:country, for example GET /v1/holidays/2026/US. Use ISO 3166-1 alpha-2 or alpha-3 codes, such as US, DE or DEU. The response has the country, year, a count and a holidays array. Each holiday includes its date, weekday, name, local name, categories, and whether it is an observed day.

Add subdivision for a state, province or regional calendar. Use categories to choose holiday types, language for names in another language, and observed to switch observed dates on or off.

Call GET /v1/countries to list every supported calendar. Call GET /v1/countries/:country to see one country's categories, languages, weekend days, years covered and subdivision codes. Use it to pick valid inputs before you request holidays. Coverage and options vary by calendar, so check exceptional dates against official announcements.

Teams use the Country Holidays API to fill holiday calendars in HR and leave tools, block holidays in booking apps, and show regional holidays for each office.

To find the next holidays or check a single date, use the Public Holidays by Country and Stock Market API. To count working days, use the Calculate Business Days Across Countries and Markets API.

▣ ENDPOINT 01 / 03

GET

List Supported Countries

https://api.eu.apyhub.com/callable-labs/retrieve-public-holidays-by-country-and-year-api/v1/countries

QUICKSTART

GUIDE

Quickstart

Fetch the holiday calendar catalog with a simple GET request.

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

What you'll get back

Returns a JSON object with count as an integer, calendar_version as a string, and items as an array of calendar objects.

Each item includes code, aliases, name, kind, categories, default_category, languages, default_language, weekend, subdivision_count, and years.

{
  "count": 250,
  "calendar_version": "0.106",
  "items": [
    {
      "code": "DE",
      "aliases": ["DEU"],
      "name": "Germany",
      "kind": "country",
      "categories": ["public"],
      "default_category": "public",
      "languages": ["de", "en_US"],
      "default_language": "de",
      "weekend": ["saturday", "sunday"],
      "subdivision_count": 17,
      "years": [1990, 2100]
    }
  ]
}

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 a catalog of available holiday calendars as a JSON object, including the total count, the calendar version, and an array of country/market entries.

Response

Returns a JSON object with three top-level fields: count is an integer, items is an array of calendar records, and calendar_version is a string. The response body is the CalendarCatalog object.

Parameter	Type	Mandatory	Description
count	Integer	Yes	Total number of catalog entries.
items	Object Array	Yes	List of calendar records. Each item is a `CalendarInfo` object with the following fields: `code` (string), `kind` (string; `country` or `market`), `name` (string), `years` (integer array; first and last year with rules), `aliases` (string array; alpha-3 code or the exchange's acronyms), `weekend` (string array), `languages` (string array), `categories` (string array), `default_category` (string), `default_language` (string or null), and `subdivision_count` (integer).
calendar_version	String	Yes	Calendar data version string.

▣ ENDPOINT 02 / 03

GET

Get Country Calendar Details

https://api.eu.apyhub.com/callable-labs/retrieve-public-holidays-by-country-and-year-api/v1/countries/:country

QUICKSTART

GUIDE

Quickstart

Look up the holiday calendar details for a country code like US.

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

What you'll get back

Returns a JSON object matching the CalendarDetail schema, with required top-level fields like code, name, kind, years, aliases, weekend, languages, categories, default_category, default_language, subdivision_count, and subdivisions.

{
  "code": "DE",
  "aliases": ["DEU"],
  "name": "Germany",
  "kind": "country",
  "categories": ["public"],
  "default_category": "public",
  "languages": ["de", "en_US"],
  "default_language": "de",
  "weekend": ["saturday", "sunday"],
  "subdivision_count": 17,
  "years": [1990, 2100],
  "subdivisions": []
}

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

Retrieves the calendar details for a country or market identified by its ISO code. The response returns the country metadata and calendar-related arrays such as aliases, languages, categories, weekend days, subdivisions, and supported years.

Path Parameter(s)

Attribute	Type	Mandatory	Description
country	String	Yes	ISO 3166-1 alpha-2 or alpha-3 code

Response

Returns a JSON object of type CalendarDetail with required fields for the country or market code, name, kind, aliases, categories, default category and language, weekend days, languages, subdivision count, supported years, and subdivisions.

Parameter	Type	Mandatory	Description
code	String	Yes	Country or market code.
aliases	String Array	Yes	Alpha-3 code, or the exchange's acronyms.
name	String	Yes	Country or market name.
kind	String	Yes	`country` or `market`.
categories	String Array	Yes	Calendar categories associated with the country or market.
default_category	String	Yes	Default calendar category.
languages	String Array	Yes	Languages associated with the country or market.
default_language	String	Yes	Default language, or null.
weekend	String Array	Yes	Weekend days.
subdivision_count	Integer	Yes	Number of subdivisions.
years	Integer Array	Yes	First and last year with rules.
subdivisions	Object Array	Yes	Every subdivision code with its names. Each item includes `code` and `names`.

▣ ENDPOINT 03 / 03

GET

List Country Holidays

https://api.eu.apyhub.com/callable-labs/retrieve-public-holidays-by-country-and-year-api/v1/holidays/:year/:country

QUICKSTART

GUIDE

Quickstart

Get the holiday list for a specific year and country.

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

What you'll get back

Returns a JSON object with categories (array of strings), language (string or null), calendar_version (string), year (integer), count (integer), and holidays (array of holiday objects).

Each holiday object includes date (string, date), weekday (string), name (string), local_name (string), categories (array of strings), and observed (boolean).

{
  "categories": ["public"],
  "language": "en_US",
  "calendar_version": "0.106",
  "year": 2026,
  "count": 13,
  "holidays": [
    {
      "date": "2026-12-25",
      "weekday": "friday",
      "name": "Christmas Day",
      "local_name": "Erster Weihnachtstag",
      "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 holiday calendar for a specific year and country, with optional filtering by language, observed, categories, and subdivision. The response includes the calendar metadata plus a list of holiday objects.

Path Parameter(s)

Attribute	Type	Mandatory	Description
year	Integer	Yes	Year, 1900–2100
country	String	Yes	ISO 3166-1 alpha-2 or alpha-3 code

Query Parameter(s)

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

Response

Returns a JSON object with year as an integer, count as an integer, market as a string or null, country as a string or null, holidays as an array of holiday objects, language as a string or null, categories as an array of strings, subdivision as a string or null, and calendar_version as a string. The response schema requires categories, language, calendar_version, year, count, and holidays.

Attribute	Type	Mandatory	Description
year	Integer	Yes	Year
count	Integer	Yes	Count
market	String	No	ISO 10383 MIC
country	String	No	ISO 3166-1 alpha-2 code
holidays	Object Array	Yes	List of holiday objects. Each item includes `date`, `weekday`, `name`, `local_name`, `categories`, and `observed`.
language	String	Yes	Language of `name`
categories	String Array	Yes	Categories
subdivision	String	No	Subdivision code, when one was asked for
calendar_version	String	Yes	Version of the holiday rules 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 by Country and Stock Market APICallable Labs CALLPublic Holidays APIApyHub CALLCalculate Business Days Across Countries and MarketsCallable Labs CALLBusiness Days Calculator APInick creighton

From the blog

Reads that touch this API.

How Many Working Days Are in 2027? By Country and MonthSep 18, 2026 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 Timezones Dictionary API: Global Timezone Data and Best Alternatives for 2026Jul 9, 2026