FinCal API - Endpoint Reference

API key required — All /v1/ endpoints require a free API key as of June 20, 2026. Example links below point to browser-friendly previews where available.

Get an API key →

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.

GET /v1/today

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.

Try it: /preview/today

GET /v1/announcements

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.

Docs: announcements.html

GET /v1/calendars

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.

Docs: calendars.html

GET /v1/upcoming

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.

Try it: /preview/upcoming

Date Status & Holiday Lookup

Check whether a specific date is a holiday, early close, or normal business day.

GET /v1/day_status

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.

Try it: /preview/holiday-check · Docs: day_status.html

GET /v1/is_holiday

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.

Try it: /preview/holiday-check · Docs: is_holiday.html

GET /v1/is_early_close

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.

Try it: /preview/holiday-check · Docs: is_early_close.html

GET /v1/is_valid_settlement_date

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.

Try it: /preview/settlement-date · Docs: is_valid_settlement_date.html

GET /v1/is_holiday_verbose

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.

Try it: /preview/holiday-check

Business Day Calculations

Calculate next/previous business days and T+N settlement dates.

GET /v1/next_business_day

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.

Docs: next_business_day.html

GET /v1/previous_business_day

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.

Docs: previous_business_day.html

GET /v1/settlement_date

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.

Try it: /preview/settlement-date · Docs: settlement_date.html

GET /v1/next_settlement_date

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.

Try it: /preview/settlement-date · Docs: next_settlement_date.html

GET /v1/get_nth_settlement_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.

Try it: /preview/settlement-date

GET /v1/settlement

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

Try it: /preview/settlement-date

Holiday Calendar Data

Retrieve lists of upcoming holidays and calendar data in bulk.

GET /v1/holidays/range

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.

Try it: /preview/holiday-range · Docs: holidays_range.html

GET /v1/next_n_holidays

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.

Try it: /preview/holiday-range · Docs: next_n_holidays.html

GET /v1/holidays/list

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.

Docs: next_n_holidays.html