API reference

Authentication and limits

• Anonymous (no key): about 30 requests per minute per IP. Meant for trying the API and for the web calculator.
• API key: send Authorization: Bearer wd_live_… (or X-Api-Key). Free keys include 1,000 calls per calendar month (UTC) and about 120 requests per minute per key (and per IP for keyed traffic). Responses carry X-Plan, X-Quota-Limit, X-Quota-Used and X-Quota-Remaining. When the monthly quota is used up you get 429 monthly_quota_exceeded with Retry-After = seconds until 00:00 UTC on the 1st.
• Repeated failed authentication (malformed, unknown or revoked keys) from one IP is limited to about 10 per minute; after that the IP gets 429 too_many_auth_failures for a minute. If the service-wide daily capacity for failed key lookups is used up, a client that failed authentication within the last minute may get 503 daily_capacity_reached with Retry-After: 60; retry in a minute (the condition clears a minute after that client's last failed attempt). Clients without recent failures are not affected. While an IP is marked, a valid key it has not used recently also counts once toward its 10 per minute.
• Get a free key: curl -X POST https://workdayapi.mike-tusa.workers.dev/v1/keys (the key is shown once). Check usage: GET /v1/key. Sign-ups are limited to about 5 per minute and 5 per UTC day per IP (IPv6: per /64, and 15 per day per /48): 429 rate_limited (Retry-After: 60) or 429 signup_limit_reached (until 00:00 UTC).
• Request bodies are capped at 16 KB (413 payload_too_large). On GET endpoints only successful calls count toward your quota (validation errors are free). POST /v1/batch charges one call per submitted op, including ops that return an error.
• Send each query parameter once: a repeated parameter (e.g. country=US&country=DE) is rejected with 400 duplicate_parameter.
• Responses for the same inputs are deterministic and cacheable (Cache-Control: max-age=86400).

Common parameters

Parameter	Meaning
country	ISO 3166-1 alpha-2 code, e.g. US, DE. See GET /v1/countries.
region	Optional ISO 3166-2 subdivision where supported: DE-BY, GB-SCT… (BY also works). GB defaults to GB-ENG (England and Wales).
weekend	Optional override, e.g. fri,sat, sun or none. Default sat,sun.
types	Holiday types that are non-business days. Default public,bank; use public to ignore "bank" days (customary closures such as Christmas Eve in Sweden). observance days never block business days, so a list without public or bank (e.g. types=observance) is rejected with 400 invalid_types on the business-day endpoints (it is fine on /v1/holidays).

GET /v1/holidays

country, year, optional region, types. Lists the year's holidays. Moved holidays carry observed (for example a Saturday 1 January observed on Friday 31 December appears in both years).

curl "https://workdayapi.mike-tusa.workers.dev/v1/holidays?country=DE&year=2027&region=DE-BY"

{ "country": "DE", "region": "DE-BY", "year": 2027, "count": 12,
  "holidays": [ { "date": "2027-01-01", "name": "New Year's Day", "local_name": "Neujahr", "type": "public", "national": true }, … ] }

GET /v1/is-business-day

date, country, optional region, weekend, types.

curl "https://workdayapi.mike-tusa.workers.dev/v1/is-business-day?date=2026-12-28&country=GB"
{ "date": "2026-12-28", "business_day": false, "reason": "observed_holiday",
  "holiday": { "name": "Boxing Day (observed)", "type": "public", "actual_date": "2026-12-26" },
  "previous_business_day": "2026-12-24", "next_business_day": "2026-12-29", … }

reason is one of business_day, weekend, holiday, observed_holiday. At the edges of the supported range (2020-01-01, 2035-12-31) a neighbour that would fall outside it is null.

GET /v1/add

date, days (integer, negative counts backwards, |days| ≤ 2500), country, optional region, weekend, types. The start date itself is never counted; days=0 returns the date if it is a business day, otherwise the next one.

curl "https://workdayapi.mike-tusa.workers.dev/v1/add?date=2026-12-22&days=5&country=US"
{ "date": "2026-12-22", "days": 5, "result": "2026-12-30", "result_weekday": "wednesday", "calendar_days": 8,
  "skipped_holidays": [ { "date": "2026-12-25", "name": "Christmas Day", "type": "public" } ], … }

GET /v1/between

from, to, country, optional inclusive=true, region, weekend, types. Counts the days after from up to and including to (so between(from, add(from, n)) = n); inclusive=true also counts from. If to is before from the counts are negative. holiday_days counts holidays (including any on weekends); weekend_days counts the other weekend days.

curl "https://workdayapi.mike-tusa.workers.dev/v1/between?from=2026-12-01&to=2026-12-31&country=FR"
{ "business_days": 21, "calendar_days": 30, "weekend_days": 8, "holiday_days": 1, "holidays": [ … ] }

POST /v1/batch Pro key

Up to 100 operations per call (each submitted op counts as one call, including ops that return an error), using at most 10 distinct calendars (a calendar = country + region + types + weekend). Body ≤ 16 KB. Batch responses are compact JSON; per-day lists (holidays for between, skipped_holidays for add) are replaced by holidays_count / skipped_holidays_count unless the op sets "details": true (at most 10 ops per batch). Errors: 422 too_many_ops, too_many_calendars, too_many_details (rejected batches are not charged).

curl -X POST https://workdayapi.mike-tusa.workers.dev/v1/batch -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"ops":[{"op":"add","date":"2026-10-05","days":10,"country":"US"},{"op":"between","from":"2026-01-01","to":"2026-12-31","country":"DE","region":"DE-BY"}]}'
{ "count": 2, "results": [ { "index": 0, "ok": true, "result": { … } }, { "index": 1, "ok": true, "result": { … } } ] }

GET /v1/countries, GET /v1/meta, GET /health

Supported countries with regions, scope, notes and official sources; service version, data version and limits.

{ "error": { "code": "invalid_date", "message": "\"date\" must be a calendar date in YYYY-MM-DD format." }, "docs": "/docs" }

400 invalid or missing parameter / duplicate_parameter / invalid_types · 401 invalid_api_key / api_key_required · 403 plan_required · 404 unknown_country / unknown_region / not_found · 405 method_not_allowed · 413 payload_too_large · 422 year_out_of_range / date_out_of_range / result_out_of_range / too_many_ops / too_many_calendars / too_many_details · 429 rate_limited / monthly_quota_exceeded / too_many_auth_failures (all with Retry-After) · 503 daily_capacity_reached.

Data provided as-is, without warranty. Holidays are computed from rules (fixed dates, Easter, n-th weekday, substitute-day rules) that WorkdayAPI wrote from official government sources; no third-party holiday dataset is bundled. Governments sometimes declare one-off holidays at short notice and many rules have regional exceptions, so verify critical deadlines with the official source. WorkdayAPI is not legal, payroll or financial advice; do not rely on it alone for statutory, payroll, tax or contractual deadlines. Types: public = statutory holiday; bank = not statutory but banks/most businesses are closed (counted as non-business by default); observance = informational, still a business day. Entries marked "predicted": true follow past government practice but have not been officially declared for that year yet (e.g. South Africa's Tuesday substitute when Christmas falls on a Sunday).

Code	Country	Scope and notes	Official sources
AT	Austria	Gesetzliche Feiertage (Arbeitsruhegesetz §7) Good Friday has not been a holiday since 2019 (replaced by a personal day). 24 and 31 December are customary half days and are not included.	source 1, source 2
AU	Australia	National public holidays observed in every state and territory Only holidays common to all states and territories. State-only holidays (Easter Saturday, King’s Birthday, Labour Day, Melbourne Cup, etc.) are not included yet. Anzac Day has no national substitute (some states add one).	source 1, source 2, source 3
BE	Belgium	Ten legal public holidays (FPS Employment) A holiday on a Sunday (or usual rest day) is replaced by a day chosen per company/sector, so no fixed observed dates are added.	source 1, source 2
BR	Brazil	Feriados nacionais (Lei 662/1949 and amendments) plus bank holidays Carnival Monday/Tuesday and Corpus Christi are "pontos facultativos" (optional for the federal government) but banks are closed, so they are type "bank". State and municipal holidays are not included. Black Consciousness Day (20 Nov) is national from 2024.	source 1, source 2, source 3
CA	Canada	Federal general holidays (Canada Labour Code s.166; substitute days per s.195) Federal holidays only; provincial holidays (Family Day, Civic Holiday, Saint-Jean-Baptiste, etc.) are not included. Holidays falling on a weekend move to the next weekday (federal practice). Easter Monday is a federal public-service holiday only, so it is listed as an observance (business day).	source 1, source 2, source 3
CZ	Czechia	Státní svátky a ostatní svátky (zákon č. 245/2000 Sb.)	source 1, source 2
DE	Germany Regions: DE-BW, DE-BY, DE-BE, DE-BB, DE-HB, DE-HH, DE-HE, DE-MV, DE-NI, DE-NW, DE-RP, DE-SL, DE-SN, DE-ST, DE-SH, DE-TH	Gesetzliche Feiertage: nationwide plus per Bundesland Holidays are set by each Land; without ?region= only the nine nationwide holidays (per BMI) are returned. Holidays that apply only in some municipalities (Fronleichnam in parts of Sachsen/Thüringen, Mariä Himmelfahrt in Catholic communities of Bayern, Augsburger Friedensfest) are not included. Easter Sunday and Whit Sunday are listed for Brandenburg (they fall on Sundays).	source 1, source 2
DK	Denmark	Helligdage (folkekirkens helligdage; Store Bededag abolished from 2024) Constitution Day (5 June), Christmas Eve and New Year’s Eve are not public holidays by law; they are listed as observances.	source 1, source 2
EE	Estonia	Riigipühad (Pühade ja tähtpäevade seadus)	source 1
FI	Finland	Public holidays (church holidays, May Day, Independence Day) Midsummer Eve and Christmas Eve are not statutory holidays but are general days off and bank closing days (type "bank").	source 1, source 2
FR	France	Jours fériés (Code du travail art. L3133-1), metropolitan France Alsace-Moselle (Good Friday, 26 December) and overseas departments are not included. Whit Monday is a legal holiday but is also the default "journée de solidarité", so many employers work it.	source 1, source 2
GB	United Kingdom Regions: GB-ENG, GB-WLS, GB-SCT, GB-NIR	Bank holidays (gov.uk), per nation Without ?region= the England and Wales calendar (GB-ENG) is used. Substitute days follow gov.uk.	source 1, source 2
HR	Croatia	Blagdani i neradni dani (Zakon o blagdanima, NN 110/19)	source 1
IE	Ireland	Public holidays (Organisation of Working Time Act 1997, Schedule 2) Irish law gives no automatic substitute weekday when a holiday falls on a weekend (employees get a day off within a month, an extra leave day or pay instead), so no observed dates are added. Good Friday is not a public holiday (listed as an observance).	source 1, source 2
IS	Iceland	Frídagar (Lög nr. 88/1971, 6. gr.) Christmas Eve and New Year’s Eve are holidays from 13:00 only, so they are listed as observances (business days).	source 1
IT	Italy	Festività nazionali (L. 260/1949 and amendments) Local patron-saint days are not included. 4 October (San Francesco d’Assisi) is a national holiday from 2026 (Legge 8 ottobre 2025, n. 151).	source 1, source 2
JP	Japan	国民の祝日 (Act on National Holidays) incl. substitute and citizens’ holidays Equinox days are officially fixed each February for the following year; dates after the latest Cabinet Office announcement use the standard astronomical formula and could change. Bank holidays 2-3 January and 31 December are not included (banks close, but they are not national holidays).	source 1, source 2
LT	Lithuania	Švenčių dienos (Darbo kodeksas, 123 str.)	source 1
LU	Luxembourg	Jours fériés légaux (Code du travail L.232-2) A holiday on a Sunday gives employees a compensatory day within three months (not a fixed date), so no observed dates are added.	source 1
MX	Mexico	Días de descanso obligatorio (Ley Federal del Trabajo art. 74) plus CNBV bank holidays Holy Thursday, Good Friday, 2 November and 12 December are bank holidays set by the CNBV (type "bank"; 2026 list published in the DOF, later years assume the same pattern until published). Election-day rest days (always Sundays) are not included.	source 1, source 2
NL	Netherlands	Officiële feestdagen (Rijksoverheid) Dutch law gives no general right to a day off; Good Friday and Liberation Day are mostly working days, so they are listed as observances.	source 1
NO	Norway	Helligdager (helligdagsfredloven) and 1 and 17 May	source 1, source 2
NZ	New Zealand	National public holidays (Holidays Act 2003; Te Kāhui o Matariki Public Holiday Act 2022) Regional anniversary days are not included. Mondayisation applies to New Year, Waitangi, Anzac, Christmas and Boxing Day.	source 1, source 2
PL	Poland	Dni wolne od pracy (Ustawa z 18 stycznia 1951 r.) Christmas Eve (24 December) is a public holiday from 2025 (Dz.U. 2024 poz. 1965, in force 1 Feb 2025).	source 1, source 2
PT	Portugal	Feriados obrigatórios (Código do Trabalho art. 234) Carnival Tuesday is optional (listed as an observance). Municipal holidays are not included.	source 1, source 2
SE	Sweden	Allmänna helgdagar (Lag 1989:253) plus days treated as Sundays Midsummer Eve, Christmas Eve and New Year’s Eve are not statutory holidays but are treated like Sundays (e.g. Semesterlagen) and banks are closed, so they are type "bank".	source 1
SI	Slovenia	Prazniki in dela prosti dnevi (ZPDPD) Only work-free days are included (e.g. Reformation Day 31 Oct is work-free; Primož Trubar Day and other non-work-free holidays are omitted).	source 1, source 2, source 3, source 4
US	United States	Federal holidays (5 U.S.C. 6103; OPM observed-date rule) Saturday holidays are observed the preceding Friday and Sunday holidays the following Monday (federal employees). Inauguration Day (DC area only), one-off executive-order closures and state holidays are not included.	source 1, source 2
ZA	South Africa	Public holidays (Public Holidays Act 36 of 1994) A holiday on a Sunday moves to the Monday (Public Holidays Act s.2(1)). When that Monday is already a holiday (Christmas on a Sunday), the Act gives no further day; the President proclaimed Tuesday 27 December in 2011, 2016 and 2022, and later cases (2033-12-27) are listed as predicted until proclaimed. One-off holidays declared under s.2A (election days, 15 Dec 2023, 4 Nov 2026 local government elections, Proclamation 346 of 2026) are included; future ones are added when proclaimed.	source 1, source 2, source 3, source 4