Financial Calendar API

Description

Returns upcoming holidays and early-close events within a configurable look-ahead window, either across all supported calendars or for a single specified calendar. Results are sorted by date, then calendar code. This is useful for forward-looking settlement planning, trading calendars, and risk management workflows that need to know when markets will be closed or closing early.

Endpoint

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

Parameters

Name	Type	Required	Description
`days`	integer	No — defaults to 30	Number of calendar days ahead to search (1–365). The window runs from `start_date` to `start_date + days`.
`calendar`	string	No — defaults to all calendars	A specific calendar code, e.g., `NYSE`, `LSE`, `SIFMA-US`. Omit to return events across all 14 supported calendars.
`start_date`	string	No — defaults to today (America/New_York)	Start of the look-ahead window in `YYYY-MM-DD` format. Omit to start from today.

Default Behavior

With no parameters, /v1/upcoming returns all holidays and early-close events in the next 30 calendar days across all 14 supported calendars, starting from today's date in America/New_York time. Events are sorted by date, then by calendar code.

Clickable Examples

Click any link to see live JSON output:

/v1/upcoming?days=30 — All upcoming events in the next 30 days across all calendars
/v1/upcoming?calendar=NYSE&days=30 — NYSE holidays and early closes in the next 30 days
/v1/upcoming?calendar=NYSE&start_date=2025-07-01&days=14 — NYSE events in the first two weeks of July 2025 (July 3 early close + July 4 holiday)
/v1/upcoming?days=90 — All events in the next 90 days across all calendars

Usage Examples

🐍 Python

import requests

# All calendars, next 30 days
response = requests.get(
    "https://fincalapi.com/v1/upcoming",
    params={"days": 30}
)
data = response.json()
print(f"Found {data['event_count']} events from {data['start_date']} to {data['end_date']}")
for event in data["events"]:
    print(f"  {event['date']} [{event['calendar']}] {event['event_type']}")

# Single calendar
response = requests.get(
    "https://fincalapi.com/v1/upcoming",
    params={"calendar": "NYSE", "days": 30}
)
print(response.json())

🖥️ cURL / Terminal

# All calendars, next 30 days
curl "https://fincalapi.com/v1/upcoming?days=30"

# NYSE only
curl "https://fincalapi.com/v1/upcoming?calendar=NYSE&days=30"

Example JSON Response

For /v1/upcoming?calendar=NYSE&start_date=2025-07-01&days=7:

{
  "start_date": "2025-07-01",
  "end_date": "2025-07-08",
  "days": 7,
  "calendars_queried": ["NYSE"],
  "event_count": 2,
  "events": [
    {
      "calendar": "NYSE",
      "date": "2025-07-03",
      "event_type": "early_close",
      "close_time": "13:00"
    },
    {
      "calendar": "NYSE",
      "date": "2025-07-04",
      "event_type": "holiday",
      "close_time": null
    }
  ]
}

Common Use Cases

Settlement planning — identify non-settlement days ahead of time to avoid failed trades
Trading calendar widgets — display upcoming market closures to traders and operations staff
Risk management — flag upcoming early-close days that compress trading windows
Cross-market awareness — query all calendars at once to see global holiday clusters that affect multi-market settlement
Automated notifications — trigger alerts when an exchange closure falls within the next N days

Notes & Limitations

The maximum look-ahead window is 365 days. Requests with days above 365 return HTTP 422.
When no start_date is provided, today's date is determined using the America/New_York timezone.
Only calendar codes returned by /v1/calendars are accepted. An unknown calendar code returns HTTP 400.
Results include both full holidays (event_type: "holiday") and early-close days (event_type: "early_close"). Weekends are not included.
The close_time field is null for full holidays; it returns a time string (e.g., "13:00") for early-close events.
Calendar data covers 2025–2026. Events outside that range will not appear even if the window extends there.