This page is the product-facing reference for all public FinCal API endpoints.
All endpoints are hosted at https://fincalapi.com and return JSON by default.
Most endpoints also accept a format parameter: json (default), text, csv, or html.
Discovery & Intelligence
Endpoints for exploring what is available and what is happening across all calendars.
Returns the trading status (open, holiday, early close, weekend) for all supported calendars — or a single calendar — for today or a specified date. Defaults to today in America/New_York time.
Optional: date (YYYY-MM-DD, defaults to today), calendar (calendar code, defaults to all)
Typical use: Daily dashboard showing market open/close status at a glance.
Returns recent FinCal API product announcements: newly added calendars, data corrections, and new endpoint releases. Defaults to the past 7 days.
Optional: days (int 1–3650, default 7)
Typical use: Checking if any calendar data has been updated or corrected recently.
Returns all supported calendar codes with their display name, country, timezone, region, holiday count, and a link to the details page.
No parameters required.
Typical use: Discovering available calendars and validating calendar codes before making other requests.
Returns upcoming holidays and early-close events across all calendars (or a single calendar) within a configurable look-ahead window.
Optional: calendar (defaults to all), days (1–365, default 30), start_date (YYYY-MM-DD, defaults to today)
Typical use: Pre-populating a trading desk calendar with upcoming market closures.
Date Status & Holiday Lookup
Check whether a specific date is a holiday, early close, or normal business day.
Comprehensive status for a date: returns status (open / full_close / early_close), is_holiday, is_early_close, is_weekend, and close_time.
Required: date (YYYY-MM-DD), calendar
Optional: format (json/text/plain/html/csv)
Typical use: The most complete single-call status check for a trading date.
Example — NYSE Independence Day 2025 (full close):
/v1/day_status?calendar=NYSE&date=2025-07-04
Simple boolean check: returns true if the date is a holiday on the specified calendar, false otherwise. Weekends are not holidays.
Required: date (YYYY-MM-DD), calendar
Optional: format
Typical use: Lightweight yes/no holiday check for conditional logic in spreadsheets or scripts.
Returns whether a date is an early-close day, plus the close_time in local exchange time (e.g. 13:00 for NYSE).
Required: date (YYYY-MM-DD), calendar
Optional: format
Typical use: Risk systems checking whether to cut off order submission early.
Example — NYSE Jul 3 2025 (early close 13:00 ET):
/v1/is_early_close?calendar=NYSE&date=2025-07-03
Returns true if the date is a valid settlement date (i.e. a business day that is not a holiday or weekend).
Required: date (YYYY-MM-DD), calendar
Optional: format
Typical use: Validating that a proposed settlement date is operationally valid.
Example — NYSE Independence Day 2025 (not valid → false):
/v1/is_valid_settlement_date?calendar=NYSE&date=2025-07-04
Extended holiday check: returns is_holiday, status, and close_time in a single response.
Required: date (YYYY-MM-DD), calendar
Typical use: When you need both the holiday flag and the day status in a single call.
Business Day Calculations
Calculate next/previous business days and T+N settlement dates.
Returns the next business day after the given date, skipping weekends and holidays.
Required: date (YYYY-MM-DD), calendar
Optional: format
Typical use: Finding when the market next opens after a holiday or weekend.
Example — after NYSE Independence Day 2025 → Jul 7:
/v1/next_business_day?calendar=NYSE&date=2025-07-04
Returns the most recent business day before the given date, skipping weekends and holidays.
Required: date (YYYY-MM-DD), calendar
Optional: format
Typical use: Roll-back logic: finding the last open day before a given date.
Example — before NYSE Jul 7 2025 → Jul 3 (early close):
/v1/previous_business_day?calendar=NYSE&date=2025-07-07
Calculates the T+N settlement date from a trade date, skipping weekends and holidays. Returns settlement_date as ISO string.
Required: date (YYYY-MM-DD)
Optional: calendar (default SIFMA-US), tplus (int 0–252, default 1), format
Typical use: T+1 or T+2 equity/fixed-income settlement date calculation.
Example — NYSE T+1 from Jul 3 2025 → Jul 7 (skips Jul 4):
/v1/settlement_date?calendar=NYSE&date=2025-07-03&tplus=1
Returns the next valid settlement date on or after the given date (T+0 if the input date is itself a valid settlement date, otherwise T+1).
Required: date (YYYY-MM-DD), calendar
Optional: format
Typical use: Finding the first available settlement date from a given date.
Returns the Nth business day offset from a base date. Positive N moves forward; negative N moves backward. Equivalent to T±N calculation.
Required: date (YYYY-MM-DD), calendar
Optional: n (int −252 to 252, default 0), format
Typical use: General-purpose Nth business day calculation.
Legacy settlement date endpoint — functionally equivalent to /v1/settlement_date. Prefer /v1/settlement_date for new integrations.
Required: date (YYYY-MM-DD), calendar
Optional: tplus (int 0–252, default 0), format
Holiday Calendar Data
Retrieve lists of upcoming holidays and calendar data in bulk.
Returns all holidays (and early-close days) for a calendar within a given date range. Useful for bulk calendar population.
Required: calendar
Optional: start_date (YYYY-MM-DD, defaults to today), end_date (YYYY-MM-DD), months_ahead (1–36, default 12), format
Typical use: Populating a trading system or spreadsheet with all non-trading days for the next year.
Example — NYSE holidays for the next 3 months:
/v1/holidays/range?calendar=NYSE&months_ahead=3
Returns the next N upcoming holidays for a calendar, starting from today or a specified date.
Required: calendar, n (int 1–500)
Optional: start_date (YYYY-MM-DD), format
Typical use: Loading the next few holidays into a UI or notification system.
Plain-text optimized list of upcoming holidays — one date per line with a "Holidays" header. Designed for Excel Web Query imports.
Optional: calendar (default SIFMA-US), n (1–500, default 50), start_date (YYYY-MM-DD), status (full_close / early_close / all)
Typical use: Excel Web Query or legacy system that needs a flat text list of holiday dates.
Example — next 5 NYSE full-close holidays:
/v1/holidays/list?calendar=NYSE&n=5