# 2s.io Calendar Holidays API

> 2s.io Calendar Holidays API is a paid API for AI agents from 2s.io, paid per call via x402, $0.001/call, status unknown (last checked 2026-09-15).

Returns a list of public, bank, school, and other holidays for a given country and year, with optional region and language filtering.

## Facts

- Endpoint: GET https://2s.io/api/calendar/holidays
- Price: $0.001/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-15
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/2s-io-calendar-holidays-api-09c9dd29
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_8VbdNbtNNGw5tCcKQq8g7

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 2s-io-calendar-holidays-api-09c9dd29
```

Example prompt: What are all the public holidays in Japan for 2026, listed in English?

## When to prefer this

Use this endpoint when you need structured, machine-readable holiday data for a specific country and year without needing to sign up for an API key. It is especially useful for scheduling automation, date validation, business day calculations, or enriching calendar data across many countries and regions. It covers public, bank, school, and observance holidays with regional subdivision support and multilingual names.

## Known failure modes

- Missing required 'country' or 'year' query parameters returns an error response
- Invalid or unsupported ISO 3166-1 country code returns empty results or error
- Invalid region/subdivision code may return no regional holidays or an error
- Unsupported language code falls back to default language or returns an error
- Year out of supported range may return empty or error
- Payment not sent or insufficient USDC results in HTTP 402 Payment Required

## How this service works

List the official holidays for a country and year, with exact observed dates including substitute days (e.g. a Saturday July 4th observed on Friday). Query: country (ISO 3166-1 alpha-2, 200+ supported), year, optional region (subdivision code like CA for US-California or BY for DE-Bavaria), optional types filter (public, bank, school, optional, observance — comma-separated), optional lang (ISO 639-1) for localized names. Returns one item per holiday: { date (YYYY-MM-DD), name, type, substitute, rule }. Dates are computed from maintained per-country rules — including movable feasts and lunar-calendar holidays — so they stay correct year over year. Use for scheduling, delivery estimates, payment terms, and SLA math.

## Output

A JSON object containing an array of holiday entries for the requested country and year, each with a date string (YYYY-MM-DD), holiday name, type (public/bank/school/optional/observance), a recurrence rule, and a substitute flag indicating if it's a moved observance. Also includes total count and source attribution (provider, license, URL).

## Example request

```json
{
 "input": {
  "type": "http",
  "method": "GET",
  "queryParams": {
   "lang": "en",
   "year": "2026",
   "types": "public",
   "country": "US"
  }
 }
}
```

## 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",
    "queryParams"
   ],
   "properties": {
    "type": {
     "const": "http"
    },
    "method": {
     "const": "GET"
    },
    "queryParams": {
     "required": [
      "country",
      "year"
     ],
     "properties": {
      "lang": {
       "type": "string",
       "description": "Optional ISO 639-1 language for holiday names."
      },
      "year": {
       "type": "string",
       "description": "Calendar year, e.g. 2026."
      },
      "types": {
       "type": "string",
       "description": "Optional comma-separated filter: public, bank, school, optional, observance."
      },
      "region": {
       "type": "string",
       "description": "Optional subdivision code, e.g. CA (US-California), BY (DE-Bavaria)."
      },
      "country": {
       "type": "string",
       "description": "ISO 3166-1 alpha-2 country code, e.g. US, DE, JP."
      }
     }
    }
   }
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/2s-io-calendar-holidays-api-09c9dd29/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from 2s.io](https://www.zero.xyz/host/2s.io/llms.txt)