/v1/next_n_holidays

Retrieve the next 'N' upcoming holidays for a calendar.

Description

This endpoint allows you to fetch a specified number of upcoming holidays from a given start date for any supported financial calendar. It's useful for forward-looking analysis or scheduling.

Endpoint

GET https://fincalapi.com/v1/next_n_holidays

Parameters

Name Type Required Description
start_date string ✅ Yes The date from which to start searching for holidays in `YYYY-MM-DD` format (e.g., `2025-01-01`).
calendar string ✅ Yes Holiday calendar to use (e.g., `SIFMA-US`, `NYSE`, `NASDAQ`, `SIFMA-UK`, `SIFMA-JP`).
n integer ✅ Yes The number of upcoming holidays to retrieve (e.g., `5` for the next five holidays).
format string No (Default: `json`) Response format: `json`, `text`, `plain`, `html`, `csv`.

Usage Examples

🧮 Excel Formula

Retrieve a list of the next 3 holidays into an Excel cell. Note: WEBSERVICE might struggle with complex JSON; CSV format is often better for lists.

=WEBSERVICE("https://fincalapi.com/v1/next_n_holidays?start_date=2025-06-01&calendar=SIFMA-US&n=3&format=csv")

💻 VBA Macro

Automate fetching multiple upcoming holidays with VBA:

Function GetNextNHolidays(startDate As String, calendarName As String, numHolidays As Integer) As String
    Dim http As Object
    Set http = CreateObject("MSXML2.XMLHTTP")
    Dim url As String
    url = "https://fincalapi.com/v1/next_n_holidays?start_date=" & startDate & "&calendar=" & calendarName & "&n=" & numHolidays & "&format=json"
    http.Open "GET", url, False
    http.Send
    GetNextNHolidays = http.responseText ' Returns JSON string
End Function

' Example Usage: MsgBox GetNextNHolidays("2025-06-01", "SIFMA-US", 3)

📊 Google Sheets

Easily import the next 5 SIFMA-US holidays into your sheet, formatted as CSV for direct parsing:

=IMPORTDATA("https://fincalapi.com/v1/next_n_holidays?start_date=2025-06-01&calendar=SIFMA-US&n=5&format=csv")

🐍 Python

Fetch and process a list of upcoming holidays in your Python application:

import requests
import json

base_url = "https://fincalapi.com/v1/next_n_holidays"
params = {
    "start_date": "2025-06-01",
    "calendar": "SIFMA-US",
    "n": 3
}

response = requests.get(base_url, params=params)

if response.status_code == 200:
    holidays = response.json()
    print(f"Next {params['n']} holidays for {params['calendar']} from {params['start_date']}:")
    for holiday in holidays:
        print(f"- {holiday['date']}: {holiday['name']}")
else:
    print(f"Error: {response.status_code} - {response.text}")

🖥️ cURL / Terminal

Get the next 2 NYSE holidays from the command line:

curl "https://fincalapi.com/v1/next_n_holidays?start_date=2025-06-01&calendar=NYSE&n=2"

🌐 Browser

Paste the URL directly into your browser to view the JSON output:

https://fincalapi.com/v1/next_n_holidays?start_date=2025-06-01&calendar=SIFMA-US&n=5