> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.aegi.run/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.aegi.run/_mcp/server.

# Holidays

Countries are identified by [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
code. `GB`, `gb`, and `Gb` all work.

## What is next

```
GET /v1/holidays/{countryCode}/next
```

```ts
const { country, nextHolidays } = await aegis.holidays.next('US')

country // { code: 'US', name: 'United States' }
nextHolidays
// [{ name: 'Independence Day', date: '2026-07-04', national: true, type: [...] }]
```

Each holiday carries:

| Field      | Meaning                           |
| ---------- | --------------------------------- |
| `name`     | The holiday's name                |
| `date`     | ISO date, `YYYY-MM-DD`            |
| `national` | Whether it is observed nationwide |
| `type`     | Categories, e.g. public or bank   |

This is the endpoint to use for a countdown in a server — "days until
Christmas".

## A whole year

```
GET /v1/holidays/{countryCode}/{year}
```

```ts
const { year, holidays } = await aegis.holidays.year('GB', 2026)
```

`year` must be between 1900 and 2100.

## Caching

Results are cached server-side — an hour for `next`, a day for a full year — so
polling this from a bot is inexpensive both in practice and against your
[rate limits](/rate-limits). It is a `cheap` class endpoint.