Anvil › Docs › /v1/holidays/next

Next bank holiday API: how many days until the next holiday

The next few holidays after a date, each with how many days away it is. Perfect for a "next bank holiday in 12 days" line on a dashboard, an intranet or a chat bot.

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

GET

`/v1/holidays/next`

The next few holidays from today (or a date). Change the values and press Send request to call the live API.

region requiredRegion code

fromStart date, YYYY-MM-DD

count1 to 20

setFor Canada: observed or statutory

Parameters

Name	Type	What it does	Default
`region` required	string	Region code 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	—
`from`	string	Start date, YYYY-MM-DD	`today`
`count`	integer	1 to 20	`3`
`set`	string	For Canada: observed or statutory	—

Example

Request:

GET https://api.oddlathe.com/v1/holidays/next?region=ca-on&set=statutory&count=3

Response (generated by the real code when these docs were last built; random or time-based values will differ for you):

{
 "region": "ca-on",
 "from": "2026-11-12",
 "set": "statutory",
 "holidays": [
  {
   "date": "2026-12-25",
   "weekday": "Friday",
   "name": "Christmas Day",
   "actual_date": "2026-12-25",
   "substitute": false,
   "days_away": 43
  },
  {
   "date": "2026-12-28",
   "weekday": "Monday",
   "name": "Boxing Day (substitute day)",
   "actual_date": "2026-12-26",
   "substitute": true,
   "days_away": 46
  },
  {
   "date": "2027-01-01",
   "weekday": "Friday",
   "name": "New Year's Day",
   "actual_date": "2027-01-01",
   "substitute": false,
   "days_away": 50
  }
 ]
}

Code examples

curl

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

JavaScript (browser or Node 18+)

const params = new URLSearchParams({
  region: "ca-on",
  set: "statutory",
  count: "3"
});
const res = await fetch(`https://api.oddlathe.com/v1/holidays/next?${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", "set": "statutory", "count": "3"})
url = "https://api.oddlathe.com/v1/holidays/next?" + 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

Countdown widgets
Reminders to prepare cover before a long weekend
Chat bot answers to "when's the next bank holiday?"

Good to know

from defaults to today (UK date). A holiday on the from date itself counts, with days_away: 0.
Looks up to three years ahead.
Canadian regions accept set=statutory for employment-standards holidays (same meaning as on /v1/holidays).

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

Does it know about holidays announced at short notice?

Only once they are added to the rules here. See the accuracy note on the About page.

Related endpoints

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