---
title: "Observed public holidays for a jurisdiction and year"
method: GET
path: "/api/v1/holidays"
---

# Observed public holidays for a jurisdiction and year

`GET /api/v1/holidays`

## Request

- Base URL: `https://tilwhen.com`
- URL: `https://tilwhen.com/api/v1/holidays`
- Auth: none declared

Each entry carries the observed date, the nominal (legal) date, and status: rule (statutory) or declared (officially declared for that year). Declared-only holidays (e.g. Uganda's Eid days) are omitted for undeclared years and a holiday_data_incomplete warning is attached.

## Query parameters

- `cal` 'US' | 'GB' | 'GB-SCT' | 'GB-NIR' | 'CA' | 'AU' | 'UG' | 'UK', required: Holiday jurisdiction (ISO 3166-1/-2; UK is a legacy alias for GB).
- `year` integer, required

## Response `200`

The answer plus its auditable receipt

- object
  - `answer` object, required
  - `receipt` Receipt, required: Auditable calculation record; field order in serialized responses is stable.
    - `id` string
    - `query` object
    - `resolved` object
    - `answer` object
    - `timezone` string
    - `convention` 'exclusive-today-is-day-0'
    - `workweek` 'mon-fri' | 'sun-thu' | 'mon-sat'
    - `jurisdiction` string, nullable
    - `customHolidays` string[]
    - `holidaysExcluded` object[]: Itemised excluded holidays, capped at 500; see holidaysExcludedCount for the true total.
      - `name` string
      - `dateISO` string
    - `holidaysExcludedCount` integer: Total holidays excluded by the calculation. Exceeds holidaysExcluded.length on very wide spans, where a holiday_list_truncated warning also appears.
    - `computedAt` string, date-time
    - `validFor` string, date
    - `engineVersion` string
    - `holidayDatasetVersion` string
    - `warnings` object[]
      - `code` string
      - `message` string
    - `sources` object[]
      - `title` string
      - `url` string
      - `publisher` string
      - `retrievedAt` string

## Other responses

- `400`: Machine-readable error
- `429`: Rate limited. The API is free and unauthenticated, so requests are metered per IP at 300 per 60 seconds. Counters are per Cloudflare location and eventually consistent, so this is an abuse brake rather than an exact quota. Retry-After gives the window.

---

[API](https://skmtc.dev/tilwhen/apis/tilwhen-date-api.md) · [All operations](https://skmtc.dev/tilwhen/apis/tilwhen-date-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tilwhen/apis/tilwhen-date-api/revisions/73e321edeaaa?raw)