Holidays

Countries are identified by ISO 3166-1 alpha-2 code. GB, gb, and Gb all work.

What is next

GET /v1/holidays/{countryCode}/next

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:

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

A whole year

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

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. It is a cheap class endpoint.