UK Bank Holidays & Working Day Calendar
Pricing
$1.00 / 1,000 holidays
UK Bank Holidays & Working Day Calendar
UK bank-holiday calendar from GOV.UK for England/Wales, Scotland and Northern Ireland. Export holiday rows or derived working-day flags and inclusive counts as JSON with source notes.
Get official GOV.UK bank holidays for England/Wales, Scotland and Northern Ireland, or derive daily working-day flags and inclusive working-day counts from the same feed.
What it does
The actor fetches GOV.UK bank-holidays.json once on a successful run. Transient network failures, HTTP 429 and server errors receive sequential retries with 1-second and 2-second backoff, up to three attempts. It preserves substitute-day notes, the official bunting boolean and special holidays rather than recomputing holiday dates.
Choose holidays for official events, calendar for one row per date, or working-days for a count summary per selected division. England and Wales share one official division. Selecting all keeps the three calendars separate.
A requested year must be present in the live feed for the selected division. A range checks every calendar year it touches, including internal gaps. Unavailable years fail with the available years; the actor does not invent future holidays. A valid range without holidays can return an empty holiday dataset.
Input
The prefilled example is:
| Input | Meaning | Default / limits |
|---|---|---|
| division | england-and-wales, scotland, northern-ireland or all | england-and-wales |
| year | Optional year filter; must exist in the source | Omitted means all source years; prefill is 2026 |
| mode | holidays, calendar or working-days | holidays |
| startDate, endDate | ISO YYYY-MM-DD bounds, both inclusive; supply together | Required for calendar and working-days; optional holiday filter; at most 366 days |
| weekend | saturday-sunday, friday-saturday, sunday-only or none | saturday-sunday |
| includeWeekdayFlags | Add derived flags and weekend assumptions to holiday rows | false; calendar mode always has flags |
| maxItems | Global dataset cap across divisions, including error rows | 1000; 1–10000; prefill is 10 |
When year and a range are both supplied, both endpoints must lie in that year. Omit year to use a range crossing two supported years. Numeric strings, invalid dates, unsupported options and unknown input keys are rejected clearly.
Working-day count example:
In the recorded local run this produced 7 calendar days, 2 weekend days, 1 bank-holiday date and 4 working days. Changing weekend to none produced 6 working days. These observations are saved in evidence/observations.json.
Output fields
The default dataset contains one of four record types. The actor output links to its dataset items. Missing fields for another record type are omitted, not filled with guessed values.
| Common field | Meaning |
|---|---|
| recordType | holiday, calendar, working-days or error |
| division | Official division identifier |
| errors | Empty list on a successful row; readable messages on an uncharged error row |
| sourceName, sourceUrl | GOV.UK and the official JSON feed URL |
| fetchedAt | UTC retrieval timestamp for the run |
| copyright | © Crown copyright |
| licence, licenceUrl | Open Government Licence v3.0 and its full URL |
| attribution | Public-sector information, OGL and Crown/GOV.UK attribution |
| Holiday field | Meaning |
|---|---|
| title | Official title with Unicode compatibility normalization and collapsed whitespace; punctuation is retained |
| date, year | ISO holiday date and integer year |
| notes | Official notes with normalized whitespace, including Substitute day |
| bunting | Official true/false value; not inferred |
| Derived daily / optional holiday field | Meaning |
|---|---|
| weekday, weekdayNumber | English weekday name and ISO weekday number, Monday=1 through Sunday=7 |
| isWeekday | Monday through Friday, independent of the selected weekend rule |
| isWeekend | Date belongs to the chosen weekend days |
| isBankHoliday | Selected division has a feed holiday on this date |
| isWorkingDay | Date is neither a chosen weekend day nor an official bank holiday |
| holidayTitles | Calendar mode: titles of holidays on that date, otherwise an empty list |
| weekendDays, weekendAssumptions | Named weekend days and the calculation's explicit assumptions |
| calendarComplete | Calendar/count mode: touched years are present and applicable holiday events parsed without errors; source completeness depends on GOV.UK |
| Working-days summary field | Meaning |
|---|---|
| rangeStart, rangeEnd, inclusive | Bounds and true, indicating both endpoints count |
| calendarDaysCount | Number of dates in the whole range |
| weekdayDaysCount | Monday–Friday dates |
| weekendDaysCount | Dates excluded by the selected weekend rule |
| bankHolidayDaysCount | Distinct holiday dates in the range, including holidays falling on a chosen weekend |
| nonWeekendBankHolidayDaysCount | Holiday dates outside the selected weekend; prevents double subtraction |
| workingDaysCount | Remaining working dates |
| weekendDays, weekendAssumptions, calendarComplete | Calculation assumptions and source-parsing coverage |
Error rows may also include eventIndex, inputDate, rangeStart and rangeEnd for diagnosis. An event's malformed title, date, notes or bunting produces an error row while other valid holiday rows survive. Derived results for a division are withheld when an applicable source year contains malformed events; no optimistic working-day count is emitted for that damaged calendar.
The RUN_SUMMARY key-value record includes availableYears, totalRows, outputRows, emittedRows, successfulRows, errorRows, sourceErrorRows, maxItems, truncated, budgetReached, durationSeconds and full-range workingDaySummaries in derived modes. Unsupported-year/source failures have a shorter summary with status and errors. Invalid input fails before fetching and has no result rows.
Counts use the complete source calendar and full requested range even when maxItems truncates daily output. Use RUN_SUMMARY.truncated to detect a capped dataset. Errors count against maxItems but are uncharged. The dataset may be empty for a valid holiday filter; this is distinct from an unsupported year, which fails.
Actual output example
This row comes from sample_output.json, containing the 8 England/Wales 2026 holidays returned by the recorded local run:
Pricing
Proposed pay-per-event pricing: holiday = $0.001 per successful dataset row, or $1 per 1,000 rows. Holiday events, calendar dates and working-days summaries each use one event per successful row. Error rows and RUN_SUMMARY are not charged. There is no proposed start fee or minimum event spend. Price activation is the owner's publication step; platform usage depends on Apify settings and the caller's plan.
The Store API comparison on 2026-10-06 found easyapi/public-holidays-api as the most used comparable returned by the recorded holiday/calendar searches, with 30 lifetime users. Its current result fee was $0.00299 with a $0.09 start event. Our proposed result fee is lower. PRICING.md and evidence/pricing-comparison.json contain the selection rule, full event prices and retrieval timestamp.
Limits
- Date ranges are inclusive and bounded to 366 days; output is capped globally by maxItems.
- Source access is sequential with one connection and a 20-second request timeout. Responses larger than 2 MiB are rejected.
- Years come from the feed at run time. Stored test fixtures are regression evidence, not a fallback data source.
- Saturday/Sunday is the default weekend, but the chosen rule is stated in derived output. Monday–Friday isWeekday remains a separate flag.
- Working-day calculations exclude official bank holidays and the selected weekend only. Employer-specific closures, local holidays and other calendars are not included.
- Source failures produce an uncharged error row and failed run; malformed individual events preserve valid holiday rows and diagnostics.
- The SDK charging budget can stop output before maxItems; this is reported as truncated with budgetReached. Paid cloud billing and Docker execution have not been exercised in this local build.
FAQ
Why are England and Wales combined? The official feed uses a single england-and-wales division.
Does this forecast holidays? No. It uses the events and years present in the fetched official feed, including any special holidays added by GOV.UK.
Are substitute days preserved? Yes. The returned date is the official substitute date and notes retains Substitute day when supplied.
Can I calculate a full range with maxItems=1? Yes. working-days mode emits one full-range summary per division. In calendar mode the dataset is capped but full-range summaries remain in RUN_SUMMARY. With division=all and maxItems=1, only the first dataset row is emitted; RUN_SUMMARY announces truncation.
Does bunting determine working days? No. It is preserved as source data; each listed holiday date is excluded regardless of bunting.
Use with AI agents / MCP
Once this actor is published, use Apify's MCP server to discover/run it and read dataset results, or supply these same JSON inputs through the Apify actor API in your automation. The MCP integration has not been exercised as part of this local build.
Ask an agent to select the correct division, verify requested years, set a bounded range and explicit weekend, then inspect recordType, errors and RUN_SUMMARY.truncated before using a result. For a planning calculation use working-days mode; for per-date decisions use calendar mode. Attribution fields should travel with reused output.
Source and attribution
© Crown copyright. Contains public sector information licensed under the Open Government Licence v3.0. Source: GOV.UK bank holidays and its official JSON feed. GOV.UK content terms describe Crown copyright and OGL reuse.
This actor is an independent tool. GOV.UK supplies the source calendar; the actor supplies normalization, filtering and calculations.
Verification
Unit tests use a full official response saved with its source, retrieval timestamp and OGL attribution in tests/fixtures. One test is marked live and fetches GOV.UK. Exact command output is in evidence/tests-final.txt; CLI schema output is in evidence/schemaValid.txt; real-process observations are in evidence/BEHAVIOR_PROOF.md and evidence/observations.json. The sample is from an actual local SDK run, not generated documentation data.
