api-company/docs-site/src/pages/blog/public-holidays-api.mdx

---
title: "Public Holidays API: The Free Holiday Calendar API for Any Country"
description: "Get public holidays for 100+ countries with a single API call. The leeworks.dev Holidays API is perfect for scheduling, calendar apps, and payroll systems."
date: "2026-05-24"
author: "leeworks.dev"
tags: ["holidays", "api", "tutorial"]
---

import Base from '../../layouts/Base.astro';

<Base title="Public Holidays API Guide" description="Get public holidays for 100+ countries with a single API call.">

<article style="max-width: 800px; margin: 0 auto; padding: 2rem; line-height: 1.75;">

<script type="application/ld+json" set:html={JSON.stringify({
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Public Holidays API: The Free Holiday Calendar API for Any Country",
  "datePublished": "2026-05-24",
  "author": { "@type": "Organization", "name": "leeworks.dev" },
  "publisher": { "@type": "Organization", "name": "leeworks.dev", "url": "https://docs.leeworks.dev" }
})} />

# Public Holidays API: The Free Holiday Calendar API for Any Country

Building a scheduling app, payroll system, or booking platform? You need accurate **public holiday data** for every country you serve. The leeworks.dev **Holidays API** gives you that data in milliseconds.

## Why You Need a Holiday Calendar API

Manually maintaining a list of public holidays is a losing battle. Holidays change year to year, differ by country and region, and missing one can mean:

- **Wrong delivery estimates** on e-commerce sites
- **Incorrect payroll calculations** (overtime on holidays)
- **Broken calendar apps** that schedule meetings on national holidays
- **Failed SLA commitments** that assumed business days

A reliable **holiday API** solves this once.

## What the leeworks.dev Holidays API Provides

- Public holidays for **100+ countries**
- Data updated from Nager.Date's curated public dataset
- Filter by **country code** (ISO 3166-1 alpha-2), **year**, and **type**
- Response includes holiday name (localized), date, and type (`public`, `optional`, `observance`)
- Sub-100ms response time, SQLite-backed

## Quick Start

```bash
# Get all US public holidays for 2026
curl "https://holidays.leeworks.dev/v1/holidays?country=US&year=2026" \
  -H "X-RapidAPI-Key: YOUR_API_KEY"
```

Response:
```json
{
  "country": "US",
  "year": 2026,
  "holidays": [
    {
      "date": "2026-01-01",
      "name": "New Year's Day",
      "type": "public"
    },
    {
      "date": "2026-07-04",
      "name": "Independence Day",
      "type": "public"
    }
  ]
}
```

## Common Use Cases

### 1. Skip Holidays in Business Day Calculations

```python
from datetime import date, timedelta
import httpx

def next_business_day(start: date, country: str = "US") -> date:
    resp = httpx.get(
        "https://holidays.leeworks.dev/v1/holidays",
        params={"country": country, "year": start.year},
        headers={"X-RapidAPI-Key": "YOUR_KEY"},
    )
    holidays = {h["date"] for h in resp.json()["holidays"]}
    
    current = start + timedelta(days=1)
    while current.weekday() >= 5 or current.isoformat() in holidays:
        current += timedelta(days=1)
    return current
```

### 2. Display Holiday Badges in a Calendar

```javascript
async function getHolidayMap(countryCode, year) {
  const res = await fetch(
    `https://holidays.leeworks.dev/v1/holidays?country=${countryCode}&year=${year}`,
    { headers: { 'X-RapidAPI-Key': process.env.RAPIDAPI_KEY } }
  );
  const { holidays } = await res.json();
  // Return a Map of ISO date string → holiday name
  return new Map(holidays.map(h => [h.date, h.name]));
}

// Usage in a calendar component
const holidayMap = await getHolidayMap('GB', 2026);
const isHoliday = holidayMap.has('2026-12-25'); // true: Christmas Day
```

### 3. Check If Today Is a Holiday

```typescript
async function isTodayHoliday(country = 'US'): Promise<string | null> {
  const today = new Date().toISOString().split('T')[0];
  const year = new Date().getFullYear();
  
  const res = await fetch(
    `https://holidays.leeworks.dev/v1/is-holiday?country=${country}&date=${today}`,
    { headers: { 'X-RapidAPI-Key': process.env.RAPIDAPI_KEY! } }
  );
  const data = await res.json();
  return data.isHoliday ? data.name : null;
}
```

## Supported Countries (Sample)

| Code | Country | Code | Country |
|------|---------|------|---------|
| US | United States | GB | United Kingdom |
| CA | Canada | DE | Germany |
| FR | France | JP | Japan |
| AU | Australia | BR | Brazil |
| IN | India | MX | Mexico |

...and 90+ more. Use `GET /v1/countries` to see the full list.

## Pricing

| Plan | Requests/mo | Price |
|------|------------|-------|
| Free | 500 | $0 |
| Basic | 10,000 | $9/mo |
| Pro | 100,000 | $19/mo |
| Ultra | 1,000,000 | $49/mo |

**[Subscribe on RapidAPI →](https://rapidapi.com/leeworks/api/holidays)**

## Conclusion

Stop hardcoding holiday lists or scraping Wikipedia. The leeworks.dev **public holidays API** gives you accurate, up-to-date holiday data for every country you need — with a simple REST interface and affordable pricing.

**[Get started for free →](https://rapidapi.com/leeworks/api/holidays)**

</article>
</Base>