Holidays & Workdays API
The Holidays API returns public-holiday data as clean JSON.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
The primary holidays endpoint returns a country and year's holidays (date, name, local name, types, counties, weekday), and you can check is_workday, count workdays, list next_holidays and long_weekends and supported countries. It is built for scheduling, HR and payroll tools that need accurate holiday calendars. One ReefAPI key, one shared credit pool, the standard envelope.
Real request and response JSON
Captured from the indexed primary action, holidays, on .
{
"method": "POST",
"url": "https://api.reefapi.com/holidays/v1/holidays",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"country": "US",
"year": 2026
}
}{
"ok": true,
"meta": {
"api": "holidays",
"endpoint": "holidays",
"mode": "live",
"latency_ms": 518.9,
"record_count": 17,
"bytes": 11218,
"cache_hit": false,
"completeness_pct": 100,
"requests": 2,
"attribution": "Holiday data computed by Nager.Date (MIT-licensed, https://github.com/nager/Nager.Date), served free at https://date.nager.at. Public-holiday dates are factual reference data."
},
"data": {
"country": "US",
"year": 2026,
"count": 17,
"holidays": [
{
"date": "[redacted-phone]",
"localName": "New Year's Day",
"name": "[redacted-name]",
"countryCode": "US",
"fixed": false,
"global": true,
"counties": null,
"launchYear": null,
"types": [
"Public",
"Bank"
],
"year": 2026,
"weekday": "Thursday",
"nationwide": true
},
{
"date": "[redacted-phone]",
"localName": "Martin Luther King, Jr. Day",
"name": "[redacted-name]",
"countryCode": "US",
"fixed": false,
"global": true,
"counties": null,
"launchYear": null,
"types": [
"Public",
"Bank"
],
"year": 2026,
"weekday": "Monday",
"nationwide": true
},
{
"date": "[redacted-phone]",
"localName": "Lincoln's Birthday",
"name": "[redacted-name]",
"countryCode": "US",
"fixed": false,
"global": false,
"counties": [
"US-CA",
"US-CT",
"US-IL"
],
"launchYear": null,
"types": [
"Observance"
],
"year": 2026,
"weekday": "Thursday",
"nationwide": false
}
],
"source": "Nager.Date"
}
}What the Holidays & Workdays API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| holidays | public holidays for a country + year (full Nager fields + derived year/weekday/nationwide) | Ops teams call holidays to get public holidays for a country + year (full Nager fields + derived year/weekday/nationwide). | country, year |
| is_workday | is a given date a working day for a country? (weekend + public-holiday aware; reasons[] explain) | Developer tools call is_workday to get is a given date a working day for a country? (weekend + public-holiday aware; reasons[] explain). | country, date, weekend, types, subdivision |
| workday_count | business-day count over a date range: workdays/weekend_days/holiday_days + the holidays in range | Validation workflows call workday_count to get business-day count over a date range. | country, start, end, weekend, types, ... |
| next_holidays | upcoming public holidays (next ~365 days) with daysUntil | Data-quality teams call next_holidays to get upcoming public holidays (next ~365 days) with daysUntil. | country, today |
| long_weekends | long-weekend windows for a country + year (+ bridge-day suggestions) | Ops teams call long_weekends to get long-weekend windows for a country + year (+ bridge-day suggestions). | country, year |
| countries | the supported country set (code → name) | Developer tools call countries to get the supported country set (code → name). | none |
Call holidays from your stack
curl -X POST https://api.reefapi.com/holidays/v1/holidays \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"country":"US","year":2026}'import requests
r = requests.post(
"https://api.reefapi.com/holidays/v1/holidays",
headers={"x-api-key": REEF_KEY},
json={
"country": "US",
"year": 2026
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/holidays/v1/holidays", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"country": "US",
"year": 2026
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.holidays.holidays with {"country":"US","year":2026}.Who uses this API and why
- Scheduling tools call is_workday before booking a date.
- HR and payroll use holidays and workday_count to calculate leave and pay periods.
- Travel apps use long_weekends to suggest trips.
Questions developers ask before integrating
What is the Holidays & Workdays API?
Holidays & Workdays API is a ReefAPI endpoint group for public holidays and business-day calculations. It returns live JSON through POST requests under /holidays/v1.
Is the Holidays & Workdays API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. Holidays & Workdays calls use the same shared credit balance as every other ReefAPI engine.
Do I need a Holidays & Workdays login or account?
No login to Holidays & Workdays is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the Holidays & Workdays data?
The page example is captured from a live holidays call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the Holidays & Workdays API use?
Holidays & Workdays actions currently cost 1 credit per successful call. Failed or blocked calls are free, and all APIs draw from one credit pool.
Can I call Holidays & Workdays from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call holidays actions with the same key, credit pool and JSON envelope used by normal REST requests.
Is the Holidays & Workdays API a Holidays & Workdays scraper?
It is the managed alternative to a DIY Holidays & Workdays scraper. Instead of building and maintaining your own scraper — proxies, headless browsers, captcha and constant breakage — you call one ReefAPI endpoint and get the same public holidays and business-day calculations back as clean JSON.
Why does my Holidays & Workdays scraper keep getting blocked?
Most Holidays & Workdays scrapers break on anti-bot defenses, rate limits and IP bans that need rotating residential proxies and browser fingerprinting to clear. ReefAPI handles all of that for you — no proxies, no captchas, no maintenance — and returns live JSON. Blocked or failed calls are free.