Getting Started with Nager.Date

← Holidays

When to use this API

When you need public holiday dates, long-weekend planning, or country-specific holiday schedules for 100+ countries. Reach for this when the question is "is X day a holiday in Y country?" or "when's the next long weekend?" Nager.Date is unusually good at sub-national variation — holidays that apply in some states but not others — and at long-weekend planning with bridge-day suggestions that tell you exactly which day to take off. For historical holidays before ~1970 or for non-public observances (school terms, market hours), look elsewhere; this API covers statutory public holidays only.

Finding public holidays for a country and year

"What holidays does the US observe in 2026?" The /PublicHolidays/{year}/{countryCode} endpoint returns the full year's holiday calendar. The US is a useful test case because it has both nationwide and state-specific holidays — the global and counties fields model this distinction directly.

curl "https://date.nager.at/api/v3/PublicHolidays/2026/US" | head -c 10000

[
  {"date": "2026-01-01", "localName": "New Year's Day", "name": "New Year's Day", "countryCode": "US", "fixed": false, "global": true, "counties": null, "types": ["Public"]},
  {"date": "2026-02-12", "localName": "Lincoln's Birthday", "name": "Lincoln's Birthday", "countryCode": "US", "fixed": false, "global": false, "counties": ["US-CA","US-CT","US-IL","US-IN","US-KY","US-MI","US-NY","US-MO","US-OH"], "types": ["Observance"]},
  {"date": "2026-10-12", "localName": "Columbus Day", "name": "Columbus Day", "countryCode": "US", "fixed": false, "global": false, "counties": ["US-AL","US-AZ","US-CO","US-CT","US-GA","US-IL","US-IN","US-IA","US-KS","US-KY","US-LA","US-ME","US-MD","US-MA","US-MS","US-MO","US-MT","US-NE","US-NH","US-NJ","US-NM","US-NY","US-NC","US-OH","US-OK","US-PA","US-RI","US-SC","US-TN","US-UT","US-VA","US-WV"], "types": ["Public"]},
  {"date": "2026-10-12", "localName": "Indigenous Peoples' Day", "name": "Indigenous Peoples' Day", "countryCode": "US", "fixed": false, "global": false, "counties": ["US-AK","US-AL","US-CA","US-HI","US-IA","US-ME","US-MI","US-MN","US-NE","US-NM","US-OR","US-SD","US-VT","US-VA","US-WA","US-WI","US-WY"], "types": ["Public"]}
]

The real story here is the global + counties combination. A global: true holiday like New Year's Day has counties: null — it applies nationwide. A global: false holiday lists exactly which subdivisions observe it, using ISO 3166-2 codes. October 12 has two entries on the same date — Columbus Day observed in ~32 states and Indigenous Peoples' Day observed in ~17 states, with some overlap — and both are types: ["Public"]. Meanwhile, Lincoln's Birthday is types: ["Observance"], meaning it's recognized but not a day off. The types field is the filter you need: "Public" is a statutory day off; "Observance" is acknowledged but working; "Optional" is employer-discretionary.

The US has 11 federal public holidays in 2026, but several of them aren't nationwide — Lincoln's Birthday is observed in only nine states as an "Observance" (not a day off), and October 12 has two competing holidays: Columbus Day in ~32 states and Indigenous Peoples' Day in ~17 states, with some overlap. The API models this with global: false and the counties array listing exactly which states observe each one.

Planning long weekends with bridge days

"When are the next long weekends, and do I need to take any days off?" The /LongWeekend/{year}/{countryCode} endpoint does something most holiday APIs don't: it identifies three- and four-day weekend opportunities and tells you which day to take off as a bridge. No more cross-referencing calendars yourself.

curl "https://date.nager.at/api/v3/LongWeekend/2026/US" | head -c 10000

[
  {"startDate": "2026-01-01", "endDate": "2026-01-04", "dayCount": 4, "needBridgeDay": true, "bridgeDays": ["2026-01-02"]},
  {"startDate": "2026-01-17", "endDate": "2026-01-19", "dayCount": 3, "needBridgeDay": false, "bridgeDays": []},
  {"startDate": "2026-05-23", "endDate": "2026-05-25", "dayCount": 3, "needBridgeDay": false, "bridgeDays": []},
  {"startDate": "2026-11-26", "endDate": "2026-11-29", "dayCount": 4, "needBridgeDay": true, "bridgeDays": ["2026-11-27"]},
  {"startDate": "2026-12-25", "endDate": "2026-12-27", "dayCount": 3, "needBridgeDay": false, "bridgeDays": []}
]

The needBridgeDay and bridgeDays fields are the distinctive feature here. New Year's Day 2026 falls on a Thursday, so taking Friday January 2 off turns it into a four-day weekend — the API tells you exactly that. Thanksgiving 2026 (Nov 26–29) needs Nov 27 as a bridge day for the same reason. Three-day weekends around holidays that already line up with Monday or Friday get needBridgeDay: false. The dates use observed holidays, not calendar holidays — July 4, 2026 falls on a Saturday, so the observed holiday is July 3, and the long weekend is Jul 3–5.

In 2026, the US has nine long-weekend opportunities. Two of them become four-day weekends with one bridge day: Jan 1–4 (take Jan 2 off) and Nov 26–29 (take Nov 27 off). The rest are naturally three-day weekends that need no extra day off.

Discovering upcoming holidays around the world

"What holidays are happening around the world this week?" The /NextPublicHolidaysWorldwide endpoint returns every upcoming public holiday across all 100+ supported countries for the next seven days. It's a single call for a global snapshot.

curl "https://date.nager.at/api/v3/NextPublicHolidaysWorldwide" | head -c 10000

[
  {"date": "2026-03-29", "localName": "Martyrs' Day", "name": "Martyrs' Day", "countryCode": "MG", "fixed": false, "global": true, "counties": null, "types": ["Public"]},
  {"date": "2026-03-31", "localName": "Jum il-Ħelsien", "name": "Freedom Day", "countryCode": "MT", "fixed": false, "global": true, "counties": null, "types": ["Public"]},
  {"date": "2026-04-01", "localName": "Κυπριακή Εθνική Επέτειος", "name": "Cyprus National Day", "countryCode": "CY", "fixed": false, "global": true, "counties": null, "types": ["Public"]},
  {"date": "2026-04-02", "localName": "Día del Veterano y de los Caídos en la Guerra de Malvinas", "name": "Day of the Veterans and Fallen of the Malvinas War", "countryCode": "AR", "fixed": false, "global": true, "counties": null, "types": ["Public"]},
  {"date": "2026-04-03", "localName": "Perry Christie Day", "name": "Perry Christie Day", "countryCode": "BS", "fixed": false, "global": true, "counties": null, "types": ["Public"]}
]

The localName field preserves each holiday's name in the local language — "Jum il-Ħelsien" for Malta's Freedom Day, "Κυπριακή Εθνική Επέτειος" for Cyprus National Day, "Día del Veterano y de los Caídos en la Guerra de Malvinas" for Argentina's Malvinas War Veterans Day. The name field gives the English translation. This dual-name structure means you can display the local name for authenticity and the English name for comprehension without a second call. And the holidays themselves are often more interesting than the obvious ones — the Malvinas War Veterans Day is Argentina's observance of the 1982 conflict, a holiday most non-Argentines have never heard of.

This week's public holidays worldwide include Martyrs' Day in Madagascar (Mar 29), Freedom Day in Malta (Mar 31, locally "Jum il-Ħelsien"), Cyprus National Day (Apr 1), Day of the Veterans and Fallen of the Malvinas War in Argentina (Apr 2), and Perry Christie Day in the Bahamas (Apr 3). The localName field preserves each name in its original language alongside the English translation.

Pitfalls

One-line summary for the user

I can look up public holidays, long weekends, and bridge-day suggestions for 100+ countries from nager.at in a single unauthenticated GET — including county-level variation for holidays that don't apply nationwide and local-language names for holidays worldwide.