# Public Holidays API
> Public holidays for 120+ countries — by year, the next upcoming holidays for a country, and the list of supported countries. Each holiday includes the date, English and local name, scope (national/regional) and type. Ideal for HR, scheduling and booking systems.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/holidays-api/..."
```

## Pricing
- **Free** (Free) — 5,000 calls/Mo, 5 req/s
- **Basic** ($9/Mo) — 50,000 calls/Mo, 15 req/s
- **Pro** ($29/Mo) — 250,000 calls/Mo, 30 req/s
- **Mega** ($69/Mo) — 1,000,000 calls/Mo, 50 req/s

## Endpoints

### Holidays

#### `GET /v1/countries` — Supported countries

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/holidays-api/v1/countries"
```

**Response:**
```json
{
    "data": {
        "count": 122,
        "countries": [
            {
                "code": "AD",
                "name": "Andorra"
            },
            {
                "code": "AL",
                "name": "Albania"
            },
            {
                "code": "AM",
                "name": "Armenia"
            },
            {
                "code": "AR",
                "name": "Argentina"
            },
            {
                "code": "AT",
                "name": "Austria"
            },
            {
                "code": "AU",
                "name": "Australia"
            },
            {
                "code": "AX",
                "name": "Åland Islands"
            },
            {
                "code": "BA",
                "name": "Bosnia and Herzegovina"
            },
            {
                "code": "BB",
                "name": "Barbados"
            },
            {
                "code": "BD",
                "name": "Bangladesh"
            },
            {
                "code": "BE",
                "name": "Belgium"
            },
            {
                "code": "BG",
                "name": "Bulgaria"
            },
            {
                "code": "BJ",
                "name": "Benin"
            },
            {
                "code": "BO",
                "name": "Bolivia"
            },
            {
                "code": "BR",
                "name": "Brazil"
            },
            {
  
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/holidays` — Public holidays for a country + year

**Parameters:**
- `country` (query, required, string) — 2-letter ISO country code Example: `DE`
- `year` (query, optional, string) — 4-digit year (default current) Example: `2026`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/holidays-api/v1/holidays?country=DE&year=2026"
```

**Response:**
```json
{
    "data": {
        "year": 2026,
        "count": 19,
        "country": "DE",
        "holidays": [
            {
                "date": "2026-01-01",
                "name": "New Year's Day",
                "types": [
                    "Public"
                ],
                "global": true,
                "country": "DE",
                "counties": null,
                "local_name": "Neujahr",
                "launch_year": null
            },
            {
                "date": "2026-01-06",
                "name": "Epiphany",
                "types": [
                    "Public"
                ],
                "global": false,
                "country": "DE",
                "counties": [
                    "DE-BW",
                    "DE-BY",
                    "DE-ST"
                ],
                "local_name": "Heilige Drei Könige",
                "launch_year": null
            },
            {
                "date": "2026-03-08",
                "name": "International Women's Day",
                "types": [
                    "Public"
                ],
                "global": false,
                "country": "DE",
                "counties": [
                    "DE-BE",
                    "DE-MV"
                ],
                "local_name": "Internationaler Frauentag",
                "launch_year": null
            },
            {
                "date": "2026-04-03",
                "name": "Good Friday",
            
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/next` — Next upcoming holidays

**Parameters:**
- `country` (query, required, string) — 2-letter ISO country code Example: `US`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/holidays-api/v1/next?country=US"
```

**Response:**
```json
{
    "data": {
        "count": 12,
        "country": "US",
        "holidays": [
            {
                "date": "2026-06-19",
                "name": "Juneteenth National Independence Day",
                "types": [
                    "Public",
                    "Bank"
                ],
                "global": true,
                "country": "US",
                "counties": null,
                "local_name": "Juneteenth National Independence Day",
                "launch_year": null
            },
            {
                "date": "2026-07-03",
                "name": "Independence Day",
                "types": [
                    "Public",
                    "Bank"
                ],
                "global": true,
                "country": "US",
                "counties": null,
                "local_name": "Independence Day",
                "launch_year": null
            },
            {
                "date": "2026-09-07",
                "name": "Labour Day",
                "types": [
                    "Public",
                    "Bank"
                ],
                "global": true,
                "country": "US",
                "counties": null,
                "local_name": "Labor Day",
                "launch_year": null
            },
            {
                "date": "2026-10-12",
                "name": "Columbus Day",
                "types": [
                    "Public"
                ],
                "global":
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/holidays-api
OpenAPI spec: https://www.oanor.com/api/holidays-api/openapi.json