# Holiday Calendar API – List Public Holidays by Country

> Holiday Calendar API – List Public Holidays by Country is a paid API for AI agents from holidays.use.x402atlas.com, paid per call via x402, $0.005/call, status unknown (last checked 2026-09-14).

Returns a list of official public holidays for a specified country and year, with optional regional subdivision filtering and localized names.

## Facts

- Endpoint: GET https://holidays.use.x402atlas.com/list
- Price: $0.005/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-14
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/holiday-calendar-api-list-public-holidays-by-country-d9b64c14
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_N9pWMXMtKuoyFJo5VGLke

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability holiday-calendar-api-list-public-holidays-by-country-d9b64c14
```

Example prompt: Can you list all official public holidays in Germany for 2025, including any specific to Bavaria?

## When to prefer this

Use this endpoint when you need a full list of all public holidays for a country in a given year — ideal for building calendars, configuring payroll systems, or planning travel. Prefer this over the sibling date-check endpoint when you need the complete holiday schedule rather than checking a single date. Best suited for the 37 supported European, Latin American, and African countries between 2020 and 2030.

## Known failure modes

- Unsupported country code returns an error — only 37 specific ISO codes are accepted
- Year out of range (below 2020 or above 2030) returns a validation error
- Invalid subdivision code format or mismatch with selected country causes rejection
- Invalid language code format causes a bad request response
- Missing required query parameters (country or year) results in a 400 error

## How this service works

Official public holidays by country and year, with regional subdivisions, localized names and normalized dates.

## Output

A JSON object containing the country code, year, query timestamp, total holiday count, and an array of holiday objects each with the holiday name (in the requested language), start date, end date, type (e.g. public, bank), a nationwide boolean, and applicable subdivision codes.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "required": [
      "country",
      "year"
     ],
     "properties": {
      "year": {
       "type": "integer",
       "maximum": 2030,
       "minimum": 2020,
       "description": "Calendar year"
      },
      "country": {
       "enum": [
        "AD",
        "AL",
        "AT",
        "BE",
        "BG",
        "BR",
        "BY",
        "CH",
        "CZ",
        "DE",
        "EE",
        "ES",
        "FR",
        "HR",
        "HU",
        "IE",
        "IT",
        "LI",
        "LT",
        "LU",
        "LV",
        "MC",
        "MD",
        "MT",
        "MX",
        "NL",
        "PL",
        "PT",
        "RO",
        "RS",
        "SE",
        "SI",
        "SK",
        "SM",
        "VA",
        "ZA"
       ],
       "type": "string",
       "description": "Supported ISO 3166-1 alpha-2 country code: AD Andorra; AL Albania; AT Austria; BE Belgium; BG Bulgaria; BR Brazil; BY Belarus; CH Switzerland; CZ Czechia; DE Germany; EE Estonia; ES Spain; FR France; HR Croatia; HU Hungary; IE Ireland; IT Italy; LI Liechtenstein; LT Lithuania; LU Luxembourg; LV Latvia; MC Monaco; MD Moldova; MT Malta; MX Mexico; NL Netherlands; PL Poland; PT Portugal; RO Romania; RS Serbia; SE Sweden; SI Slovenia; SK Slovakia; SM San Marino; VA Vatican City; ZA South Africa."
      },
      "language": {
       "type": "string",
       "pattern": "^[A-Z]{2}$",
       "description": "Optional two-letter ISO 639-1 result language. Defaults to English when available."
      },
      "subdivision": {
       "type": "string",
       "pattern": "^[A-Z]{2}-.+$",
       "maxLength": 20,
       "description": "Optional regional subdivision code beginning with the selected country code, for example DE-BE."
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object",
     "required": [
      "country",
      "year",
      "queried_at",
      "count",
      "holidays"
     ]
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "year": 2026,
  "count": 1,
  "country": "DE",
  "holidays": [
   {
    "name": "New Year's Day",
    "type": "Public",
    "end_date": "2026-01-01",
    "nationwide": true,
    "start_date": "2026-01-01",
    "subdivisions": [],
    "regional_scope": "National",
    "temporal_scope": "FullDay"
   }
  ],
  "language": "EN",
  "queried_at": "2026-07-27T12:00:00Z",
  "subdivision": "DE-BE"
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/holiday-calendar-api-list-public-holidays-by-country-d9b64c14/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from holidays.use.x402atlas.com](https://www.zero.xyz/host/holidays.use.x402atlas.com/llms.txt)