Getting started

Base URL

https://api.financecalendarapi.com

Every endpoint is a GET and needs an API key. Start a 14-day free trial at financecalendarapi.com/login, then create a key in your dashboard.

Sending your key

Send it in the Authorization header:

curl -H "Authorization: Bearer $FC_API_KEY" "https://api.financecalendarapi.com/v1/days/2027-12-24?calendars=XNYS,USD"

Calendar apps and spreadsheets can’t send headers, so ?key= works too: https://api.financecalendarapi.com/v1/calendars/XNYS.ics?key=fc_live_…. A key in a URL can end up in logs and app settings, so give those uses their own key and revoke it if it leaks.

Answers about your key and plan

Status	Code	Meaning
401	unauthorized	No key, or the key is wrong or revoked.
403	plan_required	Your trial or subscription has ended, or the request names more calendars than your plan allows.
429	rate_limited	Too many requests a minute for your plan.
429	quota_exceeded	This month’s requests are used; the quota resets on the 1st (UTC).

Successful responses carry X-Quota-Limit and X-Quota-Reset, and X-Quota-Remaining when the count is ready in time (it is counted alongside the answer, never holding it up).

Your first requests

Is 24 December 2027 a business day on the New York Stock Exchange and for US dollar settlement?

curl -H "Authorization: Bearer $FC_API_KEY" "https://api.financecalendarapi.com/v1/days/2027-12-24?calendars=XNYS,USD"

What are the London Stock Exchange’s next three closures from 1 January 2027?

curl -H "Authorization: Bearer $FC_API_KEY" "https://api.financecalendarapi.com/v1/holidays/next?calendars=XLON&from=2027-01-01&n=3"

How many business days are there in December 2027 for the NYSE? (from is counted, to isn’t.)

curl -H "Authorization: Bearer $FC_API_KEY" "https://api.financecalendarapi.com/v1/business-days/count?from=2027-12-01&to=2028-01-01&calendars=XNYS"

Find calendar ids on the calendars page or with GET /v1/calendars.

Dates and today

Dates are YYYY-MM-DD. Wherever a date is accepted you can pass today, which is resolved in the tz time zone (IANA name, default UTC): /v1/days/today?calendars=XASX&tz=Australia/Sydney.

Formats

Add format= to most endpoints:

format	You get
json (default)	The full answer, with data_release saying which release answered.
csv	Rows, for spreadsheets and scripts.
text	One bare value: true/false, a date, or one date per line. Made for WEBSERVICE and IMPORTDATA.

With format=text, /v1/days/{date} returns is_business_day unless you pick another value with field= (is_holiday, is_early_close, close_time, status; all but is_business_day need exactly one calendar).

Limits

Each plan sets a monthly quota, a burst limit per key and how many calendars one request may name; see Pricing. Over the burst limit you get a 429 with code rate_limited; wait a minute and retry. Responses are cached at the edge for five minutes, and every response carries the data release that answered it in the x-data-release header.

Errors

Errors are RFC 9457 problem details with a stable code:

{ "type": "about:blank", "title": "invalid date", "status": 400, "code": "invalid_date", "detail": "date must be a real date as YYYY-MM-DD, got \"2027-02-30\"" }

code	Status	Meaning
invalid_calendar	400	An unknown calendar id, or more than 50.
invalid_date	400	Not a real date, or from after to.
invalid_request	400	Another parameter is wrong; detail says which.
invalid_format	400	format or field can’t be used here.
out_of_coverage	422	The calendar holds no data for that date.
not_a_business_day	422	A business-day date was required and this isn’t one.
not_found	404	No such endpoint or calendar.
unauthorized	401	No API key, or the key is wrong or revoked.
plan_required	403	The trial or subscription has ended, or more calendars than the plan allows.
rate_limited	429	Over the plan’s requests a minute per key.
quota_exceeded	429	This month’s requests are used.
no_data	503	The data is briefly unavailable; retry.

Calling it from a web page

The API sends CORS headers, so a page on any site can call it with fetch. Anyone can read a key in a public page, so call the API from your server, or use a key you can revoke. See JavaScript.