Public Holidays API logo
EventsMAINTAINED1 token / call

Public Holidays API

23,786 public holidays for 204 countries from 2020 to 2028, with regional scope and long weekends

Public holidays for 204 countries and territories, served from our own database — 23,786 holidays covering 2020 through 2028, sourced from the MIT-licensed Nager.Date project. Each holiday carries its English and local name, nationwide-vs-regional scope (with ISO subdivision codes: Lincoln's Birthday lists US-CA, US-NY...), fixed-date flag and types (Public, Bank, Observance...). Get a country's year (US 2026 correctly shows Independence Day observed on Friday July 3), ask if a given date is a holiday (/holidays/today — 178 countries celebrate December 25), pull the next upcoming holidays for any country, or request computed long weekends (US 2026 has 8 three-day-plus breaks, listed with dates and the anchor holiday). The original /v1/{year}/{code} route still works unchanged, so existing integrations keep running — but responses now come from D1 in milliseconds with multi-year history instead of a third-party proxy call. Scheduling, HR and payroll tools, delivery-date calculators, booking systems and marketing calendars.

Every call needs an X-Api-Key header. A free key includes 500 tokens a month, no card required. 1 token per call, so the free plan covers about 500 calls a month.

No credit card requiredAccess to 125+ APIsCancel anytime
response.json
{
  "query": "GET /v1/holidays/today?country=US&date=2026-07-03",
  "is_public_holiday": true,
  "holiday": "Independence Day (observed)",
  "coverage": "204 countries, 2020-2028",
  "long_weekends": "computed per country/year"
}

Also available on

Production Ready
Battle-tested infrastructure with a 99.9% uptime SLA. Rate limits are generous, responses are consistent.
Simple Integration
Standard REST + JSON. Works with any HTTP client. Copy-ready code snippets in 4 languages.
One Key, 125+ APIs
Your DataAndAPIs subscription unlocks every API on the platform — anime, finance, sports, and more.

Use cases for Public Holidays API

  • Skip holidays when computing delivery dates, SLAs or payment due dates per country.

  • Show upcoming holidays and long weekends in an HR, travel or scheduling app.

  • Check whether a given date is a public holiday before sending notifications or opening a store.

  • Handle regional holidays correctly using the ISO subdivision codes on each entry.

Public Holidays API endpoints

Every endpoint with its parameters and a real example response.

GETCountry Holidays By Year

https://public-holidays.dataandapis.com/v1/holidays/{country}/{year}

Path parameters

ParameterExample
countryUSRequired
year2026Required

Example request

curl
curl "https://public-holidays.dataandapis.com/v1/holidays/US/2026" \
  -H "X-Api-Key: YOUR_API_KEY"
JavaScript / TypeScript (dataandapis package)
// npm install dataandapis
import { DataAndApis } from "dataandapis";

const client = new DataAndApis(); // reads DATAANDAPIS_API_KEY

const data = await client.publicHolidays.countryHolidaysByYear({
  country: "US",
  year: 2026,
});
Example response
[
  {
    "date": "2026-01-01",
    "localName": "New Year's Day",
    "name": "New Year's Day",
    "countryCode": "US",
    "fixed": false,
    "global": true,
    "counties": null,
    "launchYear": null,
    "types": [
      "Public",
      "Bank"
    ]
  },
  {
    "date": "2026-01-19",
    "localName": "Martin Luther King, Jr. Day",
    "name": "Martin Luther King, Jr. Day",
    "countryCode": "US",
    "fixed": false,
    "global": true,
    "counties": null,
    "launchYear": null,
    "types": [
      "Public",
      "Bank"
    ]
…
Show full response
[
  {
    "date": "2026-01-01",
    "localName": "New Year's Day",
    "name": "New Year's Day",
    "countryCode": "US",
    "fixed": false,
    "global": true,
    "counties": null,
    "launchYear": null,
    "types": [
      "Public",
      "Bank"
    ]
  },
  {
    "date": "2026-01-19",
    "localName": "Martin Luther King, Jr. Day",
    "name": "Martin Luther King, Jr. Day",
    "countryCode": "US",
    "fixed": false,
    "global": true,
    "counties": null,
    "launchYear": null,
    "types": [
      "Public",
      "Bank"
    ]
  },
  {
    "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"
    ],
    "launchYear": null,
    "types": [
      "Observance"
    ]
  }
]

GETData Sources

https://public-holidays.dataandapis.com/v1/sources

This endpoint takes no parameters.

Example request

curl
curl "https://public-holidays.dataandapis.com/v1/sources" \
  -H "X-Api-Key: YOUR_API_KEY"
JavaScript / TypeScript (dataandapis package)
// npm install dataandapis
import { DataAndApis } from "dataandapis";

const client = new DataAndApis(); // reads DATAANDAPIS_API_KEY

const data = await client.publicHolidays.dataSources();
Example response
{
  "ok": true,
  "sources": [
    {
      "slug": "nager-date",
      "name": "Nager.Date worldwide public holidays",
      "publisher": "Nager.Date project (Tino Hager and contributors)",
      "licence": "MIT",
      "source_url": "https://date.nager.at/",
      "file_url": "https://date.nager.at/api/v3/PublicHolidays",
      "cadence": "years 2020-2028; annual re-scrape adds the next year",
      "record_count": 23786,
      "retrieved_at": "2026-09-06"
    }
  ]
}

GETIs It A Holiday

https://public-holidays.dataandapis.com/v1/holidays/today

Query parameters

ParameterExample
countryUSOptional
date2026-07-03Optional

Example request

curl
curl "https://public-holidays.dataandapis.com/v1/holidays/today?country=US&date=2026-07-03" \
  -H "X-Api-Key: YOUR_API_KEY"
JavaScript / TypeScript (dataandapis package)
// npm install dataandapis
import { DataAndApis } from "dataandapis";

const client = new DataAndApis(); // reads DATAANDAPIS_API_KEY

const data = await client.publicHolidays.isItAHoliday({
  country: "US",
  date: "2026-07-03",
});
Example response
{
  "ok": true,
  "country": "US",
  "date": "2026-07-03",
  "is_public_holiday": true,
  "holidays": [
    {
      "date": "2026-07-03",
      "localName": "Independence Day",
      "name": "Independence Day",
      "countryCode": "US",
      "fixed": false,
      "global": true,
      "counties": null,
      "launchYear": null,
      "types": [
        "Public",
        "Bank"
      ]
    }
  ]
}

GETLong Weekends

https://public-holidays.dataandapis.com/v1/holidays/long-weekends/{country}/{year}

Path parameters

ParameterExample
countryUSRequired
year2026Required

Example request

curl
curl "https://public-holidays.dataandapis.com/v1/holidays/long-weekends/US/2026" \
  -H "X-Api-Key: YOUR_API_KEY"
JavaScript / TypeScript (dataandapis package)
// npm install dataandapis
import { DataAndApis } from "dataandapis";

const client = new DataAndApis(); // reads DATAANDAPIS_API_KEY

const data = await client.publicHolidays.longWeekends({ country: "US", year: 2026 });
Example response
{
  "ok": true,
  "country": "US",
  "year": 2026,
  "long_weekends": [
    {
      "start": "2026-01-17",
      "end": "2026-01-19",
      "days": 3,
      "holidays": [
        "Martin Luther King, Jr. Day"
      ]
    },
    {
      "start": "2026-02-14",
      "end": "2026-02-16",
      "days": 3,
      "holidays": [
        "Presidents Day"
      ]
    },
    {
      "start": "2026-05-23",
      "end": "2026-05-25",
      "days": 3,
      "holidays": [
        "Memorial Day"
      ]
…
Show full response
{
  "ok": true,
  "country": "US",
  "year": 2026,
  "long_weekends": [
    {
      "start": "2026-01-17",
      "end": "2026-01-19",
      "days": 3,
      "holidays": [
        "Martin Luther King, Jr. Day"
      ]
    },
    {
      "start": "2026-02-14",
      "end": "2026-02-16",
      "days": 3,
      "holidays": [
        "Presidents Day"
      ]
    },
    {
      "start": "2026-05-23",
      "end": "2026-05-25",
      "days": 3,
      "holidays": [
        "Memorial Day"
      ]
    }
  ]
}

GETNext Holidays

https://public-holidays.dataandapis.com/v1/holidays/next

Query parameters

ParameterExample
count5Optional
countryMXRequired

Example request

curl
curl "https://public-holidays.dataandapis.com/v1/holidays/next?count=5&country=MX" \
  -H "X-Api-Key: YOUR_API_KEY"
JavaScript / TypeScript (dataandapis package)
// npm install dataandapis
import { DataAndApis } from "dataandapis";

const client = new DataAndApis(); // reads DATAANDAPIS_API_KEY

const data = await client.publicHolidays.nextHolidays({ count: 5, country: "MX" });
Example response
{
  "ok": true,
  "country": "MX",
  "from": "2026-09-06",
  "holidays": [
    {
      "date": "2026-09-16",
      "localName": "Día de la Independencia",
      "name": "Independence Day",
      "countryCode": "MX",
      "fixed": false,
      "global": true,
      "counties": null,
      "launchYear": null,
      "types": [
        "Public"
      ]
    },
    {
      "date": "2026-11-16",
      "localName": "Día de la Revolución",
      "name": "Revolution Day",
      "countryCode": "MX",
      "fixed": false,
      "global": true,
      "counties": null,
      "launchYear": null,
      "types": [
…
Show full response
{
  "ok": true,
  "country": "MX",
  "from": "2026-09-06",
  "holidays": [
    {
      "date": "2026-09-16",
      "localName": "Día de la Independencia",
      "name": "Independence Day",
      "countryCode": "MX",
      "fixed": false,
      "global": true,
      "counties": null,
      "launchYear": null,
      "types": [
        "Public"
      ]
    },
    {
      "date": "2026-11-16",
      "localName": "Día de la Revolución",
      "name": "Revolution Day",
      "countryCode": "MX",
      "fixed": false,
      "global": true,
      "counties": null,
      "launchYear": null,
      "types": [
        "Public"
      ]
    }
  ]
}

GETSupported Countries

https://public-holidays.dataandapis.com/v1/countries

This endpoint takes no parameters.

Example request

curl
curl "https://public-holidays.dataandapis.com/v1/countries" \
  -H "X-Api-Key: YOUR_API_KEY"
JavaScript / TypeScript (dataandapis package)
// npm install dataandapis
import { DataAndApis } from "dataandapis";

const client = new DataAndApis(); // reads DATAANDAPIS_API_KEY

const data = await client.publicHolidays.supportedCountries();
Example response
{
  "ok": true,
  "total": 204,
  "countries": [
    {
      "code": "AD",
      "name": "Andorra",
      "years_from": 2020,
      "years_to": 2028,
      "holiday_count": 126
    },
    {
      "code": "AL",
      "name": "Albania",
      "years_from": 2020,
      "years_to": 2028,
      "holiday_count": 119
    }
  ]
}

Where the data comes from

Source
Nager.Date public holiday data (MIT licence), loaded into the API's own database.
Freshness
Annual load adding the next year; 2020 to 2028 currently available.

One install. Every endpoint.

Install the dataandapis package from npm and call this API with typed methods, or use any HTTP client in the language you prefer.

4languages
6endpoints
RESTarchitecture
1key for all APIs
  • Typed parameters and responses, with auto-completion in your editor
  • Works with import and require on Node.js 18 or later, with no dependencies
  • One key works across 125+ APIs on the platform

Read the npm package guide →

// npm install dataandapis
import { DataAndApis } from "dataandapis";

const client = new DataAndApis(); // reads DATAANDAPIS_API_KEY

const data = await client.publicHolidays.countryHolidaysByYear({
  country: "US",
  year: 2026,
});

Public Holidays API · X-Api-Key

Explore the endpoints

Browse request parameters and inspect live example responses.

Available Endpoints

Request Parameters

API URL

Headers

X-Api-Key

Path Parameters

country
year
// npm install dataandapis
import { DataAndApis } from "dataandapis";

const client = new DataAndApis({ apiKey: "YOUR_API_KEY" });

const data = await client.publicHolidays.countryHolidaysByYear({
  country: "US",
  year: 2026,
});

One subscription. Every API.

Tokens unlock this API and 125+ others on DataAndAPIs. Switch APIs any time — we promote.

FREE

$0/mo

500 tokens / month

  • Access to all APIs
  • Tokens reset monthly
  • Community support
Start free
Most Popular

STARTER

$6.99/mo

25,000 tokens / month

  • Access to all APIs
  • Tokens reset monthly
  • Email support
Subscribe

PRO

$24.99/mo

100,000 tokens / month

  • Access to all APIs
  • Tokens reset monthly
  • Priority email support
Subscribe

ULTRA

$99.99/mo

1,000,000 tokens / month

  • Access to all APIs
  • Tokens reset monthly
  • Priority support
Subscribe

Need higher volume, dedicated infra, or a custom contract? Talk to sales →

Questions about Public Holidays API

Ship Public Holidays API this afternoon.

500 free tokens. No card. Plus 125+ other APIs on the same key.