FinCal API - /calendars

Description

Returns a complete list of all supported financial calendar codes along with metadata for each one. Use this endpoint for discovery and to validate calendar names before passing them as parameters to other endpoints. All calendars returned have supported: true — the API will never return a calendar code that it cannot query.

Endpoint

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

Parameters

This endpoint takes no parameters.

Response Fields

Field	Type	Description
`code`	string	The calendar identifier used in all other API calls (e.g., `NYSE`, `SIFMA-US`).
`name`	string	Human-readable full name of the exchange or organization.
`description`	string	Brief description of the calendar and what it covers.
`country`	string	Country or territory the calendar belongs to (e.g., `US`, `UK`, `Japan`).
`region`	string	Geographic region: `North America`, `Europe`, or `Asia-Pacific`.
`timezone`	string	IANA timezone string for the exchange's primary trading hours (e.g., `America/New_York`).
`supported`	boolean	Always `true` for all returned entries.
`holiday_count`	integer	Number of holiday/early-close dates stored for this calendar.
`details_slug`	string	Path to the human-readable detail page for this calendar (e.g., `nyse.html`).
`note`	string	Optional. Present on alias calendars (e.g., NASDAQ and AMEX share the NYSE schedule).

Request Example

All /v1/ endpoints require an API key. Get one free →

GET /v1/calendars — Complete list of all 14 supported calendars with metadata

Usage Examples

🐍 Python

import requests

API_KEY = "fincal_live_YOUR_KEY_HERE"
headers = {"Authorization": f"Bearer {API_KEY}"}

response = requests.get("https://fincalapi.com/v1/calendars", headers=headers)
data = response.json()

print(f"Total supported calendars: {data['count']}")
for cal in data["calendars"]:
    print(f"  {cal['code']:12} {cal['name']} ({cal['country']}, {cal['timezone']})")

🖥️ cURL / Terminal

curl -H "Authorization: Bearer fincal_live_YOUR_KEY_HERE" \
  "https://fincalapi.com/v1/calendars"

Example JSON Response

Abbreviated example showing two entries from /v1/calendars:

{
  "calendars": [
    {
      "code": "NYSE",
      "name": "New York Stock Exchange",
      "description": "NYSE equity market holiday calendar.",
      "country": "US",
      "region": "North America",
      "timezone": "America/New_York",
      "supported": true,
      "holiday_count": 21,
      "details_slug": "nyse.html"
    },
    {
      "code": "NASDAQ",
      "name": "NASDAQ",
      "description": "NASDAQ stock market holiday calendar (shares NYSE schedule).",
      "country": "US",
      "region": "North America",
      "timezone": "America/New_York",
      "supported": true,
      "holiday_count": 21,
      "note": "Shares NYSE calendar",
      "details_slug": "nasdaq.html"
    }
    ...
  ],
  "count": 14
}

Common Use Cases

Discovery — enumerate all available calendar codes before building a query UI or dropdown
Validation — confirm a calendar code is supported before passing it to /v1/today, /v1/upcoming, or settlement endpoints
Metadata display — surface display names, timezones, and regions to end users
Documentation generation — pull calendar metadata programmatically to build reference docs

Notes & Limitations

Currently 14 calendars are supported. New calendars are announced via /v1/announcements.
Some calendars are aliases for another: NASDAQ and AMEX share the NYSE holiday schedule. These entries include a note field indicating the shared source.
The holiday_count reflects all stored holiday and early-close records, not just full-close holidays.
The details_slug field points to the human-readable calendar detail page served at /{slug} (e.g., /nyse.html).