> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bunny.build/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /public-holidays

> Retrieve the list of public holidays for any country and year.

## Endpoint

```
POST https://api.bunny.build/api/v1/public-holidays
```

## Authentication

| Header         | Required | Value                    |
| -------------- | -------- | ------------------------ |
| `X-API-Key`    | Yes      | Your API key (`bun_...`) |
| `Content-Type` | Yes      | `application/json`       |

## Overview

Retrieve a complete list of public holidays for any supported country, optionally filtered to a specific year. Returns holiday names in both English and the local language alongside ISO dates, enabling date-aware scheduling, SLA calculations, and calendar integrations.

## Use cases

* Skip holidays in business day calculations
* Display regional holidays in scheduling or calendar UIs
* Automate SLA deadline adjustments around public holidays
* Build country-aware payroll or time-tracking systems

## Details

Covers 100+ countries. Holiday data includes national and regional observances. The `year` field defaults to the current year when omitted. Country codes follow ISO 3166-1 alpha-2 (e.g. `BR`, `US`, `DE`).

## Request body

| Field     | Type   | Required | Description                                                             |
| --------- | ------ | -------- | ----------------------------------------------------------------------- |
| `country` | string | Yes      | ISO 3166-1 alpha-2 country code (e.g. `BR`, `US`)                       |
| `year`    | number | No       | Year to retrieve holidays for (default: current year, range: 1900–2100) |

### Example

```json theme={null}
{
  "country": "BR",
  "year": 2025
}
```

## Response

### 200 OK

| Field      | Type      | Description                       |
| ---------- | --------- | --------------------------------- |
| `country`  | string    | ISO country code (uppercased)     |
| `year`     | number    | Year of the holidays              |
| `count`    | integer   | Total number of holidays returned |
| `holidays` | object\[] | Array of holiday objects          |

Each holiday object:

| Field         | Type              | Description                                                             |
| ------------- | ----------------- | ----------------------------------------------------------------------- |
| `date`        | string            | ISO 8601 date (YYYY-MM-DD)                                              |
| `localName`   | string            | Holiday name in the local language                                      |
| `name`        | string            | Holiday name in English                                                 |
| `countryCode` | string            | ISO country code                                                        |
| `fixed`       | boolean           | Whether this holiday falls on the same date every year                  |
| `global`      | boolean           | `true` if the holiday applies to the whole country, `false` if regional |
| `counties`    | string\[] \| null | List of county/region codes the holiday applies to (`null` if global)   |
| `launchYear`  | integer \| null   | Year the holiday was first observed (if known)                          |
| `types`       | string\[]         | Holiday type tags, e.g. `["Public"]`                                    |

**Example**

```json theme={null}
{
  "country": "BR",
  "year": 2025,
  "count": 12,
  "holidays": [
    {
      "date": "2025-01-01",
      "localName": "Confraternização Universal",
      "name": "New Year's Day",
      "countryCode": "BR",
      "fixed": true,
      "global": true,
      "counties": null,
      "launchYear": null,
      "types": ["Public"]
    },
    {
      "date": "2025-04-21",
      "localName": "Tiradentes",
      "name": "Tiradentes' Day",
      "countryCode": "BR",
      "fixed": true,
      "global": true,
      "counties": null,
      "launchYear": null,
      "types": ["Public"]
    }
  ]
}
```

### 401 Unauthorized

```json theme={null}
{
  "detail": "Missing API key. Include X-API-Key header."
}
```

### 402 Payment Required

```json theme={null}
{
  "detail": "Monthly quota exceeded. Upgrade your plan."
}
```

### 422 Unprocessable Entity

```json theme={null}
{
  "detail": "Unknown country code"
}
```

### 429 Too Many Requests

```json theme={null}
{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}
```

## cURL example

```bash theme={null}
curl -X POST https://api.bunny.build/api/v1/public-holidays \
  -H "X-API-Key: bun_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"country": "BR", "year": 2025}'
```