UK Bank Holidays & Business Day Calculator

UK Bank Holidays & Business Day Calculator lists UK bank holidays from GOV.UK for England and Wales, Scotland and Northern Ireland. It also adds or counts business days for your dates, with substitute days, custom weekends and your own closure dates. You get one clean row per holiday or per calculation.

It is made for finance, payroll and operations teams, and for developers and AI agents that need the correct UK working day. No login and no API key are needed. The form example (all 2026 holidays for the three UK divisions) finishes in a few seconds and costs about $0.0066.

Contents

• What it does
• Quick start
• Use cases
• Input
• Output
• Pricing
• Limits
• API and integrations
• Troubleshooting
• FAQ
• Data source and licence
• Support

What it does

The Actor reads the public UK bank holidays feed on GOV.UK once per run. GOV.UK publishes three separate calendars, called divisions: england-and-wales, scotland and northern-ireland. The Actor has two modes:

• list: one row per bank holiday, division and year. Substitute days (for example Boxing Day moved to Monday 28 December 2026) are marked with isSubstituteDay.
• calculate: up to 100 calculations per run. Each calculation either adds a number of business days to a start date (addBusinessDays, negative goes back in time) or counts business days between two dates (endDate). You get one row per calculation and division, with the result date and the holidays it skipped.

A business day is a day that is not a weekend day (weekendDays, default Saturday and Sunday), not a GOV.UK bank holiday of that division and not one of your extraHolidays.

Good fit

• Find an invoice due date or a payment date "N working days" after a date.
• Check an SLA or a notice period: how many business days are between two dates.
• Compare Scotland, Northern Ireland and England and Wales for the same date.
• Get the list of UK bank holidays for a calendar, a payroll system or a test fixture.
• Use a Friday–Saturday weekend or add your own office closure days.

Not a fit

• Other countries, local holidays or regional events. Only the three GOV.UK divisions are used.
• Years that GOV.UK has not published yet (now 2019–2028). The Actor never invents future holidays: see partial results.
• Court deadlines or legal time limits (for example Civil Procedure Rules). Check legal rules with a lawyer.
• Business hours or time zones. The Actor works with calendar dates (YYYY-MM-DD).

Quick start

1. Open the Input tab. The form already has List bank holidays, all three divisions and the year 2026.
2. Click Start.
3. Open the Bank holidays view in the Output tab. Check division, date, title and isSubstituteDay.
4. To calculate dates, choose Calculate business days in Mode. The form already has two example calculations. Click Start and open the Business-day calculations view. Check resultDate and businessDays.

Expected result: 28 holiday rows for 2026 (8 for England and Wales, 10 for Scotland, 10 for Northern Ireland) in a few seconds.

Use cases

Buyer job	Input	Output	Key fields
Invoice or payment due date	calculate + addBusinessDays	calculation row	resultDate, holidaysSkipped, calendarDays
SLA or notice period check	calculate + endDate	calculation row	businessDays, weekendDaysSkipped, holidaysSkippedCount
Scotland vs England dates	divisions (several)	one row per division	division, resultDate
Holiday calendar or payroll import	list + years	holiday rows	date, title, isSubstituteDay, division
Company with own closure days	extraHolidays, weekendDays	both modes	holidaySource (custom), holidaysSkipped

Input

Field	Type	Default	Allowed values	What it does
mode	string	list	list, calculate	List holidays, or run the calculations.
divisions	array of strings	all three (form: all three)	england-and-wales, scotland, northern-ireland	Which UK calendars to use. Empty means all three.
years	array of integers	every published year (form: 2026)	up to 50 years, 1900–2100	List mode only. Years to list. A year that GOV.UK has not published gives no rows and a warning in the run summary.
calculations	array of objects	none (form: 2 examples)	1–100 objects	Calculate mode only, required. See below.
weekendDays	array of strings	saturday, sunday	weekday names; not all seven	Days that are never business days.
extraHolidays	array of strings or objects	empty	up to 500	Your own non-working dates, added on top of GOV.UK holidays. Used in both modes.

Calculation object

Key	Type	Required	What it does
startDate	string YYYY-MM-DD	yes	The date you start from. It is never counted itself.
addBusinessDays	integer, −2000 to 2000	one of the two	Add this many business days. +1 from a Friday gives the next business day (usually Monday). A negative number goes back. 0 keeps the start date if it is a business day, or moves forward to the next business day.
endDate	string YYYY-MM-DD	one of the two	Count business days after startDate up to and including endDate. If endDate is earlier, the count is negative.
id	string	no	Your label, copied to calculationId. Default: the position in the list (1, 2, …).
division	string	no	Use only this division for this calculation. Without it, the calculation runs once for each selected division.

Set exactly one of addBusinessDays and endDate. A wrong calculation (for example 2026-02-30 or both keys) becomes one free error row, and the other calculations still run. The same calculation written twice gives two rows.

Extra holidays

Write a date, or an object with a title and divisions:

["2026-12-31", { "date": "2026-12-29", "title": "Office closed", "divisions": ["scotland"] }]

Without divisions, the date applies to every division. In list mode, extra holidays appear as rows with holidaySource: "custom", only for the selected years when you set them.

Input examples

All 2026 bank holidays (the form example):

{
  "mode": "list",
  "divisions": ["england-and-wales", "scotland", "northern-ireland"],
  "years": [2026]
}

Due dates over Christmas, with an office closure on 31 December in England and Wales:

{
  "mode": "calculate",
  "divisions": ["england-and-wales", "scotland"],
  "extraHolidays": [{ "date": "2026-12-31", "title": "Office closed", "divisions": ["england-and-wales"] }],
  "calculations": [
    { "id": "invoice-due", "startDate": "2026-12-24", "addBusinessDays": 10 },
    { "id": "sla-window", "startDate": "2026-11-27", "endDate": "2026-12-04", "division": "scotland" },
    { "id": "back-5", "startDate": "2027-01-05", "addBusinessDays": -5, "division": "northern-ireland" }
  ]
}

Results of this run: invoice-due is 2027-01-13 in both divisions (England and Wales skips the closure day, Scotland skips 2 January's substitute day on 4 January). sla-window has 4 business days, because St Andrew's Day (30 November) is a Scottish bank holiday. back-5 gives 2026-12-24.

Output

Each Dataset row has recordType: holiday or calculation. Use the Bank holidays and Business-day calculations views, or filter on recordType in your export. The key-value store has a RUN_SUMMARY record with the run status and counts.

Row status

status	Meaning	Charged
complete	The holiday, or a calculation fully inside the years GOV.UK has published.	yes
partial	The calculation touches a year GOV.UK has not published. Only weekends and your extraHolidays are used for that year, so the result can change later. Read coverageWarning.	yes
error	The calculation input is not valid. statusReason says what to fix.	no

Holiday fields

Field	Meaning	Example
division, divisionName	Division key and name	"scotland", "Scotland"
date, year, dayOfWeek	Holiday date	"2027-01-01", 2027, "friday"
title	Holiday name as GOV.UK writes it (with a curly apostrophe ’)	"New Year’s Day"
notes	GOV.UK note, empty string when there is none	"Substitute day"
isSubstituteDay	true when the note says it is a substitute day	false
bunting	GOV.UK flag, passed as it is; null for your extra holidays	true
holidaySource	gov.uk or custom (from extraHolidays)	"gov.uk"
status	Always complete for holiday rows
sourceUrl, fetchedAt	Source and read time

Calculation fields

Field	Meaning	Can be null?	Example
calculationId	Your id or the position	no	"invoice-due"
division, divisionName	Division of this row	on error rows	"england-and-wales"
operation	add_business_days or count_business_days	on error rows	"add_business_days"
startDate, startDayOfWeek, startIsBusinessDay	Your start date	on some error rows	"2026-12-24", "thursday", true
addBusinessDays, endDate	Your input; the other one is null	yes	10, null
resultDate, resultDayOfWeek, resultIsBusinessDay	Result date (for add) or your endDate (for count)	on error rows	"2027-01-12", "tuesday"
businessDays	Business days moved or counted; negative when going back	on error rows	10
calendarDays	Calendar days from start to result	on error rows	19
weekendDaysSkipped	Weekend days passed over	on error rows	4
holidaysSkippedCount	Holiday dates on working weekdays passed over (one date with two titles counts once)	on error rows	3
holidaysSkipped	List of {date, title, source} for those holidays	empty list on error rows	see example
weekendDays	Weekend days used	no	["sunday", "saturday"]
coverageWarning, uncoveredYears	Why a row is partial, and which years were missing	null / empty when covered	[2029]
publishedYears	First and last year GOV.UK publishes for this division	on error rows	{"first": 2019, "last": 2028}
status, statusReason, errorCode	Row result, see above; errorCode is INVALID_CALCULATION on error rows	reason and code only when needed	"complete"
sourceUrl, fetchedAt	Source and read time

A holiday on a weekend day counts as a weekend day, not as a holiday, because the day is not a business day anyway. GOV.UK then adds a substitute weekday, and that day is skipped as a holiday.

Output example

The invoice-due calculation from the form, England and Wales:

{
  "recordType": "calculation",
  "status": "complete",
  "calculationId": "invoice-due",
  "division": "england-and-wales",
  "operation": "add_business_days",
  "startDate": "2026-12-24",
  "addBusinessDays": 10,
  "endDate": null,
  "resultDate": "2027-01-12",
  "resultDayOfWeek": "tuesday",
  "businessDays": 10,
  "calendarDays": 19,
  "weekendDaysSkipped": 6,
  "holidaysSkippedCount": 3,
  "holidaysSkipped": [
    { "date": "2026-12-25", "title": "Christmas Day", "source": "gov.uk" },
    { "date": "2026-12-28", "title": "Boxing Day", "source": "gov.uk" },
    { "date": "2027-01-01", "title": "New Year’s Day", "source": "gov.uk" }
  ],
  "coverageWarning": null,
  "uncoveredYears": [],
  "publishedYears": { "first": 2019, "last": 2028 }
}

This example is trimmed. In Scotland the same calculation gives 2027-01-13, because 4 January 2027 is the substitute day for 2 January.

Run summary

RUN_SUMMARY.status is one of COMPLETE, PARTIAL (some rows are partial, or some requested years are not published), NO_RESULTS (no holidays for the requested years), CAPPED (stopped at your maximum charge), ERROR (GOV.UK did not answer or changed its format), INVALID_INPUT or CANCELLED. It also shows counts, the published years per division, the source licence and the time of the GOV.UK read.

Pricing

Pay per event. Platform usage is included.

Event	Price (free plan)	When
Actor start	$0.001	Once per run (per GB of memory; the default 256 MB counts once)
Calculation row	$0.0018	Each complete or partial calculation row
Holiday row	$0.0002	Each holiday row

Paid Apify plans get a lower row price: Bronze $0.0017 / $0.00019, Silver $0.0016 / $0.00018, Gold $0.0015 / $0.00017 (calculation / holiday row). error rows are free. A run with no paid rows (for example a year GOV.UK has not published, or invalid input) costs only the start.

Run	Rows	Example cost (free plan)
All 2026 holidays, 3 divisions (form example)	28	$0.0066
All published years, 3 divisions	280	$0.057
1 calculation, 1 division	1	$0.0028
2 form calculations, 3 divisions	4	$0.0082
100 calculations, 1 division	100	$0.181
100 calculations, 3 divisions	300	$0.541

Set a maximum cost per run in the run options to cap your spend. The Actor stops before a paid row that does not fit and reports CAPPED.

Limits

• Up to 100 calculations per run. Each one runs once per selected division, so 100 calculations × 3 divisions give 300 rows. In our tests this took about 3 seconds.
• addBusinessDays from −2000 to 2000; startDate and endDate at most 36,600 days apart; dates from 1900 to 2100.
• Up to 500 extraHolidays and 50 years.
• Bank holidays exist only for the years GOV.UK publishes (now 2019–2028). GOV.UK adds new years about a year or two ahead and can remove old years. Every run reads the current list.
• The Actor reads GOV.UK once per run. If GOV.UK is down, the run fails with ERROR instead of giving an empty or wrong result.

API and integrations

Start a run with the same JSON input through the Apify API (POST /v2/acts/cliqtomedia~uk-bank-holidays-business-days/runs), then read the Dataset. Export to CSV, Excel or JSON from the Dataset, or connect the run to other tools with the usual Apify integrations. For CSV, use the Bank holidays or Business-day calculations view.

Join calculation rows to your records on calculationId. To refresh a holiday calendar each month, create an Apify schedule for a saved task in list mode.

Use with AI agents (MCP)

AI agents can call this Actor through the Apify MCP server: add https://mcp.apify.com?tools=cliqtomedia/uk-bank-holidays-business-days to your MCP client (Claude, Cursor, VS Code and others). The MCP server needs your Apify account (OAuth sign-in or an Apify API token); GOV.UK needs no key. The agent builds the input from the input schema. A small calculation:

{ "mode": "calculate", "divisions": ["england-and-wales"], "calculations": [{ "startDate": "2026-12-24", "addBusinessDays": 10 }] }

Key output fields for an agent: status (complete, partial or error), resultDate, businessDays, holidaysSkipped, coverageWarning. A call usually finishes in a few seconds and costs under $0.01 for a few rows. Up to 100 calculations fit in one run. A partial row means GOV.UK has not published that year yet, so the date can change later.

Troubleshooting

Symptom	Check	Action
A row is partial	coverageWarning, uncoveredYears	The date range reaches a year GOV.UK has not published. Use the result as an estimate, or run again after GOV.UK publishes that year.
An error row (errorCode: "INVALID_CALCULATION")	statusReason	Fix that calculation, for example the date format YYYY-MM-DD or exactly one of addBusinessDays and endDate.
No rows in list mode	RUN_SUMMARY.uncoveredRequestedYears, warnings	The years you asked for are not published. Choose a year from coverage.
A different date than another tool	division, holidaysSkipped, weekendDays	Check the division (Scotland and Northern Ireland have other holidays) and that the start date is not counted.
INVALID_INPUT (run failed)	RUN_SUMMARY.message	Common causes: calculate mode without calculations, more than 100 calculations, every calculation is wrong (the free error rows show why), all seven days in weekendDays. Only the start is charged.
ERROR (run failed)	RUN_SUMMARY.message, warnings, http	GOV.UK did not answer or sent data in an unknown format. No rows are written or charged. Run again later.

FAQ

Do I need an API key or a GOV.UK account?

No. The GOV.UK feed is open and free. You only need your Apify account.

Does the Actor count the start date?

No. +1 business day from Thursday is Friday. When you count between two dates, the start date is not counted and the end date is counted.

Why are Scotland and England different?

They have different bank holidays. For example, Scotland has 2 January, St Andrew's Day and, in 2026, the one-off World Cup bank holiday (15 June); Northern Ireland has St Patrick's Day and 12 July. Wales uses the England and Wales calendar.

What about holidays on a weekend?

GOV.UK moves them to a substitute weekday, for example Boxing Day 2026 to Monday 28 December. The Actor uses the GOV.UK dates as they are.

How fresh is the data?

Each run reads GOV.UK live. Each row has fetchedAt, and RUN_SUMMARY.source keeps the read time. GOV.UK can also add one-off holidays; the next run picks them up.

Data source and licence

Data: UK bank holidays on GOV.UK (JSON feed). Contains public sector information licensed under the Open Government Licence v3.0. When you reuse the data, keep this attribution. This Actor is independent and not endorsed by GOV.UK or the UK Government.

Support

Use the Issues tab of this Actor. Add the run ID, the mode (list or calculate) and the statusReason or errorCode you saw. Do not send API tokens or private data.