---
title: Retrieve Public Holidays by Country and Year
slug: retrieve-public-holidays-by-country-and-year-api
url: https://apyhub.com/callable-labs/service/retrieve-public-holidays-by-country-and-year-api
provider: Callable Labs
tags: [countries, holiday-calendars, subdivisions, iso-codes]
auth: api_key
version: v1
service_type: sync
endpoints: 3
atoms: 5
mcp: true
---

# Retrieve Public Holidays by Country and Year

Get holiday dates by year and country, including regional calendars, local names and observed days. Look up supported countries, languages and subdivisions.

## Endpoints

| Method | URL | Description | Atoms |
| --- | --- | --- | --- |
| GET | `https://api.eu.apyhub.com/callable-labs/retrieve-public-holidays-by-country-and-year-api/v1/countries` | What it does Returns a catalog of available holiday calendars as a JSON object, including the total… | 5 |
| GET | `https://api.eu.apyhub.com/callable-labs/retrieve-public-holidays-by-country-and-year-api/v1/countries/:country` | What it does Retrieves the calendar details for a country or market identified by its ISO code. The… | 5 |
| GET | `https://api.eu.apyhub.com/callable-labs/retrieve-public-holidays-by-country-and-year-api/v1/holidays/:year/:country` | What it does Returns the holiday calendar for a specific year and country, with optional filtering… | 5 |

## Endpoint reference

### List Supported Countries

`GET https://api.eu.apyhub.com/callable-labs/retrieve-public-holidays-by-country-and-year-api/v1/countries` · 5 atoms · accepts `application/json` · returns `application/json`

#### Quickstart

Fetch the holiday calendar catalog with a simple GET request.

```bash
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`.

```json
{
  "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]
    }
  ]
}
```

### Get Country Calendar Details

`GET https://api.eu.apyhub.com/callable-labs/retrieve-public-holidays-by-country-and-year-api/v1/countries/:country` · 5 atoms · accepts `application/json` · returns `application/json`

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `country` | path | string | yes | ISO 3166-1 alpha-2 or alpha-3 code Default: `US`. Example: `US`. |

#### Quickstart

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

```bash
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`.

```json
{
  "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": []
}
```

### List Country Holidays

`GET https://api.eu.apyhub.com/callable-labs/retrieve-public-holidays-by-country-and-year-api/v1/holidays/:year/:country` · 5 atoms · accepts `application/json` · returns `application/json`

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `year` | path | integer | yes | Default: `2026`. |
| `country` | path | string | yes | Default: `US`. |
| `language` | query | string | no |  |
| `observed` | query | boolean | no | Default: `true`. |
| `categories` | query | string | no |  |
| `subdivision` | query | string | no |  |

#### Quickstart

Get the holiday list for a specific year and country.

```bash
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).

```json
{
  "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
    }
  ]
}
```

## About

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

## Usage

Base URL: `https://api.eu.apyhub.com` (default region — see
`GET https://apyhub.com/api/public/regions` for the rest).

Authenticate with an ApyHub API key in the `apy-token` header.
Full docs and a live playground: https://apyhub.com/callable-labs/service/retrieve-public-holidays-by-country-and-year-api