Is this a working day — in that country, in that state?
The Holidays API returns public-holiday data as clean JSON.
6 active endpoints, on 0 and 1 credit tiers.
- POST/holidays/v1/holidays
- POST/holidays/v1/is_workday
- POST/holidays/v1/workday_count
- POST/holidays/v1/next_holidays
- POST/holidays/v1/long_weekends
- POST/holidays/v1/countries
What Holidays & Workdays endpoints does ReefAPI ship?
6 live read endpoints. Read-only data API: no writes, no account actions, no dashboard access on the target site.
Holidays & Workdays API
3 of 6 endpoints, ready to run
Every public holiday for a country and year, each with its local name, its English name, the weekday it falls on, its type, and the regions it applies to when it is not nationwide.
{ "ok": true, "meta": { "api": "holidays", "endpoint": "holidays", "mode": "live", "latency_ms": 468.8, "record_count": 17, "cache_hit": false, "completeness_pct": 100 }, "data": { "country": "US", "year": 2026, "count": 17, "holidays": [ { "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" ], "year": 2026, "weekday": "Thursday", "nationwide": true }, { "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" ], "year": 2026, "weekday": "Monday", "nationwide": true }, { "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" ], "launchYear": null, "types": [ "Observance" ], "year": 2026, "weekday": "Thursday", "nationwide": false } ], "source": "Nager.Date" } }
How the Holidays & Workdays API works
Holidays & Workdays is a normal ReefAPI surface — the same four rules that hold for every other engine on the key.
No OAuth app, no request signing, no per-site account. One key covers all 184 engines.
Every route is a POST with a JSON body. Parameters are validated against the published schema before anything is charged.
Credits, not seats. Failed and blocked calls are never charged, and cache hits cost nothing.
One envelope everywhere. meta carries latency_ms, record_count and the endpoint that answered.
A delivery promise that does not land on a holiday
Adding three days to a date is easy and wrong. The question is how many working days there are between two dates in the region the customer is actually in.
{"country": "DE", "start": "2026-01-01", "end": "2026-01-31", "subdivision": "DE-BY"}Returns the working days, the weekend days and the holidays inside the window, with each holiday listed and flagged for whether it fell on a weekend anyway.
{"country": "DE", "date": "2026-01-06", "subdivision": "DE-BY"}For a single promised date. The reasons array names what made it non-working rather than leaving you to infer it.
The same January window returned a different number of working days for Bavaria than for Berlin. That difference is the entire reason to use this rather than a weekday calculation.
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}'{
"ok": true,
"data": { … },
"meta": {
"api": "holidays",
"endpoint": "holidays",
"mode": "live",
"latency_ms": …,
"record_count": …
},
"error": null
}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.
How far down the answer goes, and where it silently defaults
Measured across four countries and both sides of a regional holiday. The first row is the one that quietly produces wrong numbers.
6 January is a public holiday in Bavaria and an ordinary working day in Berlin. Asked without a subdivision, the endpoint answered working day — the nationwide view — which is Berlin's answer, not Bavaria's. Counted across January, Bavaria came back with one fewer working day than Berlin. Nothing warns you: the call succeeds and the number looks reasonable. If the region matters to you, pass it.
They are not a separate product. Of the German holidays in a year, ten carried an explicit region list; in Spain twenty-two did, and in Switzerland twenty-nine of thirty-three. A holiday that applies everywhere carries an empty region list and a nationwide flag, so the two cases are distinguishable rather than blended.
Each holiday carries the name as it is written in the country and the English name beside it — Neujahr and New Year's Day, Zafer Bayramı and Victory Day. A user-facing calendar needs the first; your own log lines and rules need the second.
The single-date check returns whether it is a weekend and whether it is a public holiday as separate booleans, plus a reasons array naming the holiday. It also returns the weekend definition it used, which is what makes the answer auditable in countries where the weekend is not Saturday and Sunday.
The country list is itself callable, so you can populate a dropdown from the same source that answers the queries rather than hardcoding a list that goes stale. Upcoming holidays come with a days-until count, which is the shape a reminder needs.
What people build with Holidays & Workdays
The jobs this data is most often used for.
endpoints
credits per call
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.
What Holidays & Workdays data costs
The cheapest call here is 0 credits, so $15/mo (Pro) buys 10,000 of them — $1.50 per 1,000 credits. Credits roll over and never expire, and failed or blocked calls are not charged.
Full pricing →- 1,000 free credits on signup, no card
- One key, all 184 APIs, one credit pool
- Failed and blocked calls are never charged
- Credits roll over and never expire
Call it in two lines
Sign up, get 1,000 credits and one key that works on every engine. Then this is the whole protocol.
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"])Have a question? We got answers.
The questions people actually ask before wiring up Holidays & Workdays.
Get a free key →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.
19 Utilities & AI APIs on the same key
One key, one credit pool, one response envelope. If you are pulling Holidays & Workdays, you are one call away from the rest of the category — no second contract, no second integration.
Need something this API does not do?
Name the endpoint, the field, or a source we do not carry yet. We ship new APIs every week and you would be first to get the key. Real people read every message and reply the same day.
Try it on your own data before you pay anything
The call above is the real endpoint, not a recording. A free key gives you 1,000 credits, the other 183 APIs, and the same envelope everywhere.
Endpoints, parameters and credit costs on this page are read from the live catalog and cannot drift from what the API accepts. Field notes were captured on 2026-08-30.