UK Bank Holidays API

Overview

The UK Bank Holidays API provides a direct, unauthenticated JSON feed of official bank and public holidays for the United Kingdom. Maintained by the UK government, the API offers structured data covering holidays in England and Wales, Scotland, and Northern Ireland. This resource is designed for developers requiring precise, up-to-date information on UK public holidays for integration into various applications, including scheduling tools, calendar systems, and internal business applications.

Developers can retrieve a comprehensive list of upcoming and past bank holidays, complete with event titles and dates, categorized by geographical region. This regional breakdown is critical for applications serving users across the UK, as holiday schedules can differ significantly between constituent countries. For instance, while Christmas Day is a bank holiday across all regions, Scotland observes different additional holidays such as St Andrew's Day, which is not a bank holiday in England and Wales.

The API's simplicity, requiring no API keys or authentication, streamlines the integration process, allowing for direct consumption of the JSON data. This makes it particularly useful for rapid prototyping, small-to-medium scale projects, or educational purposes where the overhead of managing API credentials is undesirable. Its primary use cases include enhancing user interfaces with accurate holiday displays, automating holiday-sensitive business logic (e.g., payroll processing, delivery scheduling), and informing users about non-working days in the UK. The data is consistently updated, ensuring that changes to holiday schedules, such as substitute days for holidays falling on weekends, are reflected promptly.

Key features

• Official UK Government Data: Provides authoritative and regularly updated information on bank and public holidays directly from the UK government, ensuring accuracy for applications requiring UK holiday schedules.
• Regional Holiday Data: Delivers holiday schedules segmented by specific UK regions: England and Wales, Scotland, and Northern Ireland. This allows applications to present accurate holiday information relevant to distinct geographical areas within the UK.
• JSON Format: Data is delivered in a standard JSON format, facilitating parsing and integration with modern web and mobile applications using common programming languages and libraries.
• No Authentication Required: The API endpoint is publicly accessible without the need for API keys, OAuth tokens, or any other form of authentication, simplifying the development and deployment process.
• Comprehensive Holiday Details: Each holiday entry includes the event title and the specific date, along with an optional notes field for additional context, such as substitute days.
• Historical and Future Dates: The API provides data for both past and upcoming bank holidays, enabling historical analysis or future planning within applications.

Pricing

The UK Bank Holidays API is entirely free to use. There are no subscription fees, usage limits, or authentication requirements for accessing the official JSON data feed. This makes it a cost-effective solution for developers and organizations needing UK public holiday information.

Common integrations

• Web Applications: Displaying upcoming bank holidays on public-facing websites or internal dashboards. Developers can use standard JavaScript fetch or XMLHttpRequest to retrieve and render data dynamically.
• Scheduling and Calendar Software: Incorporating UK bank holidays into personal or organizational calendars to automatically mark non-working days. This can be achieved by parsing the JSON and adding events to calendar platforms via their respective APIs.
• Business Process Automation: Integrating holiday data into payroll systems, customer service routing, or delivery scheduling to account for non-business days. For example, a system might adjust estimated delivery dates based on the official UK bank holiday schedule.
• Mobile Applications: Providing users with localized UK bank holiday information within native iOS or Android applications. Developers would typically use HTTP client libraries available in Swift/Objective-C or Kotlin/Java to consume the JSON.
• Data Analysis Projects: Utilizing historical bank holiday data for trend analysis or to correlate business performance with holiday periods. Python's requests library and data manipulation tools like Pandas are commonly used for this.
• Notification Systems: Sending automated reminders or alerts to users about upcoming bank holidays. This could involve integrating with messaging APIs like Twilio's SMS API to send notifications based on the holiday schedule.

Alternatives

• Holiday API: Offers global holiday data for over 200 countries, including the UK, with features like date range queries and language support. More information can be found on the Holiday API website.
• Abstract Public Holidays API: Provides public holiday data for 250+ countries and supports various query parameters for filtering by country, year, and month. Details are available on the Abstract Public Holidays API page.
• Calendarific: A global holiday API covering 230+ countries, offering features such as timezone support and holiday types. Visit the Calendarific homepage for capabilities.

Getting started

To retrieve UK bank holiday data, you can make a simple HTTP GET request to the official JSON endpoint. The response will contain a structured JSON object with holiday events categorized by region.

Here's an example using Python to fetch and display bank holidays for England and Wales:

import requests

def get_uk_bank_holidays():
    url = "https://www.gov.uk/bank-holidays.json"
    try:
        response = requests.get(url)
        response.raise_for_status()  # Raise an HTTPError for bad responses (4xx or 5xx)
        data = response.json()
        return data
    except requests.exceptions.RequestException as e:
        print(f"Error fetching bank holidays: {e}")
        return None

if __name__ == "__main__":
    holidays_data = get_uk_bank_holidays()
    if holidays_data:
        england_wales_holidays = holidays_data.get("england-and-wales", {}).get("events", [])
        print("UK Bank Holidays (England and Wales):")
        for holiday in england_wales_holidays:
            print(f"  - {holiday['title']} on {holiday['date']}")

        # Example of accessing Scottish holidays
        scotland_holidays = holidays_data.get("scotland", {}).get("events", [])
        print("\nUK Bank Holidays (Scotland):")
        for holiday in scotland_holidays:
            print(f"  - {holiday['title']} on {holiday['date']}")

This Python script defines a function get_uk_bank_holidays that fetches the JSON data from the official UK bank holidays endpoint. It then parses the JSON response and prints the bank holidays specifically for England and Wales. The script also demonstrates how to access the holidays for Scotland, illustrating the regional breakdown provided by the API. The requests.raise_for_status() call ensures that network errors or invalid HTTP responses are handled gracefully, which is a recommended practice for robust API integrations, as detailed in Mozilla's HTTP status codes documentation.