Anvil › Docs › /v1/holidays

Bank holidays API: UK, IE, US, DE(+states), FR, NL, CA(+provinces), AU(+states), NZ

Bank and public holidays for a whole year as clean JSON: date, weekday and name. Regions: UK nations (gb-eng/gb-wls/gb-sct/gb-nir), ie, us, Germany de plus de-bw…de-th, fr, nl, Canada ca plus ca-ab…ca-yt (13 provinces/territories), Australia au plus au-act…au-wa (8 states/territories), and nz.

In one line: GET /v1/holidays?region=ca-on&year=2026&set=statutory returns JSON. No key, CORS on, 60 requests a minute.

GET

`/v1/holidays`

Public / bank holidays for a year. Change the values and press Send request to call the live API.

region requiredgb-eng…, ie, us, de/de-by…, fr, nl, ca/ca-on…, au/au-nsw…, nz

year1990 to 2100

setFor Canada: observed (federal + extras, default) or statutory (employment-standards list)

Parameters

Name	Type	What it does	Default
`region` required	string	gb-eng…, ie, us, de/de-by…, fr, nl, ca/ca-on…, au/au-nsw…, nz Allowed: gb-eng, gb-wls, gb-sct, gb-nir, ie, us, de, 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, ca, ca-ab, ca-bc, ca-mb, ca-nb, ca-nl, ca-ns, ca-nt, ca-nu, ca-on, ca-pe, ca-qc, ca-sk, ca-yt, au, au-act, au-nsw, au-nt, au-qld, au-sa, au-tas, au-vic, au-wa, nz, fr, nl	—
`year`	integer	1990 to 2100	`this year`
`set`	string	For Canada: observed (federal + extras, default) or statutory (employment-standards list)	—

Example

Request:

GET https://api.oddlathe.com/v1/holidays?region=ca-on&year=2026&set=statutory

Response (generated by the real code when these docs were last built):

{
 "region": "ca-on",
 "region_name": "Canada — Ontario",
 "year": 2026,
 "set": "statutory",
 "count": 9,
 "holidays": [
  {
   "date": "2026-01-01",
   "weekday": "Thursday",
   "name": "New Year's Day",
   "actual_date": "2026-01-01",
   "substitute": false
  },
  {
   "date": "2026-02-16",
   "weekday": "Monday",
   "name": "Family Day",
   "actual_date": "2026-02-16",
   "substitute": false
  },
  {
   "date": "2026-04-03",
   "weekday": "Friday",
   "name": "Good Friday",
   "actual_date": "2026-04-03",
   "substitute": false
  },
  {
   "date": "2026-05-18",
   "weekday": "Monday",
   "name": "Victoria Day",
   "actual_date": "2026-05-18",
   "substitute": false
  },
  {
 …

Code examples

curl

curl 'https://api.oddlathe.com/v1/holidays?region=ca-on&year=2026&set=statutory'

JavaScript (browser or Node 18+)

const params = new URLSearchParams({
  region: "ca-on",
  year: "2026",
  set: "statutory"
});
const res = await fetch(`https://api.oddlathe.com/v1/holidays?${params}`);
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();
console.log(data);

Python (standard library only)

import json, urllib.parse, urllib.request

params = urllib.parse.urlencode({"region": "ca-on", "year": "2026", "set": "statutory"})
url = "https://api.oddlathe.com/v1/holidays?" + params
# Send a User-Agent: the edge network refuses Python's default one.
req = urllib.request.Request(url, headers={"User-Agent": "my-script/1.0"})
with urllib.request.urlopen(req, timeout=10) as r:
    data = json.load(r)
print(data)

When it's useful

Skipping holidays in billing, shipping or SLA calculations
Shading holidays in a calendar or rota
Planning sprint lengths and release dates

Good to know

Holidays are calculated from the rules: Easter by the Gregorian computus, "first Monday in May"-style rules, and substitute days when a holiday falls at a weekend.
Known UK one-offs (jubilees, royal weddings and funerals, the 2020 VE Day move) and Ireland's St Brigid's Day from 2023 are included. A future one-off appears only after it's announced.
US dates include the observed weekday when the holiday falls on a weekend, for example 3 July 2026 for Independence Day.
Germany de returns the nine nationwide holidays (plus the one-off Reformation Day in 2017). Pass a state code such as de-by (Bavaria) or de-nw (NRW) to include that state's extras: Epiphany, Women's Day, Corpus Christi, Assumption, World Children's Day, Reformation Day, All Saints and Saxony's Buß- und Bettag. Holidays that apply only in some municipalities (Fronleichnam in parts of Saxony/Thuringia) are omitted. Bavaria's Assumption Day is listed statewide even though it only binds in predominantly Catholic communities.
France and Germany have no substitute days: a holiday that falls on a weekend is simply lost. France excludes the Alsace-Moselle extras (Good Friday, 26 December). Whit Monday is still listed for France although many employers treat it as the unpaid solidarity day.
Netherlands follows the Algemene termijnenwet list, so Easter Sunday and Whit Sunday appear, and King's Day moves to Saturday 26 April when 27 April is a Sunday. Liberation Day (5 May) is listed every year, but whether it is a paid day off depends on your employment contract. Good Friday is not included because it is not a national holiday there.
Canada ca follows the federal Canada Labour Code set (including National Day for Truth and Reconciliation from 2021). Weekend holidays move to the nearest weekday (Saturday→Friday, Sunday→Monday), walking forward past clashes — so Boxing Day 2026 is Monday 28 December. Province codes such as ca-on or ca-qc default to that federal set plus commonly listed extras (Family Day, Civic Holiday, Saint-Jean-Baptiste, Easter Monday, and the territorial days). That over-counts for most provincially regulated workplaces: Ontario's Employment Standards Act has nine public holidays, and Civic Holiday, Remembrance Day and the National Day for Truth and Reconciliation are not among them. Pass set=statutory to get the employment-standards list for that province or territory (Ontario 9, Quebec 8, Nova Scotia 6, and so on). set=observed is the default and keeps the older federal-plus-extras behaviour. Yukon's August holiday is Discovery Day (the third Monday), not the first-Monday Civic Holiday.
Australia au lists the nationwide set (New Year's, Australia Day, Good Friday, Easter Monday, Anzac Day, Christmas, Boxing Day). When New Year's, Christmas or Boxing Day fall on a weekend the weekend date is kept and an additional day is added on the next free weekday. Australia Day is different: on a weekend it moves to the following Monday as a substitute day and the weekend date is not a public holiday (next: Monday 28 January 2030). State codes add Easter Saturday/Sunday, King's Birthday (June in most states; October in Queensland; late September in WA), Labour Day, Melbourne Cup, Canberra Day, and Anzac additional Mondays where that state observes them. Half-day Christmas Eve / New Year's Eve holidays and city-only show days are omitted.
New Zealand nz includes Waitangi Day, Anzac Day, King's Birthday, Labour Day and Matariki (gazetted Fridays 2022–2052). Weekend New Year / Waitangi / Anzac / Christmas / Boxing Day holidays are mondayised.

Calculated from the published rules (Easter by the Gregorian computus, 'first Monday' rules, substitute days) plus known one-off UK and Irish proclamations. Future one-off holidays appear only once announced, so check the official source for legal deadlines.

Errors

Errors are JSON like {"error": {"code": "…", "message": "…"}}. The ones this endpoint can return:

missing_param (400): a required parameter is missing or empty
bad_param (400): a value is the wrong type or out of range (the message says which)
rate_limited (429): over 60 requests a minute; wait for Retry-After seconds

Questions

Why do Scotland and England differ?

Scotland has 2 January and St Andrew's Day (30 November) and no Easter Monday; England and Wales have Easter Monday and the late-August holiday on a different week.

Can I rely on this for legal deadlines?

It follows the published rules, but governments can add or move days. Check the official source for anything with legal or financial weight.

Is there an iCal feed?

Yes: <a href="/docs/holidays-ics"><code>/v1/holidays.ics</code></a>.

What does set=statutory do?

For Canadian regions it returns that jurisdiction's employment-standards paid holidays instead of the federal set plus extras. Ontario then has nine days (no Civic Holiday, Remembrance Day or National Day for Truth and Reconciliation). Other countries ignore the parameter.

Related endpoints

Prefer a page to an API?

Bank holidays list with countdown and calendar subscribe on Tooltern: same job, nothing leaves your browser.

Published 3 November 2026, updated 8 November 2026 · OpenAPI 3.1 spec · Limits and privacy