GOV.UK API: List bank holidays
Lists GOV.UK bank holidays for a UK region and year, including substitute days and notes, plus the next upcoming holiday. Years GOV.UK does not publish return an empty list and the published years.
Unofficial. Not affiliated with or endorsed by GOV.UK.
Inputs
Values from the run on Oct 23, 2026, shown under Output.
- Year optional
year Calendar year, for example 2027. Defaults to the current year (Europe/London).
2027
Whole number from 1 to 9999.
- Region optional
region UK region, for example scotland. Defaults to england_and_wales.
scotland
One of
england_and_wales,scotland,northern_ireland. Defaultengland_and_wales.
Input as JSON
{ "year": 2027, "region": "scotland"}Output
{ "link": "https://www.gov.uk/bank-holidays#scotland" , "note": null, "year": 2027, "region": "scotland", "holidays": [ { "date": "2027-01-01", "link": "https://www.gov.uk/bank-holidays#scotland" , "note": null, "day_of_week": "Friday", "holiday_name": "New Year’s Day", "substitute_day": "no" }, { "date": "2027-01-04", "link": "https://www.gov.uk/bank-holidays#scotland" , "note": "Substitute day", "day_of_week": "Monday", "holiday_name": "2nd January", "substitute_day": "yes" }, { "date": "2027-03-26", "link": "https://www.gov.uk/bank-holidays#scotland" , "note": null, "day_of_week": "Friday", "holiday_name": "Good Friday", "substitute_day": "no" } ], "next_upcoming_bank_holiday": { "date": "2026-11-30", "link": "https://www.gov.uk/bank-holidays#scotland" , "note": null, "day_of_week": "Monday", "holiday_name": "St Andrew’s Day", "substitute_day": "no" }}Code
curl https://api.fous.com/v1/runs \ -H "Authorization: Bearer $FOUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"method":"gov.uk/list_bank_holidays","input":{"year":2027,"region":"scotland"}}' # Save as fous.py, then run: python3 fous.pyimport json, os, timefrom urllib.error import HTTPErrorfrom urllib.request import Request, urlopenAPI = "https://api.fous.com/v1/runs" KEY = os.environ["FOUS_API_KEY"]HEADERS = { "Authorization": f"Bearer {KEY}", "Content-Type": "application/json" ,}def call(url, body=None): data = json.dumps(body).encode() if body else None request = Request(url, data, HEADERS) try: with urlopen(request, timeout=120) as r: return r.status, json.load(r) except HTTPError as error: message = json.load(error)["error"]["message"] raise RuntimeError(message) from errorstatus, run = call(API, { "method": "gov.uk/list_bank_holidays" , "input": { "year": 2027, "region": "scotland" }})# 202: still going after 30 s. Ask again until it ends.while status == 202: time.sleep(2) status, run = call(f"{API}/{run['id']}")print(json.dumps(run["data"], indent=2))// Save as fous.mjs, then run: node fous.mjsconst api = "https://api.fous.com/v1/runs" ;const headers = { Authorization: `Bearer ${process.env.FOUS_API_KEY}`, "Content-Type": "application/json" ,};let response = await fetch(api, { method: "POST", headers, body: JSON.stringify({ "method": "gov.uk/list_bank_holidays" , "input": { "year": 2027, "region": "scotland" } }), signal: AbortSignal.timeout(120_000),});let run = await response.json();// 202: still going after 30 s. Ask again until it ends.while (response.status === 202) { await new Promise((done) => setTimeout(done, 2_000)); response = await fetch(`${api}/${run.id}`, { headers }); run = await response.json();}if (!response.ok) throw new Error(run.error.message);console.log(run.data);# Connect your agent to Fous once, over MCP (Streamable HTTP):# https://api.fous.com/mcp# Set FOUS_API_KEY first: create a key at https://app.fous.com/keys.# Claude Codeclaude mcp add \ --scope user \ --transport http fous https://api.fous.com/mcp \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Codexcodex mcp add fous \ --url https://api.fous.com/mcp \ --bearer-token-env-var FOUS_API_KEY# Cursor, VS Code, Windsurf, Cline and morenpx -y add-mcp https://api.fous.com/mcp -g -n fous \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Then ask your agent:# "Use Fous to run gov.uk/list_bank_holidays# with {"year":2027,"region":"scotland"}"Over HTTP, the answer’s data holds the output. A run still going after 30 seconds answers 202 with its id: ask GET /v1/runs/{id} until it ends.
Schema
Input schema
{ "type": "object", "properties": { "year": { "type": "integer", "maximum": 9999, "minimum": 1, "description": "Calendar year, for example 2027. Defaults to the current year (Europe/London)." }, "region": { "enum": [ "england_and_wales", "scotland", "northern_ireland" ], "type": "string", "default": "england_and_wales", "description": "UK region, for example scotland. Defaults to england_and_wales." } }}Output schema
{ "type": "object", "required": [ "region", "year", "holidays", "next_upcoming_bank_holiday", "note", "link" ], "properties": { "link": { "type": "string", "description": "GOV.UK bank holiday page for the selected region." }, "note": { "type": [ "string", "null" ], "description": "Available published years when the requested year is unavailable." }, "year": { "type": "integer", "description": "Year requested." }, "region": { "type": "string", "description": "Region requested." }, "holidays": { "type": "array", "items": { "type": "object", "required": [ "date", "day_of_week", "holiday_name", "substitute_day", "note", "link" ], "properties": { "date": { "type": "string", "format": "date", "description": "Holiday date." }, "link": { "type": "string", "description": "GOV.UK page for this holiday's region." }, "note": { "type": [ "string", "null" ], "description": "Any note shown by GOV.UK, or null." }, "day_of_week": { "type": "string", "description": "Day of the week." }, "holiday_name": { "type": "string", "description": "Name of the bank holiday." }, "substitute_day": { "enum": [ "yes", "no" ], "type": "string", "description": "Whether this is a substitute day." } } }, "description": "Bank holidays for the year in date order." }, "next_upcoming_bank_holiday": { "anyOf": [ { "type": "object", "required": [ "date", "day_of_week", "holiday_name", "substitute_day", "note", "link" ], "properties": { "date": { "type": "string", "format": "date" }, "link": { "type": "string" }, "note": { "type": [ "string", "null" ] }, "day_of_week": { "type": "string" }, "holiday_name": { "type": "string" }, "substitute_day": { "enum": [ "yes", "no" ], "type": "string" } } }, { "type": "null" } ], "description": "Next bank holiday on or after today, regardless of the selected year, if published." } }}- Price
- 1 credit per completed run (1¢ with pay as you go); failed runs are free.
- Method
gov.uk/list_bank_holidays- Returns
- holidays for the year, substitute days, notes, next upcoming bank holiday
Use it from your agent
Give your agent this line. It reads SKILL.md, gets a Fous API key and connects the Fous MCP server. Its run then takes the method gov.uk/list_bank_holidays with the inputs above.
Ask your agent
- What are the bank holidays in Scotland in 2027?
- List England and Wales bank holidays for 2025, including any substitute days.
- When is the next bank holiday in Northern Ireland?
- Which days are public holidays in the UK for 2026 for England and Wales, and are any substituted?
- Show me the Scotland bank holiday dates for 2028 on gov.uk with any notes.
See more
All GOV.UK methodsChecks a name against the current UK Sanctions List and returns possible matches in the site's best-match order, with designation details. Results may include entries that only mention the name in their reasons, so check each entry before identifying anyone.
gov.uk/check_sanctionsReturns current UK government (FCDO) travel warnings, entry requirements for British passport holders, safety, health and emergency information for a country. Summaries are shortened; follow the link for full details.
gov.uk/get_travel_adviceLists a country's public holidays for a year from Nager.Date, with local names, regional coverage and holiday types.
date.nager.at/list_public_holidaysSearch UK legislation by topic or title, with optional type and year filters. Closest title matches appear first; broader text matches fill remaining places.
legislation.gov.uk/search_legislationCounts weekdays between two dates, excluding nationwide public holidays or, optionally, public holidays in a state or province, from Time and Date's published holiday calendar.
timeanddate.com/count_business_daysReturns the PGA Tour season schedule for a year, with dates, venue, purse, status, winners and defending champions.
pgatour.com/get_scheduleLists statewide ballot measures in a US state and year, in Ballotpedia order, with election dates, topics, measure types, yes/no vote meanings and results. Years without statewide measures return an empty list.
ballotpedia.org/list_ballot_measuresChecks whether a date is a public holiday or weekend in a country. By default only nationwide holidays count; give a region to include holidays observed there.
date.nager.at/check_public_holiday