/v1/holidays/range

Retrieves a list of holidays within a specified date range.

Description

This endpoint returns a list of all official holidays for a specified financial calendar within a defined date range. You can define the range by providing a `start_date` and `end_date`, or by specifying a number of `months_ahead` from the current date. This is highly useful for calendar generation, forward-looking analysis, and compliance checks.

Endpoint

GET https://fincalapi.com/v1/holidays/range

Parameters

Name Type Required Description
calendar string ✅ Yes Holiday calendar name, e.g., `SIFMA-US`, `NYSE`, `NASDAQ`, `SIFMA-UK`, `SIFMA-JP`.
start_date string Conditional (Required with `end_date`) Start date for the range in `YYYY-MM-DD` format (e.g., `2025-01-01`).
end_date string Conditional (Required with `start_date`) End date for the range in `YYYY-MM-DD` format (e.g., `2025-12-31`).
months_ahead integer Conditional (Alternative to `start_date`/`end_date`) Number of months from today to look ahead for holidays (e.g., `12`). If provided, `start_date` and `end_date` are ignored.
format string No (Default: `json`) Response format: `json`, `text`, `plain`, `html`, `csv`.

Note: You must provide either `start_date` and `end_date` *or* `months_ahead`.

Usage Examples

🧮 Excel Formula (CSV Format)

Import a list of SIFMA-US holidays for the next 12 months into an Excel sheet. The `format=csv` parameter makes this ideal for direct import.

=WEBSERVICE("https://fincalapi.com/v1/holidays/range?calendar=SIFMA-US&months_ahead=12&format=csv")

💻 VBA Macro

Retrieve a holiday range programmatically with VBA:

Function GetHolidayRange(calendarName As String, startDate As String, Optional endDate As String = "", Optional monthsAhead As Integer = 0) As String
    Dim http As Object
    Set http = CreateObject("MSXML2.XMLHTTP")
    Dim url As String
    url = "https://fincalapi.com/v1/holidays/range?calendar=" & calendarName
    If Not IsEmpty(startDate) Then url = url & "&start_date=" & startDate
    If Not IsEmpty(endDate) Then url = url & "&end_date=" & endDate
    If monthsAhead > 0 Then url = url & "&months_ahead=" & monthsAhead
    url = url & "&format=json" ' Request JSON for easier parsing in VBA if needed

    http.Open "GET", url, False
    http.Send
    GetHolidayRange = http.responseText ' Returns JSON string
End Function

' Example: MsgBox GetHolidayRange("NYSE", "2025-01-01", "2025-12-31")
' Example with months_ahead: MsgBox GetHolidayRange("NASDAQ", "", "", 6)

📊 Google Sheets

Import holidays for a specific range directly into Google Sheets:

=IMPORTDATA("https://fincalapi.com/v1/holidays/range?calendar=NYSE&start_date=2025-01-01&end_date=2025-06-30&format=csv")

🐍 Python

Fetch and process a list of holidays for a specific calendar and time frame:

import requests
import json
from datetime import date

base_url = "https://fincalapi.com/v1/holidays/range"

# Example 1: Using start_date and end_date
params1 = {
    "calendar": "SIFMA-UK",
    "start_date": "2025-01-01",
    "end_date": "2025-03-31"
}
response1 = requests.get(base_url, params=params1)
if response1.status_code == 200:
    uk_holidays = response1.json()
    print("UK Holidays (Jan-Mar 2025):", json.dumps(uk_holidays, indent=2))

# Example 2: Using months_ahead
params2 = {
    "calendar": "SIFMA-US",
    "months_ahead": 6
}
response2 = requests.get(base_url, params=params2)
if response2.status_code == 200:
    us_holidays_next_6m = response2.json()
    print("\nUS Holidays (Next 6 months):", json.dumps(us_holidays_next_6m, indent=2))
else:
    print(f"Error: {response2.status_code} - {response2.text}")

🖥️ cURL / Terminal

Get holidays for the next 12 months for NASDAQ, in JSON format:

curl "https://fincalapi.com/v1/holidays/range?calendar=NASDAQ&months_ahead=12"

🌐 Browser

View a range of holidays directly in your browser as an HTML table:

https://fincalapi.com/v1/holidays/range?calendar=SIFMA-JP&start_date=2025-04-01&end_date=2025-09-30&format=html