# UK Bank Holidays

> Look up UK bank holidays from a workflow, straight from GOV.UK. List the bank holidays for a year or between two dates, get the next one coming up, check whether a date, or today, is a bank holiday, find when a named one falls, count the working days between two dates with weekends and bank holidays taken out, and work out a deadline a number of working days away. England and Wales, Scotland and Northern Ireland keep three different calendars and this handles all three, including comparing a date across them in one step, so a business with an office in Edinburgh and one in London gets the right answer for each. Substitute days are flagged rather than left in a note. Every action reads: nothing here changes anything. No account or API key required.

App · Calendars · 9 actions. Web page: https://docs.lodol.com/docs/integrations/uk-bank-holidays

## Actions

### Add working days to a date

Work out the date a number of working days from another one, stepping over weekends and the local bank holidays. This is the deadline sum: 'we will reply within five working days' from a ticket's date, a payment due date, a notice period. Counting starts the day after the start date, which is how a deadline is written. A negative number counts backwards, for working out when to start in order to finish on time.

**Inputs**

- Where in the UK (`division`, text, required): Which of the three UK bank holiday calendars to read. They really do differ: Easter Monday is a bank holiday in England, Wales and Northern Ireland but not in Scotland, Scotland has 2nd January and St Andrew's Day, and Northern Ireland has St Patrick's Day and the Battle of the Boyne. A value from an earlier step can be the name of a country ('Wales'), the slug GOV.UK keys the data by ('england-and-wales') or the ISO code another integration uses ('GB-SCT'). 'UK' is not an answer, because the three calendars disagree; use 'Compare a date across the UK' to ask all three at once. One of: `england-and-wales` (England and Wales), `scotland`, `northern-ireland` (Northern Ireland).
- Start date (`start_date`, date): The date to count from. It is not itself counted: one working day after a Monday is the Tuesday. Defaults to today in the UK.
- Working days (`working_days`, number, required): How many working days to count. A negative number counts backwards from the start date. Zero returns the start date itself. From -2000 to 2000.
- Working days of the week (`working_week`, list): Which days of the week count as worked. Monday to Friday by default, which with bank holidays taken out is the working day GOV.UK itself means. Add Saturday for a business that trades then, otherwise every count here is out by a day a week. One or more of: `Monday`, `Tuesday`, `Wednesday`, `Thursday`, `Friday`, `Saturday`, `Sunday`. Default: `["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"]`.

**Outputs**

- `calendar_days` (number): How many calendar days that turned out to be
- `date` (text): The date the count landed on, as YYYY-MM-DD
- `direction` (text): 'forwards' or 'backwards'
- `division` (text): The calendar that was read
- `division_name` (text): That calendar's name
- `skipped_bank_holiday_count` (number): Bank holidays passed over
- `skipped_bank_holidays` (list): Those bank holidays, in date order
- `skipped_weekend_days` (number): Days passed over for falling outside the working week
- `start_date` (text): The date counting began from
- `start_is_working_day` (true/false): True when the start date was itself a working day; counting begins the day after either way
- `start_weekday` (text): The day of the week that was
- `weekday` (text): The day of the week it is
- `working_days` (number): The number of working days that were counted
- `working_week` (list): The weekdays counted as worked

**Example output**

```json
{
  "calendar_days": 12,
  "date": "2027-01-04",
  "direction": "forwards",
  "division": "england-and-wales",
  "division_name": "England and Wales",
  "skipped_bank_holiday_count": 3,
  "skipped_bank_holidays": [
    {
      "bunting": true,
      "date": "2026-12-25",
      "days_until": 312,
      "division": "england-and-wales",
      "division_name": "England and Wales",
      "is_substitute": false,
      "notes": "",
      "title": "Christmas Day",
      "weekday": "Friday",
      "year": 2026
    },
    {
      "bunting": true,
      "date": "2026-12-28",
      "days_until": 315,
      "division": "england-and-wales",
      "division_name": "England and Wales",
      "is_substitute": true,
      "notes": "Substitute day",
      "title": "Boxing Day",
      "weekday": "Monday",
      "year": 2026
    },
    {
      "bunting": true,
      "date": "2027-01-01",
      "days_until": 319,
      "division": "england-and-wales",
      "division_name": "England and Wales",
      "is_substitute": false,
      "notes": "",
      "title": "New Year's Day",
      "weekday": "Friday",
      "year": 2027
    }
  ],
  "skipped_weekend_days": 4,
  "start_date": "2026-12-23",
  "start_is_working_day": true,
  "start_weekday": "Wednesday",
  "weekday": "Monday",
  "working_days": 5,
  "working_week": [
    "Monday",
    "Tuesday",
    "Wednesday",
    "Thursday",
    "Friday"
  ]
}
```

### Check whether a date is a bank holiday

Check one date in one part of the UK and get three plain answers: is it a bank holiday, is it a weekend, is it a working day. Use it to gate a workflow on whether an office is open, or to hold a message back until the next working day. It defaults to today, so 'is today a bank holiday' needs nothing filled in but the place. A date outside the years GOV.UK publishes is refused rather than answered no, because those are not the same thing.

**Inputs**

- Where in the UK (`division`, text, required): Which of the three UK bank holiday calendars to read. They really do differ: Easter Monday is a bank holiday in England, Wales and Northern Ireland but not in Scotland, Scotland has 2nd January and St Andrew's Day, and Northern Ireland has St Patrick's Day and the Battle of the Boyne. A value from an earlier step can be the name of a country ('Wales'), the slug GOV.UK keys the data by ('england-and-wales') or the ISO code another integration uses ('GB-SCT'). 'UK' is not an answer, because the three calendars disagree; use 'Compare a date across the UK' to ask all three at once. One of: `england-and-wales` (England and Wales), `scotland`, `northern-ireland` (Northern Ireland).
- Date to check (`check_on`, date): The date to check. Defaults to today in the UK, which is the day a bank holiday is actually on: a step running late in the evening would otherwise ask about yesterday for half the year.
- Working days of the week (`working_week`, list): Which days of the week count as worked. Monday to Friday by default, which with bank holidays taken out is the working day GOV.UK itself means. Add Saturday for a business that trades then, otherwise every count here is out by a day a week. One or more of: `Monday`, `Tuesday`, `Wednesday`, `Thursday`, `Friday`, `Saturday`, `Sunday`. Default: `["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"]`.

**Outputs**

- `bank_holidays` (list): Every entry on the date, normally none or one
- `bunting` (true/false): True when bunting is traditionally put out
- `covered_from_year` (number): The earliest year this calendar reaches
- `covered_to_year` (number): The latest year this calendar reaches
- `date` (text): The date that was checked
- `days_until_next` (number): Days from this date to the next bank holiday
- `division` (text): The calendar that was read
- `division_name` (text): That calendar's name
- `is_bank_holiday` (true/false): True when this calendar has a bank holiday on the date
- `is_substitute` (true/false): True when it stands in for a weekend date
- `is_weekend` (true/false): True when the date falls outside the working week
- `is_working_day` (true/false): True when it is neither, so an office is open
- `next_bank_holiday` (text): The name of the next bank holiday after this date
- `next_bank_holiday_date` (text): The date of the next bank holiday after this date
- `notes` (text): GOV.UK's own note on the entry
- `title` (text): The bank holiday's name, empty when there is none
- `weekday` (text): The day of the week
- `working_week` (list): The weekdays counted as worked

**Example output**

```json
{
  "bank_holidays": [
    {
      "bunting": true,
      "date": "2026-04-06",
      "days_until": 49,
      "division": "england-and-wales",
      "division_name": "England and Wales",
      "is_substitute": false,
      "notes": "",
      "title": "Easter Monday",
      "weekday": "Monday",
      "year": 2026
    }
  ],
  "bunting": true,
  "covered_from_year": 2019,
  "covered_to_year": 2028,
  "date": "2026-04-06",
  "days_until_next": 28,
  "division": "england-and-wales",
  "division_name": "England and Wales",
  "is_bank_holiday": true,
  "is_substitute": false,
  "is_weekend": false,
  "is_working_day": false,
  "next_bank_holiday": "Early May bank holiday",
  "next_bank_holiday_date": "2026-05-04",
  "notes": "",
  "title": "Easter Monday",
  "weekday": "Monday",
  "working_week": [
    "Monday",
    "Tuesday",
    "Wednesday",
    "Thursday",
    "Friday"
  ]
}
```

### Compare a date across the UK

Ask all three UK calendars about one date at once, and get a ready-made sentence saying who has the day off and who does not. This is the action for a business with people in more than one of them, because the calendars really do disagree: Easter Monday closes London and not Edinburgh, 2nd January closes Edinburgh and not London, and St Patrick's Day closes Belfast alone. Defaults to today.

**Inputs**

- Date to check (`check_on`, date): The date to check in all three calendars. Defaults to today in the UK.
- Working days of the week (`working_week`, list): Which days of the week count as worked. Monday to Friday by default, which with bank holidays taken out is the working day GOV.UK itself means. Add Saturday for a business that trades then, otherwise every count here is out by a day a week. One or more of: `Monday`, `Tuesday`, `Wednesday`, `Thursday`, `Friday`, `Saturday`, `Sunday`. Default: `["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"]`.

**Outputs**

- `bank_holiday_division_names` (list): The names of the places that have the day off
- `bank_holiday_divisions` (list): The slugs of the places that have the day off
- `covered_from_year` (number): The earliest year the data reaches
- `covered_to_year` (number): The latest year the data reaches
- `date` (text): The date that was checked
- `divisions` (list): One answer per calendar, in GOV.UK's own order
- `divisions_differ` (true/false): True when some of them have the day off and others do not, which is the case worth catching
- `is_bank_holiday_anywhere` (true/false): True when at least one of them has the day off
- `is_bank_holiday_everywhere` (true/false): True when all three calendars have the day off
- `is_weekend` (true/false): True when the date falls outside the working week
- `summary` (text): A sentence saying who has the day off and who does not
- `titles` (list): The distinct names the date goes by
- `weekday` (text): The day of the week
- `working_week` (list): The weekdays counted as worked

**Example output**

```json
{
  "bank_holiday_division_names": [
    "England and Wales",
    "Northern Ireland"
  ],
  "bank_holiday_divisions": [
    "england-and-wales",
    "northern-ireland"
  ],
  "covered_from_year": 2019,
  "covered_to_year": 2028,
  "date": "2026-04-06",
  "divisions": [
    {
      "bunting": true,
      "division": "england-and-wales",
      "division_name": "England and Wales",
      "is_bank_holiday": true,
      "is_substitute": false,
      "is_working_day": false,
      "notes": "",
      "title": "Easter Monday"
    },
    {
      "bunting": false,
      "division": "scotland",
      "division_name": "Scotland",
      "is_bank_holiday": false,
      "is_substitute": false,
      "is_working_day": true,
      "notes": "",
      "title": ""
    },
    {
      "bunting": true,
      "division": "northern-ireland",
      "division_name": "Northern Ireland",
      "is_bank_holiday": true,
      "is_substitute": false,
      "is_working_day": false,
      "notes": "",
      "title": "Easter Monday"
    }
  ],
  "divisions_differ": true,
  "is_bank_holiday_anywhere": true,
  "is_bank_holiday_everywhere": false,
  "is_weekend": false,
  "summary": "2026-04-06 (Monday) is Easter Monday in England and Wales and in Northern Ireland, but a normal day in Scotland.",
  "titles": [
    "Easter Monday"
  ],
  "weekday": "Monday",
  "working_week": [
    "Monday",
    "Tuesday",
    "Wednesday",
    "Thursday",
    "Friday"
  ]
}
```

### Count working days

Count the working days between two dates, with weekends and the local bank holidays taken out. Use it for an SLA window, a notice period, a payroll run or a project estimate. It also hands back which bank holidays cost a working day and which fell at a weekend anyway, and the working week is a setting, so a business that trades on Saturday counts its own.

**Inputs**

- Where in the UK (`division`, text, required): Which of the three UK bank holiday calendars to read. They really do differ: Easter Monday is a bank holiday in England, Wales and Northern Ireland but not in Scotland, Scotland has 2nd January and St Andrew's Day, and Northern Ireland has St Patrick's Day and the Battle of the Boyne. A value from an earlier step can be the name of a country ('Wales'), the slug GOV.UK keys the data by ('england-and-wales') or the ISO code another integration uses ('GB-SCT'). 'UK' is not an answer, because the three calendars disagree; use 'Compare a date across the UK' to ask all three at once. One of: `england-and-wales` (England and Wales), `scotland`, `northern-ireland` (Northern Ireland).
- From date (`start_date`, date, required): The first day of the range, counted in.
- To date (`end_date`, date, required): The last day of the range, counted in. It must be on or after the start date.
- Working days of the week (`working_week`, list): Which days of the week count as worked. Monday to Friday by default, which with bank holidays taken out is the working day GOV.UK itself means. Add Saturday for a business that trades then, otherwise every count here is out by a day a week. One or more of: `Monday`, `Tuesday`, `Wednesday`, `Thursday`, `Friday`, `Saturday`, `Sunday`. Default: `["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"]`.

**Outputs**

- `bank_holiday_count` (number): Bank holidays in the range, however they fell
- `bank_holiday_days_off` (number): Working-week days lost to a bank holiday
- `bank_holidays` (list): The bank holidays that cost a working day
- `bank_holidays_on_weekends` (list): Bank holidays that fell outside the working week, so cost nothing
- `division` (text): The calendar that was read
- `division_name` (text): That calendar's name
- `end_date` (text): The last day of the range
- `start_date` (text): The first day of the range
- `total_days` (number): Calendar days in the range, both ends counted in
- `weekend_days` (number): Days that fell outside the working week
- `working_days` (number): Working days in the range, both ends counted in
- `working_week` (list): The weekdays counted as worked

**Example output**

```json
{
  "bank_holiday_count": 2,
  "bank_holiday_days_off": 2,
  "bank_holidays": [
    {
      "bunting": true,
      "date": "2026-12-25",
      "days_until": 312,
      "division": "england-and-wales",
      "division_name": "England and Wales",
      "is_substitute": false,
      "notes": "",
      "title": "Christmas Day",
      "weekday": "Friday",
      "year": 2026
    },
    {
      "bunting": true,
      "date": "2026-12-28",
      "days_until": 315,
      "division": "england-and-wales",
      "division_name": "England and Wales",
      "is_substitute": true,
      "notes": "Substitute day",
      "title": "Boxing Day",
      "weekday": "Monday",
      "year": 2026
    }
  ],
  "bank_holidays_on_weekends": [],
  "division": "england-and-wales",
  "division_name": "England and Wales",
  "end_date": "2026-12-31",
  "start_date": "2026-12-01",
  "total_days": 31,
  "weekend_days": 8,
  "working_days": 21,
  "working_week": [
    "Monday",
    "Tuesday",
    "Wednesday",
    "Thursday",
    "Friday"
  ]
}
```

### Find a bank holiday by name

Find the dates a named bank holiday falls on, year by year: 'when is the Early May bank holiday', 'when is Christmas Day in Scotland'. Searching forwards from today by default, because that is usually the question. Names are matched loosely, so a partial name, a different case or a typed apostrophe all find it, and every match says how it matched. Watch for substitute days in the answer: Christmas Day 2027 comes back as 27 December, because that is the bank holiday.

**Inputs**

- Where in the UK (`division`, text, required): Which of the three UK bank holiday calendars to read. They really do differ: Easter Monday is a bank holiday in England, Wales and Northern Ireland but not in Scotland, Scotland has 2nd January and St Andrew's Day, and Northern Ireland has St Patrick's Day and the Battle of the Boyne. A value from an earlier step can be the name of a country ('Wales'), the slug GOV.UK keys the data by ('england-and-wales') or the ISO code another integration uses ('GB-SCT'). 'UK' is not an answer, because the three calendars disagree; use 'Compare a date across the UK' to ask all three at once. One of: `england-and-wales` (England and Wales), `scotland`, `northern-ireland` (Northern Ireland).
- Name (`name`, text, required): The bank holiday's name, or any part of it. GOV.UK rewrites these from year to year, so a short word finds more than a full title does.
- From date (`from_date`, date): Search from this date onwards. Defaults to today, so the answer is the next one rather than a list starting years ago. Set it earlier to include ones that have already happened.
- To date (`to_date`, date): Stop searching after this date. Defaults to the end of what GOV.UK publishes.
- How many to return (`limit`, number): How many bank holidays to return, earliest first. Defaults to 50, which is more than any of them has in five years. From 1 to 500. Default: `50`.

**Outputs**

- `bank_holidays` (list): The bank holidays whose name matched, in date order
- `count` (number): How many are in this result
- `covered_from_year` (number): The earliest year this calendar reaches
- `covered_to_year` (number): The latest year this calendar reaches
- `division` (text): The calendar that was read
- `division_name` (text): That calendar's name
- `found` (true/false): False when nothing matched
- `matched_count` (number): How many matched before the limit was applied
- `name` (text): The text that was searched for
- `next_date` (text): The date of the first match still to come
- `next_days_until` (number): Days from today to that match
- `next_title` (text): The name of the first match still to come
- `searched_from` (text): The first day searched, after trimming to what is published
- `searched_to` (text): The last day searched, after trimming to what is published

**Example output**

```json
{
  "bank_holidays": [
    {
      "bunting": true,
      "date": "2026-12-25",
      "days_until": 312,
      "division": "england-and-wales",
      "division_name": "England and Wales",
      "is_substitute": false,
      "match_type": "contains",
      "notes": "",
      "title": "Christmas Day",
      "weekday": "Friday",
      "year": 2026
    },
    {
      "bunting": true,
      "date": "2027-12-27",
      "days_until": 679,
      "division": "england-and-wales",
      "division_name": "England and Wales",
      "is_substitute": true,
      "match_type": "contains",
      "notes": "Substitute day",
      "title": "Christmas Day",
      "weekday": "Monday",
      "year": 2027
    }
  ],
  "count": 2,
  "covered_from_year": 2019,
  "covered_to_year": 2028,
  "division": "england-and-wales",
  "division_name": "England and Wales",
  "found": true,
  "matched_count": 2,
  "name": "Christmas",
  "next_date": "2026-12-25",
  "next_days_until": 312,
  "next_title": "Christmas Day",
  "searched_from": "2026-02-16",
  "searched_to": "2028-12-31"
}
```

### Get the next bank holiday

Get the single next bank holiday for one part of the UK, returned flat so a later step can read the name, the date and how many days away it is without indexing into a list. Answers 'when is the next day off' in one step, and a scheduled workflow can act a fortnight before one. Counts from today unless you give it a date to count from.

**Inputs**

- Where in the UK (`division`, text, required): Which of the three UK bank holiday calendars to read. They really do differ: Easter Monday is a bank holiday in England, Wales and Northern Ireland but not in Scotland, Scotland has 2nd January and St Andrew's Day, and Northern Ireland has St Patrick's Day and the Battle of the Boyne. A value from an earlier step can be the name of a country ('Wales'), the slug GOV.UK keys the data by ('england-and-wales') or the ISO code another integration uses ('GB-SCT'). 'UK' is not an answer, because the three calendars disagree; use 'Compare a date across the UK' to ask all three at once. One of: `england-and-wales` (England and Wales), `scotland`, `northern-ireland` (Northern Ireland).
- After this date (`from_date`, date): Count from this date, not counting the date itself. Defaults to today in the UK. Use 'Check whether a date is a bank holiday' if the question is about today rather than after it.
- Bunting (`bunting`, text): GOV.UK marks each bank holiday with whether bunting is traditionally put out for it, which is its way of separating a celebration from a solemn day: Good Friday and the Battle of the Boyne are marked as no. Filter on it when the message a workflow sends should be cheerful or should not be. Leave it unset for both. One of: `yes` (Only the ones to put bunting out for), `no` (Only the ones not to put bunting out for).
- Substitute days (`substitute_days`, text): A bank holiday that falls at a weekend is moved to a weekday, and GOV.UK publishes only the moved date: Christmas Day 2027 appears as 27 December. Leave this unset to include those, or narrow to them, or drop them to see only the holidays that fall on their own date. One of: `only` (Only substitute days), `exclude` (Leave substitute days out).

**Outputs**

- `bunting` (true/false): True when bunting is traditionally put out
- `covered_from_year` (number): The earliest year this calendar reaches
- `covered_to_year` (number): The latest year this calendar reaches
- `date` (text): The date, as YYYY-MM-DD
- `days_until` (number): Days from the date the search started
- `division` (text): The calendar that was read
- `division_name` (text): That calendar's name
- `found` (true/false): False when the published years hold nothing later
- `from_date` (text): The date the search started after
- `is_substitute` (true/false): True when it stands in for a weekend date
- `notes` (text): GOV.UK's own note on the entry
- `title` (text): The bank holiday's name
- `weekday` (text): The day of the week

**Example output**

```json
{
  "bunting": false,
  "covered_from_year": 2019,
  "covered_to_year": 2028,
  "date": "2026-04-03",
  "days_until": 46,
  "division": "england-and-wales",
  "division_name": "England and Wales",
  "found": true,
  "from_date": "2026-02-16",
  "is_substitute": false,
  "notes": "",
  "title": "Good Friday",
  "weekday": "Friday"
}
```

### List bank holidays between two dates

List the bank holidays one part of the UK has between two dates, whether or not they fall in the same year: a quarter, a sprint, a delivery window or the next six months in one step. GOV.UK publishes a rolling window of years, so a range reaching past it is trimmed to what exists and the result says so rather than quietly coming back short.

**Inputs**

- Where in the UK (`division`, text, required): Which of the three UK bank holiday calendars to read. They really do differ: Easter Monday is a bank holiday in England, Wales and Northern Ireland but not in Scotland, Scotland has 2nd January and St Andrew's Day, and Northern Ireland has St Patrick's Day and the Battle of the Boyne. A value from an earlier step can be the name of a country ('Wales'), the slug GOV.UK keys the data by ('england-and-wales') or the ISO code another integration uses ('GB-SCT'). 'UK' is not an answer, because the three calendars disagree; use 'Compare a date across the UK' to ask all three at once. One of: `england-and-wales` (England and Wales), `scotland`, `northern-ireland` (Northern Ireland).
- From date (`start_date`, date, required): The first day of the range, counted in.
- To date (`end_date`, date, required): The last day of the range, counted in. It must be on or after the start date.
- Name contains (`name_contains`, text): Only bank holidays whose name contains this text. Case, accents and the difference between a typed apostrophe and the typographic one GOV.UK publishes are all ignored, so 'new year's day' finds it. Leave it empty for every bank holiday.
- Bunting (`bunting`, text): GOV.UK marks each bank holiday with whether bunting is traditionally put out for it, which is its way of separating a celebration from a solemn day: Good Friday and the Battle of the Boyne are marked as no. Filter on it when the message a workflow sends should be cheerful or should not be. Leave it unset for both. One of: `yes` (Only the ones to put bunting out for), `no` (Only the ones not to put bunting out for).
- Substitute days (`substitute_days`, text): A bank holiday that falls at a weekend is moved to a weekday, and GOV.UK publishes only the moved date: Christmas Day 2027 appears as 27 December. Leave this unset to include those, or narrow to them, or drop them to see only the holidays that fall on their own date. One of: `only` (Only substitute days), `exclude` (Leave substitute days out).
- How many to return (`limit`, number): How many bank holidays to return, earliest first. Defaults to 50, which is more than any of them has in five years. From 1 to 500. Default: `50`.

**Outputs**

- `bank_holidays` (list): The bank holidays that matched, in date order
- `clamped_to_covered_years` (true/false): True when the range reached outside the years GOV.UK publishes and was trimmed to them
- `count` (number): How many are in this result
- `covered_from_year` (number): The earliest year this calendar reaches
- `covered_to_year` (number): The latest year this calendar reaches
- `division` (text): The calendar that was read
- `division_name` (text): That calendar's name
- `end_date` (text): The last day actually searched, after any trimming
- `in_covered_years` (true/false): False when none of the range is published, so nothing could be searched
- `matched_count` (number): How many matched before the limit was applied
- `requested_end_date` (text): The last day that was asked for
- `requested_start_date` (text): The first day that was asked for
- `start_date` (text): The first day actually searched, after any trimming
- `total_count` (number): How many fall in the range before any filter

**Example output**

```json
{
  "bank_holidays": [
    {
      "bunting": true,
      "date": "2026-12-25",
      "days_until": 312,
      "division": "england-and-wales",
      "division_name": "England and Wales",
      "is_substitute": false,
      "notes": "",
      "title": "Christmas Day",
      "weekday": "Friday",
      "year": 2026
    },
    {
      "bunting": true,
      "date": "2026-12-28",
      "days_until": 315,
      "division": "england-and-wales",
      "division_name": "England and Wales",
      "is_substitute": true,
      "notes": "Substitute day",
      "title": "Boxing Day",
      "weekday": "Monday",
      "year": 2026
    }
  ],
  "clamped_to_covered_years": false,
  "count": 2,
  "covered_from_year": 2019,
  "covered_to_year": 2028,
  "division": "england-and-wales",
  "division_name": "England and Wales",
  "end_date": "2026-12-31",
  "in_covered_years": true,
  "matched_count": 2,
  "requested_end_date": "2026-12-31",
  "requested_start_date": "2026-12-01",
  "start_date": "2026-12-01",
  "total_count": 2
}
```

### List bank holidays in a year

List every bank holiday one part of the UK keeps in a calendar year. Each one comes back with the date, the weekday, whether it is a substitute for a holiday that fell at a weekend, and whether bunting goes out for it. Narrow to a name, to the bunting days, or to the substitute days, and order it either way round. England and Wales keep eight most years, Scotland nine and Northern Ireland ten.

**Inputs**

- Where in the UK (`division`, text, required): Which of the three UK bank holiday calendars to read. They really do differ: Easter Monday is a bank holiday in England, Wales and Northern Ireland but not in Scotland, Scotland has 2nd January and St Andrew's Day, and Northern Ireland has St Patrick's Day and the Battle of the Boyne. A value from an earlier step can be the name of a country ('Wales'), the slug GOV.UK keys the data by ('england-and-wales') or the ISO code another integration uses ('GB-SCT'). 'UK' is not an answer, because the three calendars disagree; use 'Compare a date across the UK' to ask all three at once. One of: `england-and-wales` (England and Wales), `scotland`, `northern-ireland` (Northern Ireland).
- Year (`year`, text): The calendar year to list. Defaults to this year. The list holds exactly the years GOV.UK publishes right now, which is a rolling window of roughly the last few years and the next few; it moves with the calendar, so use the refresh button beside the field if a new year is missing.
- Name contains (`name_contains`, text): Only bank holidays whose name contains this text. Case, accents and the difference between a typed apostrophe and the typographic one GOV.UK publishes are all ignored, so 'new year's day' finds it. Leave it empty for every bank holiday.
- Bunting (`bunting`, text): GOV.UK marks each bank holiday with whether bunting is traditionally put out for it, which is its way of separating a celebration from a solemn day: Good Friday and the Battle of the Boyne are marked as no. Filter on it when the message a workflow sends should be cheerful or should not be. Leave it unset for both. One of: `yes` (Only the ones to put bunting out for), `no` (Only the ones not to put bunting out for).
- Substitute days (`substitute_days`, text): A bank holiday that falls at a weekend is moved to a weekday, and GOV.UK publishes only the moved date: Christmas Day 2027 appears as 27 December. Leave this unset to include those, or narrow to them, or drop them to see only the holidays that fall on their own date. One of: `only` (Only substitute days), `exclude` (Leave substitute days out).
- Order (`order`, text): Earliest first by default. Latest first puts the end of the year at the top, which is what a step wanting the last bank holiday of the year reads. One of: `earliest` (Earliest first), `latest` (Latest first).

**Outputs**

- `bank_holidays` (list): The bank holidays that matched, in date order
- `bunting_count` (number): How many of these are bunting days
- `count` (number): How many are in this result
- `covered_from_year` (number): The earliest year this calendar reaches
- `covered_to_year` (number): The latest year this calendar reaches
- `division` (text): The calendar that was read
- `division_name` (text): That calendar's name
- `substitute_count` (number): How many of these are substitute days
- `total_count` (number): How many the year holds before any filter
- `year` (number): The year that was listed

**Example output**

```json
{
  "bank_holidays": [
    {
      "bunting": true,
      "date": "2026-12-25",
      "days_until": 312,
      "division": "england-and-wales",
      "division_name": "England and Wales",
      "is_substitute": false,
      "notes": "",
      "title": "Christmas Day",
      "weekday": "Friday",
      "year": 2026
    },
    {
      "bunting": true,
      "date": "2026-12-28",
      "days_until": 315,
      "division": "england-and-wales",
      "division_name": "England and Wales",
      "is_substitute": true,
      "notes": "Substitute day",
      "title": "Boxing Day",
      "weekday": "Monday",
      "year": 2026
    }
  ],
  "bunting_count": 2,
  "count": 2,
  "covered_from_year": 2019,
  "covered_to_year": 2028,
  "division": "england-and-wales",
  "division_name": "England and Wales",
  "substitute_count": 1,
  "total_count": 8,
  "year": 2026
}
```

### List the calendars and the years covered

List the three bank holiday calendars GOV.UK publishes, the countries each one applies in, how many bank holidays each holds, the next one coming up in each, and the years the data reaches. The years matter, because they are a rolling window: nothing outside them can be answered. It is also the one-step check that the connection works.

**Inputs**: None.

**Outputs**

- `count` (number): How many calendars there are
- `covered_from_year` (number): The earliest year any calendar reaches
- `covered_to_year` (number): The latest year any calendar reaches
- `divisions` (list): The three calendars, in GOV.UK's own order
- `source_url` (text): The GOV.UK document the data came from
- `today` (text): Today's date in the United Kingdom, as YYYY-MM-DD
- `total_bank_holiday_count` (number): Bank holidays across all three calendars

**Example output**

```json
{
  "count": 3,
  "covered_from_year": 2019,
  "covered_to_year": 2028,
  "divisions": [
    {
      "bank_holiday_count": 83,
      "covers": [
        "England",
        "Wales"
      ],
      "division": "england-and-wales",
      "first_date": "2019-01-01",
      "first_year": 2019,
      "last_date": "2028-12-26",
      "last_year": 2028,
      "name": "England and Wales",
      "next_date": "2026-04-03",
      "next_title": "Good Friday"
    },
    {
      "bank_holiday_count": 94,
      "covers": [
        "Scotland"
      ],
      "division": "scotland",
      "first_date": "2019-01-01",
      "first_year": 2019,
      "last_date": "2028-12-26",
      "last_year": 2028,
      "name": "Scotland",
      "next_date": "2026-04-03",
      "next_title": "Good Friday"
    },
    {
      "bank_holiday_count": 103,
      "covers": [
        "Northern Ireland"
      ],
      "division": "northern-ireland",
      "first_date": "2019-01-01",
      "first_year": 2019,
      "last_date": "2028-12-26",
      "last_year": 2028,
      "name": "Northern Ireland",
      "next_date": "2026-03-17",
      "next_title": "St Patrick's Day"
    }
  ],
  "source_url": "https://www.gov.uk/bank-holidays.json",
  "today": "2026-02-16",
  "total_bank_holiday_count": 280
}
```