Look up public holidays

When the user asks about public holidays, long weekends, or bridge days for a country — holiday dates, sub-national variation, local-language holiday names — reach for Nager.Date. Unauthenticated GET for 100+ countries.

look-up-public-holidays · v1 · updated 2026-04-16

Agents: This page is a SKILL.md-style capability guide. For JSON, call GET /api/skills/look-up-public-holidays. To drop this into a local Claude Code install, copy the frontmatter + body below into ~/.claude/skills/look-up-public-holidays/SKILL.md.

When to use this skill

When the user asks "is X day a holiday in Y country?", "what are the public holidays for Germany in 2026?", or wants to know which days to take off for a long weekend. Nager.Date covers statutory public holidays for 100+ countries, including sub-national variation — holidays observed in some states but not others. For historical holidays before ~1970 or non-public observances (school terms, market hours), look elsewhere.

Your best first call

curl "https://date.nager.at/api/v3/PublicHolidays/2026/US"

No auth. No key. Returns a JSON array of holiday objects for the given year and ISO 3166-1 alpha-2 country code. The same endpoint works for any supported country and year.

Key fields in each holiday object:

date — ISO date string (observed date, which may shift from the calendar date when holidays fall on weekends)
localName — holiday name in the local language ("Jum il-Ħelsien" for Malta's Freedom Day, "Κυπριακή Εθνική Επέτειος" for Cyprus National Day)
name — English translation
global — true means nationwide; false means sub-national, with counties listing which ISO 3166-2 subdivisions observe it
counties — null when global is true; otherwise an array like ["US-CA","US-NY","US-IL"] naming the observing subdivisions
types — "Public" (statutory day off), "Observance" (recognized but working), or "Optional" (employer-discretionary). Filter for "Public" to count only days off.

Fallbacks (when the best call isn't enough)

Planning long weekends with bridge days → /LongWeekend/{year}/{countryCode} returns upcoming long-weekend opportunities with needBridgeDay and bridgeDays fields telling you exactly which day to take off to extend a holiday into a four-day weekend.
Holidays happening worldwide this week → /NextPublicHolidaysWorldwide returns all upcoming public holidays across all 100+ countries for the next 7 days, with localName in the original language alongside the English name.

Pitfalls

Country codes are ISO 3166-1 alpha-2, not alpha-3. Use US not USA, DE not DEU, GB not GBR. The /AvailableCountries endpoint lists all valid codes and their display names.
The same date can produce two entries — October 12 has both Columbus Day and Indigenous Peoples' Day in the US, observed in different states. Don't deduplicate by date alone.
types includes "Observance" and "Optional" alongside "Public". An "Observance" is recognized but not a day off; "Optional" is employer-discretionary. Filter by types if you only want statutory days off, or you will overcount.
IsTodayPublicHoliday returns an HTTP status code, not JSON: 200 means today is a holiday, 204 means it isn't. Handle 204 as success, not error.

One-line summary for the user

I can look up public holidays by country and year from nager.at — including sub-national variation and long-weekend bridge-day suggestions, no auth required.

APIs this skill uses

Holidays · primary · verified

A free API for public holidays. Get public holidays, long weekends, country information, and upcoming holidays for 100+ countries worldwide. No authentication required.

Generated from

Holidays tutorial Getting Started with Nager.Date

SKILL.md source (frontmatter + body)

---
name: look-up-public-holidays
description: When the user asks about public holidays, long weekends, or bridge days for a country — holiday dates, sub-national variation, local-language holiday names — reach for Nager.Date. Unauthenticated GET for 100+ countries.
---

## When to use this skill

When the user asks "is X day a holiday in Y country?", "what are the public holidays for Germany in 2026?", or wants to know which days to take off for a long weekend. Nager.Date covers statutory public holidays for 100+ countries, including sub-national variation — holidays observed in some states but not others. For historical holidays before ~1970 or non-public observances (school terms, market hours), look elsewhere.

## Your best first call

```bash
curl "https://date.nager.at/api/v3/PublicHolidays/2026/US"
```

No auth. No key. Returns a JSON array of holiday objects for the given year and ISO 3166-1 alpha-2 country code. The same endpoint works for any supported country and year.

Key fields in each holiday object:

- `date` — ISO date string (observed date, which may shift from the calendar date when holidays fall on weekends)
- `localName` — holiday name in the local language ("Jum il-Ħelsien" for Malta's Freedom Day, "Κυπριακή Εθνική Επέτειος" for Cyprus National Day)
- `name` — English translation
- `global` — `true` means nationwide; `false` means sub-national, with `counties` listing which ISO 3166-2 subdivisions observe it
- `counties` — `null` when `global` is `true`; otherwise an array like `["US-CA","US-NY","US-IL"]` naming the observing subdivisions
- `types` — `"Public"` (statutory day off), `"Observance"` (recognized but working), or `"Optional"` (employer-discretionary). Filter for `"Public"` to count only days off.

## Fallbacks (when the best call isn't enough)

- **Planning long weekends with bridge days** → `/LongWeekend/{year}/{countryCode}` returns upcoming long-weekend opportunities with `needBridgeDay` and `bridgeDays` fields telling you exactly which day to take off to extend a holiday into a four-day weekend.
- **Holidays happening worldwide this week** → `/NextPublicHolidaysWorldwide` returns all upcoming public holidays across all 100+ countries for the next 7 days, with `localName` in the original language alongside the English `name`.

## Pitfalls

- Country codes are ISO 3166-1 alpha-2, not alpha-3. Use `US` not `USA`, `DE` not `DEU`, `GB` not `GBR`. The `/AvailableCountries` endpoint lists all valid codes and their display names.
- The same date can produce two entries — October 12 has both Columbus Day and Indigenous Peoples' Day in the US, observed in different states. Don't deduplicate by date alone.
- `types` includes `"Observance"` and `"Optional"` alongside `"Public"`. An `"Observance"` is recognized but not a day off; `"Optional"` is employer-discretionary. Filter by `types` if you only want statutory days off, or you will overcount.
- `IsTodayPublicHoliday` returns an HTTP status code, not JSON: `200` means today is a holiday, `204` means it isn't. Handle `204` as success, not error.

## One-line summary for the user

I can look up public holidays by country and year from nager.at — including sub-national variation and long-weekend bridge-day suggestions, no auth required.

« Back to all skills