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.
The response fields people misread
Holiday data has more edge cases than it looks like, and several fields do not mean what their names suggest. Every value below came out of a measured call — Turkey and the United States for 2026, Germany's long weekends, and a Q1 workday count for the UK.
| Field | Measured value | What it actually means |
|---|---|---|
| date | 2026-01-01 | a plain ISO date. No time, no timezone — a holiday is a calendar day, not an instant. |
| localName / name | "Yılbaşı" / "New Year's Day" | the local-language name and the English name, always both |
| fixed | false, even on 1 January | unreliable upstream. Do not branch on it — a fixed-date holiday can be flagged false. |
| global | false on the UK's New Year's Day, which lists all four nations | not a reliable 'nationwide' flag. Read counties instead. |
| counties | null nationwide · ["GB-ENG", "GB-NIR", "GB-SCT", "GB-WLS"] | ISO 3166-2 subdivision codes. null means it applies everywhere. |
| launchYear | null | the year the holiday was introduced, populated only occasionally |
| types | ["Public"] | an array — filter with the types parameter when you want bank holidays only |
| weekend_definition | ["Saturday", "Sunday"] | echoed back so you can see what was assumed; override it with the weekend parameter |
| workday_count buckets | total_days 90 = workdays 63 + weekend_days 26 + holiday_days 1 | the three buckets are disjoint and sum exactly, so a holiday on a Saturday is never counted twice |
| needBridgeDay / bridgeDays | true · ["2026-01-02"] | the working days you would have to take off to join a holiday to the weekend |
Observed dates are returned, not nominal ones. US Independence Day 2026 comes back as 2026-07-03 — the Friday — because 4 July falls on a Saturday that year. Do not hard-code the nominal date.
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
Why does is_workday say 4 July 2026 is not a holiday?
Because in 2026 it is not one — it is a Saturday. A measured is_workday call on 2026-07-04 for the US returned is_workday false, is_weekend true, is_public_holiday false and reasons ["weekend (Saturday)"], with an empty holidays array. The holiday itself moved: the US 2026 list carries Independence Day on 2026-07-03, the observed Friday. This is the single most common mistake with holiday data — asking about the nominal date instead of the observed one. Pull the year's list and read the dates rather than assuming them.
Can I trust the `fixed` flag to tell fixed-date holidays from moving ones?
No, and we would rather say so than let you build on it. Measured, 1 January 2026 came back with fixed false for both Turkey and the United States, which is plainly wrong for a date that never moves. The flag comes from upstream and is inconsistent. If you need to know whether a holiday moves, compare the same holiday's name across two years of the holidays action — that is cheap and it is actually true.
What does global: false mean if the holiday applies everywhere?
Less than you would hope. A measured UK workday_count returned New Year's Day with global false and counties listing all four nations — GB-ENG, GB-NIR, GB-SCT and GB-WLS — so it does apply across the whole country, just via four separate subdivision rules rather than one national one. Read counties: null means it applies everywhere, and a populated array tells you exactly which ISO 3166-2 subdivisions observe it. Then narrow with the subdivision parameter if you only care about one.
How do I handle countries whose weekend is not Saturday and Sunday?
Pass the weekend parameter. Every response echoes weekend_definition so you can confirm what was applied — measured, it defaulted to ["Saturday", "Sunday"]. For a Friday-Saturday weekend country you set it explicitly, and both is_workday and workday_count recompute against it. Without that, an SLA calculator for a Gulf-region customer silently counts their weekend as working days and their working Sunday as a weekend.
Does workday_count double-count a holiday that falls on a weekend?
No, and the arithmetic is checkable. A measured UK Q1 2026 count (1 January to 31 March) returned total_days 90, workdays 63, weekend_days 26 and holiday_days 1 — 63 plus 26 plus 1 is exactly 90. The buckets are disjoint: holiday_days counts only holidays that land on a working day, and each returned holiday carries on_weekend so you can see which ones were absorbed. That makes it safe to use directly for SLA windows and payroll periods.
What is a bridge day?
A working day wedged between a holiday and a weekend, which people take off to make a long break. long_weekends finds them for you: a measured German 2026 call returned 6 long weekends, the first spanning 2026-01-01 to 2026-01-04 with needBridgeDay true and bridgeDays ["2026-01-02"] — one Friday off buys four days. Others need no bridge at all, such as the Good Friday to Easter Monday run. Each entry carries dayCount and startWeekday, which is what you want for staffing forecasts and for travel-demand planning.
How are lunar and other moving holidays handled?
They are returned on their actual dates for the year you ask about, with the local name intact. A measured Turkish 2026 list returned 14 holidays including Ramazan Bayramı 1. Gün on 2026-03-20 and Ramazan Bayramı 2. Gün on 2026-03-21, both typed as Public. Those dates shift roughly eleven days earlier each year, so any cached calendar has to be refreshed per year rather than pattern-matched. Ask for the year you need; do not extrapolate.
Which countries are covered?
204, and the countries action returns the full list as countryCode plus name so you can validate an input before spending a call. Coverage depth varies with the country — a measured United States 2026 list held 17 holidays and Turkey 14 — and subdivision-level detail exists where the country actually has differing regional holidays, such as the German Länder or the four UK nations.
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.