Economic Calendar CLI and Python Client

Complete CLI and Python reference

The Node and Python clients share a command name and most commands, but their options are not identical. This reference is generated against the shipped source, with behavior checked against the current REST implementation.

• Global options
• All commands
• Pagination and exports
• Environment and configuration
• Exit codes and errors
• Python SDK
• All Python methods
• DataFrame helper

Global options

Node accepts --flag=value or --flag value for value options. Boolean switches such as --json and --csv should be used as bare flags; the Node parser treats the string in --csv=false as truthy. Node does not reject unknown flags, so a misspelled flag may be ignored. Python argparse rejects unknown options and validates integer/choice arguments before requesting data.

All commands and command-specific options

financecalendar next

Next recorded occurrence of a series.

Known times use --tz when supplied. Human output uses your local timezone otherwise; source dates without times are not shifted.

financecalendar today

Today’s releases, NYSE summary and separate exchange closures.

Known times use --tz when supplied. Human output uses your local timezone otherwise; source dates without times are not shifted.

financecalendar week

This week, Monday to Sunday, or the next week.

Known times use --tz when supplied. Human output uses your local timezone otherwise; source dates without times are not shifted.

Neither CLI exposes week-specific pagination or the MCP week tool’s series/category filters. The API defaults to 100 rows; inspect total with –json, then use calendar with the returned from/to dates and –limit/–offset if needed.

financecalendar calendar

Filtered date-window event list; JSON, human text or one CSV page.

financecalendar series

Discover series codes, aliases and recorded next dates.

financecalendar show

One series, its source, next/last and a short upcoming preview.

Known times use --tz when supplied. Human output uses your local timezone otherwise; source dates without times are not shifted.

Human output shows at most eight upcoming entries from the returned series detail, and does not print the full history/dataset. Use –json to inspect the complete response.

financecalendar history

Past records of one series, newest first.

Known times use --tz when supplied. Human output uses your local timezone otherwise; source dates without times are not shifted.

No offset flag. At most 500 records; use calendar with explicit smaller historical windows to retrieve additional rows.

financecalendar holidays

Exchange holidays and early closes for loaded years.

financecalendar status

Exchange session/holiday status, not API health.

Choose one exchange: nyse, sifma, cme, lse, tsx, asx, hkex, euronext, jpx, six, xetra or nse. nasdaq is an API alias for nyse. all is not a market-status exchange.

financecalendar changes

Retained additions, updates and removals, newest first.

financecalendar countries

Country/area counts in the current dataset.

No command-specific options. Global options still apply.

financecalendar health

Python-only API snapshot health and counts, from /status.

No command-specific options. Global options still apply.

Pagination, CSV and output

A CLI command requests one response page and exits; it does not automatically page the entire dataset. calendar defaults to 100 records and accepts at most 500. The date difference between –from and –to must be at most 92 days. Inspect count/total with –json and advance –offset, or use the Python iter_calendar helper for automatic paging across larger date ranges.

financecalendar calendar --from 2026-11-01 --to 2026-11-30 --country US,GB --limit 500 --offset 0 --json
financecalendar calendar --from 2026-11-01 --to 2026-11-30 --country US,GB --limit 500 --offset 500 --json
financecalendar calendar --from 2026-11-01 --to 2026-11-30 --country US,GB --limit 500 --csv > november.csv

CSV output is API CSV text for that requested page. Repeated CSV requests each include a header; merge deliberately instead of blindly appending files. –csv applies only to calendar. The CLIs do not expose an ICS switch: use HTTP format=ics or the REST reference. JSON preserves nulls, exact/range/date-only timing fields, source and recorded values; human output is a summary and is not a lossless export. Numeric zero values should be inspected in raw JSON because current human formatting only prints truthy previous/actual/consensus values.

Environment, precedence and request behavior

Exit codes and errors

For HTTP errors, 400 means an invalid parameter, 401 a rejected key, 404 an unknown/missing resource, 429 an exhausted daily allowance and 503 an unavailable snapshot. Retry-After is reported when supplied for 429; neither CLI sleeps and retries automatically. Check exit status before treating an output file as a successful export.

Python SDK reference

Import Client, FinanceCalendarError and to_dataframe from financecalendar. The synchronous client returns plain dictionaries/lists containing API JSON; it does not create typed event objects, run background updates or fill missing observations.

Client(base_url: str | None=None, api_key: str | None=None, timeout: float=20, transport: httpx.BaseTransport | None=None)

Close the client after use, preferably with a context manager:

from financecalendar import Client

with Client(timeout=30) as calendar:
    response = calendar.next("uk-cpi", tz="Europe/London")
    print(response["next"]["date"])

All public Client methods

close()

Close the underlying httpx client. Returns None; also called when leaving a with Client() block.

calendar(**params: Any)

GET /calendar. Returns one JSON response page. Keyword parameters: from_, to, country, impact, category, series, include_holidays, status, tz, limit, offset. Defaults and limits match the calendar tool above: today to +14 days, at most a 92-day date difference, 100 rows by default and 500 maximum.

calendar_csv(**params: Any)

GET /calendar with format=csv. Same calendar keyword parameters; returns CSV text (str), not a dictionary. One response page only.

iter_calendar(from_: str | date, to: str | date, **params: Any)

Yield individual event dictionaries across an inclusive start/end range. Splits into consecutive requests of at most the API’s 92-day date difference and pages each using limit/offset. Default page limit 500. Accepts strings or datetime.date for the bounds; reversed bounds raise ValueError. Discards a supplied offset and manages its own offsets. Preserves available snapshot coverage; a long range does not create missing history.

today(country: str | None=None, tz: str | None=None)

GET /today. Accepts country and tz only in this SDK signature; returns date, market, count, events and market_holidays. Selection uses America/New_York’s date.

week(which: str='this', **params: Any)

GET /week. which defaults to this; next selects the next Monday–Sunday week. Keyword parameters pass through to HTTP, including country, impact, category, series, include_holidays, tz, limit and offset. Unlike the CLI/MCP week interfaces, SDK kwargs can page this endpoint.

next(series: str, country: str | None=None, tz: str | None=None)

GET /next. Required series code/alias, optional one-country override and IANA tz. Returns series identity and next record; 404 if no matching upcoming event is loaded.

series(**params: Any)

GET /series. Keyword parameters: country, category, kind (instance or holiday). Returns the declared series directory with recorded counts and next dates.

series_detail(code: str, tz: str | None=None)

GET /series/{code}. Required code/alias is URL-encoded; optional tz. Returns series, next, last, upcoming, history and dataset where published. next/last/dataset can be null.

history(series: str, **params: Any)

GET /history. Required one-series code/alias; keyword parameters from_, to, limit and tz. Defaults to loaded snapshot start through today, newest first. Default limit 100, maximum 500; no offset.

holidays(exchange: str='nyse', year: int | None=None)

GET /holidays. exchange defaults to nyse; year None currently returns all loaded years. Pass a four-digit integer year for one year. exchange=all is supported; an unloaded requested year returns 404.

market_status(exchange: str='nyse')

GET /market-status. One exchange, default nyse. Returns computed session/holiday status. all is not supported here.

changes(since: str | datetime | None=None, **params: Any)

GET /changes. since accepts an ISO 8601 string, datetime (serialized with isoformat) or None for 24 hours ago. Extra keyword parameters: series, change (added/updated/removed) and limit (1–500, default 100). Retention at most 30 days; no offset/cursor.

countries()

GET /countries. No parameters. Returns recorded countries/areas with series and event counts.

status()

GET /status. No parameters. API snapshot health, generation time/age and counts. This is distinct from market_status.

openapi()

GET /openapi. No parameters. Returns the current OpenAPI 3.1 dictionary.

Python keyword conversion and pagination

Extra keyword arguments are passed to HTTP; the client is a thin wrapper, not local schema validation. from_ becomes from. include_holidays=True becomes include=holidays. Lists, tuples and sets become comma-separated strings; date/datetime values become ISO strings. None, empty strings and False are omitted. Use date values or YYYY-MM-DD strings for calendar bounds; an ISO datetime is not a valid calendar date filter.

from datetime import date
from financecalendar import Client

with Client() as calendar:
    for event in calendar.iter_calendar(
        date(2026, 1, 1), date(2026, 12, 31),
        country=["US", "GB"], impact="high", limit=500,
    ):
        print(event["id"], event["date"], event["source_url"])

Python exceptions

HTTP 4xx/5xx responses raise FinanceCalendarError. Inspect status: int, message: str and retry_after: int | None. Numeric Retry-After seconds are preserved; an absent/non-numeric header gives None. Transport/timeouts raise httpx exceptions. Malformed JSON and local validation can raise ValueError. The SDK does not convert these into success responses.

import httpx
from financecalendar import Client, FinanceCalendarError

try:
    with Client(timeout=30) as calendar:
        response = calendar.calendar(country="US", limit=100)
except FinanceCalendarError as error:
    print(error.status, error.message, error.retry_after)
except httpx.HTTPError as error:
    print("Network request failed:", error)

Optional to_dataframe(events) helper

Install the optional dependency from the checked-out Python source with .venv/bin/python -m pip install ".[pandas]". Pass a list of event dictionaries or an entire calendar/history response dictionary. Returns a pandas DataFrame; parses date with errors=”coerce” and release_at_utc as UTC datetimes with errors=”coerce”. Unknown/invalid timestamps become NaT. The helper does not fetch missing records, page responses or invent results.

from financecalendar import Client, to_dataframe

with Client() as calendar:
    response = calendar.history("us-cpi", limit=24)
frame = to_dataframe(response)
print(frame[["date", "consensus", "actual"]])

Without pandas installed, calling the helper raises ImportError. A response with no events produces an empty DataFrame and may have no columns; check before selecting column names. The package also exports DEFAULT_BASE, MAX_RANGE_DAYS (92) and __version__.