---
title: "Public holidays of a year"
method: GET
path: "/v1/countries/{country}/holidays"
tags: ["Holidays and business days"]
---

# Public holidays of a year

`GET /v1/countries/{country}/holidays`

## Request

- Base URL: `https://api.africacompliancedata.com`
- URL: `https://api.africacompliancedata.com/v1/countries/{country}/holidays`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

National holidays with status: rule, confirmed, estimated (moon-sighted, replaced by the official date once announced), observed (weekend substitute) or bridge.

## Path parameters

- `country` string, required

## Query parameters

- `year` integer, required
- `include_religious_scopes` boolean

## Response `200`

Holidays

- object
  - `country` string, required
  - `country_name` string
  - `coverage` 'ready' | 'partial' | 'gap', required
  - `warning` string: When coverage is partial or gap, the year's holiday list is incomplete, or no value can be given
  - `sources` object, required
  - `dataset_version` string, required
  - `disclaimer` string, required
  - `year` integer
  - `weekend` integer[]
  - `weekend_rule` string
  - `holidays` Holiday[]
    - `date` string, date
    - `name` string
    - `rule_id` string, nullable: Absent for ad-hoc days off
    - `status` 'rule' | 'confirmed' | 'estimated' | 'observed' | 'bridge'
    - `scope` string: national, or the group a holiday is limited to
    - `observed_for` string, date: For a substitute day: the date of the holiday it replaces
    - `moved_from` string, date: Original date of a holiday officially moved
    - `bridge_for` string, date: For a bridge day: the holiday it bridges to
    - `estimated` boolean: true on a weekend substitute of an estimated (moon-sighted) date: it moves with the announced date
    - `source_url` string, nullable: Official announcement (confirmed dates); null when the official text is not online (source_note says where it was published)
    - `source_note` string: Where the announcement was made when it is not published online, or that the date is known from a press report of the official announcement
  - `notes` string[]
  - `announcements` object, nullable: Who announces moon-sighted and ad-hoc holidays, and where

## Other responses

- `400`: Missing or invalid parameter
- `401`: Missing or invalid API key
- `403`: Key paused for review after unusual bulk access ('Access paused')
- `404`: Unknown country, path or webhook id
- `429`: Rate limit for the plan exceeded, or key checks busy (many new keys from your network); see Retry-After
- `503`: Key check temporarily unavailable, or webhook storage unavailable (webhook endpoints); retry after Retry-After seconds

---

[API](https://skmtc.dev/africacompliancedata/apis/africa-compliance-data-api.md) · [All operations](https://skmtc.dev/africacompliancedata/apis/africa-compliance-data-api/llms.txt) · [OpenAPI document](https://skmtc.dev/africacompliancedata/apis/africa-compliance-data-api/revisions/cb17c8aafda8?raw)