Retrieve Public Holidays by Country and Year

What it does

Country Holiday Calendars returns public holiday dates for a requested year and country across 250 supported countries and territories.

Use GET /v1/holidays/:year/:country, for example GET /v1/holidays/2026/US, to retrieve the holiday list. The response includes country, year, count and a holidays array. Each holiday includes its date, weekday, name, local name, categories and whether it is an observed day.

Select state, province or regional calendars with subdivision. Optional categories, language and observed filters customize the result. Years 1900–2100 are accepted; coverage and available options vary by calendar.

GET /v1/countries lists supported country calendars. GET /v1/countries/:country provides reference metadata, supported categories, languages, weekend days, year coverage and subdivision codes. These reference endpoints help choose valid inputs; the holidays endpoint returns the actual holiday dates.

Use ISO 3166-1 alpha-2 or alpha-3 country codes, such as US, DE or DEU. Each endpoint costs 5 atoms per call. Validate exceptional dates against official announcements.

▣ 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/2026/DE" \
  -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 APIApyHub CALLBusiness Days Calculator APInick creighton CALLWorking Day Calculator APIApyHub CALLRetrieve World Bank Public Data APIDosvak LLC

From the blog

Reads that touch this API.

How Many Working Days Are in 2027? By Country and MonthSep 18, 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 Ultimate Guide to Country Codes: What They Are and How to Use ThemJul 9, 2026