AnvilJSON utilities

Anvil › Docs › /v1/holidays.ics

Bank holidays calendar feed (iCal): subscribe in Google, Apple or Outlook

Want bank holidays in your own calendar without installing anything or signing up? Subscribe to this URL once. It is a standard iCalendar (.ics) feed with one all-day event per holiday, covering last year, this year and the next two, and it rolls forward by itself every new year.

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

/v1/holidays.ics

Subscribe to bank holidays in any calendar app (iCalendar feed). Change the values and press Send request to call the live API.



Parameters
NameTypeWhat it doesDefault
region requiredstringgb-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		—
fromintegerFirst year, 1990 to 2100last year
yearsintegerHow many years, 1 to 64
setstringFor Canada: observed or statutory—


Example
Request:
GET https://api.oddlathe.com/v1/holidays.ics?region=ca-on&set=statutory


Response (generated by the real code when these docs were last built):
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//oddlathe//Anvil holidays//EN
CALSCALE:GREGORIAN
METHOD:PUBLISH
X-WR-CALNAME:Statutory holidays: Canada — Ontario
X-WR-CALDESC:Statutory holidays for Canada — Ontario\, 2025–2028. Calcu
 lated from the published rules by api.oddlathe.com. Check the official sou
 rce for legal deadlines.
REFRESH-INTERVAL;VALUE=DURATION:P1D
X-PUBLISHED-TTL:P1D
BEGIN:VEVENT
UID:[email protected]
DTSTAMP:20261112T000000Z
DTSTART;VALUE=DATE:20250101
DTEND;VALUE=DATE:20250102
SUMMARY:
 …


Code examples
curl
curl 'https://api.oddlathe.com/v1/holidays.ics?region=ca-on&set=statutory'
JavaScript (browser or Node 18+)
const params = new URLSearchParams({
  region: "ca-on",
  set: "statutory"
});
const res = await fetch(`https://api.oddlathe.com/v1/holidays.ics?${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"})
url = "https://api.oddlathe.com/v1/holidays.ics?" + 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
  • Seeing bank holidays next to your own events in Google Calendar, Apple Calendar or Outlook
  • Shared team calendars that need the right Scottish or Northern Irish holidays, not just England's
  • Rota and booking tools that can import an .ics URL
  • Scripts that want a ready-made calendar file (curl the URL to holidays.ics)


Good to know
  • Google Calendar: Other calendars → + → From URL, paste the feed URL. Apple Calendar: File → New Calendar Subscription. Outlook: Add calendar → Subscribe from web. Use the full https URL, for example https://api.oddlathe.com/v1/holidays.ics?region=gb-sct.
  • Regions: UK nations, ie, us, de/de-by…, fr, nl, ca/ca-on…, au/au-nsw…, nz.
  • from (default last year) and years (1–6, default 4) set the span. Leave them out for a feed that rolls forward automatically each January.
  • Each event has a stable UID, so calendar apps update rather than duplicate when they refresh. Weekend holidays appear on their substitute weekday, with the original date in the description. Add set=statutory for a Canadian employment-standards calendar (see /v1/holidays).
  • Response Content-Type is text/calendar, not JSON. For JSON use /v1/holidays.
  • Calendar apps fetch the feed from their own servers, so nothing about you is sent here. Nothing is stored or logged.


Returns text/calendar (RFC 5545) with one all-day event per holiday, stable UIDs and a daily refresh hint. Paste the URL into Google Calendar (From URL), Apple Calendar (New Calendar Subscription) or Outlook (Subscribe from web). Same rules as /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
How often does my calendar update?
That is up to the app: Google refreshes subscribed calendars roughly every 12–24 hours, Apple lets you choose, Outlook every few hours. The feed asks for daily.
Why is the 28 December a holiday in 2026?
Boxing Day falls on a Saturday, so the UK substitute day is the following Monday. The event description says so.
Does it include one-off holidays like a coronation?
Yes, once they have been officially announced. Future one-offs appear only after they are proclaimed.
Is anything stored?
Never. The feed is calculated on each request.


Related endpoints


Prefer a page to an API?


Published , updated  · OpenAPI 3.1 spec · Limits and privacy