Skip to main content

financecalendar

Bring economic-release dates, consensus forecasts and published results into Python, pandas and terminal workflows with the financecalendar.com API. Paid plans support release forecasts for 60 mapped headline measures across 10 economies. Available values appear in each event’s forecasts field, refreshed hourly and labelled with their update time and source count. Coverage varies by release; the mapped total is not the number with a live forecast at any moment. Provider consensus now spans 12 selected US headline release series, with source-linked actual/prior values for covered records. The same API also supplies central bank decisions, exchange holidays and source-backed crypto events. Use each record’s metric, reference period and source evidence when comparing expectations with results.

Paid API plans include annually billed Starter (1,000 requests/UTC day and 25,000/UTC calendar month). Build is US$9.99/month or US$95.90/year for 100,000/day. Scale is US$29/month or US$278.40/year for 1,000,000/day and the complete current dataset download. Inspect the public sample before choosing a plan. Check the current Starter quote or the machine-readable offer.

Free Developer is ongoing schedule JSON access: 100 successful responses per UTC calendar month, at most 10 per UTC day, one verified account and one API key issued after approval (allow up to 48 hours for review), no card or automatic charge. Use GET /calendar or /today for economic-release and central-bank schedules from UTC today through the following six days, with up to 20 records and no pagination. Country (up to three codes) and impact filters are supported; from and to may narrow, but cannot extend, the seven-date UTC window. Free /today is the current UTC date’s schedule, without market-status or holiday payloads. Free responses omit forecasts, consensus, actual/prior figures and numerical evidence, and mark releases that have them (figures_available, result_available); Starter adds release forecasts across 10 economies, these recorded fields, wider dates/history, formats, hosted MCP and browser tools.

The public calendar remains free to browse. Hosted MCP, status and the wider data examples below require a paid plan. The public sample, product offer and OpenAPI document can be read directly without a key; SDK requests consistently use your configured account key. Set FC_API_KEY securely or pass Client(api_key=...). Missing credentials fail before any network request.

Starter is billed annually and includes 1,000 requests per UTC day and 25,000 per UTC calendar month. Build includes 100,000 requests per day and Scale 1,000,000 per day. All account keys share the applicable allowance. Daily usage resets at 00:00 UTC; monthly usage resets at 00:00 UTC on the first day of the next calendar month. Existing paid customers retain their contracted prices and applicable allowances; check your account or /keys/me for effective limits. See current plans for billing options and complete snapshot downloads.

Free Developer counts successful committed HTTP 200 JSON schedule responses, including valid empty responses. Invalid or denied requests, quota errors and pre-commit server failures do not consume its allowance. Usage is shared by the account and survives key rotation; daily and monthly resets follow UTC. Already-enrolled evaluations retain their original 25-successful-request budget, 48-hour clock from first use and original scope. New trial enrolment is closed. Existing paid, legacy and custom access grants are preserved; no account is silently converted to Free Developer.

For paid plans, daily and monthly quota usage counts admitted requests, not successful responses. Requests refused with HTTP 429 do not consume more allowance; a request that passes the quota check can still consume allowance if it later returns an error. Retained per-key request history remains a separate attempt diagnostic and can include rejected requests.

export FC_API_KEY='fc_live_YOUR_ACTUAL_KEY'

Use your real key and keep it private; never include it in a shared notebook or URL.

Install the Python client

Requires Python 3.10 or newer. To install the PyPI release when available, use a virtual environment:

python -m pip install financecalendar
financecalendar --help

For the optional pandas helpers, install "financecalendar[pandas]". For a version-pinned download of the earlier beta, see the GitHub archives and checksums.

Install from source

To build directly from the public source repository:

git clone https://github.com/awarenessdays/financecalendar-api.git
cd financecalendar-api/clients/python
python -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/financecalendar --help

Use .venv\Scripts\python and .venv\Scripts\financecalendar on Windows. Install ".[pandas]" instead of . for the optional DataFrame helper.

The runtime dependencies are httpx and, on Windows, tzdata for time zone names.

Quick start

A first bounded request within free access:

from financecalendar import Client

with Client() as fc:  # reads your private FC_API_KEY
    sample = fc.calendar(limit=10)
    print(sample["events"])

The following /next example and the wider methods below require a paid plan:

from financecalendar import Client

fc = Client()                                  # requires FC_API_KEY; reads FC_API_BASE if set
nxt = fc.next("fomc")["next"]
print(nxt["date"], nxt["time_et"], nxt["consensus"], nxt["url"])

week = fc.week(country="us", impact="high", tz="Europe/London")
for e in week["events"]:
    print(e["date"], e["time_local"], e["name"], e["consensus"])

Every method returns the API's JSON as plain dicts and lists.

Paid event responses include nullable period and release_stage fields. Human CLI output shows these details when provided, labels unknown economic release times time unknown, and retains all day for exchange holidays.

Method Endpoint
calendar(**params) GET /calendar (from_, to, country, impact, category, asset, series, include_holidays, status, tz, limit, offset)
crypto_calendar(asset=None, **params) GET /calendar with category=crypto forced; canonical asset IDs
calendar_csv(**params) GET /calendar?format=csv, returns the CSV text
iter_calendar(from_, to, **params) yields every event over any span: pages with offset/limit and splits ranges longer than 92 days
today(country=None, tz=None) GET /today
week(which="this", **params) GET /week
next(series, country=None, tz=None) GET /next
series(**params) GET /series
series_detail(code, tz=None) GET /series/{code}
history(series, **params) GET /history
enrichment_history(series, **params) GET /enrichment/history; evidenced results with from_, to, limit, offset, ledger_cursor and publication_revision
enrichment_editions(event_id, **params) GET /enrichment/editions; accepted editions with limit, offset and both pagination pins
holidays(exchange="nyse", year=None) GET /holidays
market_status(exchange="nyse") GET /market-status
changes(since=None, **params) One page from GET /changes; accepts series, change, limit and cursor
countries() GET /countries
status() GET /status
quality(**params) GET /quality, the current snapshot's quality and evidence-coverage report
observations(**params) One page from GET /observations; accepts series, event_id, role, reference_period, limit, offset and snapshot_generated_at
openapi() GET /openapi

Economic results and editions

with Client() as fc:
    results = fc.enrichment_history("us-adp", from_="2026-01-01", limit=20)
    for release in results["releases"]:
        print(release["actual"], release["consensus"], release["selected_editions"])
        editions = fc.enrichment_editions(release["event_id"], limit=100)

These endpoints cover us-jolts, us-adp, us-ism-services and us-trade-balance when the enrichment service is enabled and accepted evidence is available. First pages return ledger_cursor and publication_revision. Follow next_offset with the same filters and both pins; they are required when offset is above zero. The ledger pin excludes later appends, while the publication pin prevents combining different published views. On HTTP 409, restart at offset zero without the old pins. Values retain exact decimal strings, nulls, reference periods and provenance. available_at describes recorded source availability; received_at records Finance Calendar's receipt. A provider archive is labelled separately from an engine capture. as_of_supported is false; these responses do not reconstruct an original first print. Normal account authentication and quota rules apply.

Long ranges and paging

from datetime import date

rows = list(fc.iter_calendar(date(2026, 1, 1), date(2026, 12, 31), country="us,gb", impact="high"))

For changes, follow next_cursor until has_more is false, passing that cursor alone to fc.changes(cursor=...). Advance the since checkpoint only after all pages finish. HTTP 409 means the snapshot changed: restart with the original since and filters and deduplicate repeated changes. Reload the full snapshot if the checkpoint is outside the 30-day retention window. The CLI accepts the same continuation with financecalendar changes --cursor ....

Errors

Any 4xx or 5xx raises FinanceCalendarError with the API's message:

from financecalendar import Client, FinanceCalendarError

try:
    Client().calendar(tz="Mars/Olympus")
except FinanceCalendarError as exc:
    print(exc.status, exc.message, exc.retry_after)   # 400, "tz must be an IANA timezone...", None

On a 429 the retry_after attribute holds the Retry-After seconds.

pandas

from financecalendar import Client, to_dataframe

df = to_dataframe(Client().history("us-cpi", limit=24))
print(df[["date", "consensus", "actual"]])

to_dataframe accepts a list of event rows or a whole calendar/history response and parses date and release_at_utc to datetimes. pandas is imported only when you call it.

Configuration

Setting Constructor Environment variable
Base URL Client(base_url=...) FC_API_BASE (default https://www.financecalendar.com/wp-json/fc/v1; an edge mirror at https://api.financecalendar.com/v1 is planned)
API key Client(api_key=...) FC_API_KEY, sent as X-API-Key
Timeout Client(timeout=20)

Client is also a context manager and has close().

Crypto coverage

from financecalendar import Client, to_dataframe

with Client() as fc:
    series = fc.series(category="crypto")  # discover canonical series and assets
    calendar = fc.crypto_calendar(asset="ethereum")
    nxt = fc.next("ethereum-network-upgrades", asset="ethereum")
    rows = list(fc.iter_calendar("2026-10-01", "2027-03-01", category="crypto", asset="ethereum"))

asset passes through calendar, calendar_csv, iter_calendar, today, week, next, series, series_detail and history. Asset IDs are canonical names such as ethereum, not ticker symbols such as ETH. Crypto rows have country=None and may have impact=None. A country filter excludes global rows.

Estimated month/quarter/year windows retain date_window_start/end; date is only their lower-bound index. Range queries include overlapping windows, and iter_calendar deduplicates stable IDs across chunks. A scheduled testnet fork is distinct from mainnet and is not proof of an observed activation. Inspect crypto.environment, crypto.activation_status, verification_url, verification_method, manually_reviewed_at, last_verified_at and data_stale.

to_dataframe retains nested assets, crypto, source_license and source_rights plus the optional discovery_url, parses estimated date-window bounds, and adds asset_ids, asset_symbols, crypto_event_type, crypto_network, crypto_exchange, crypto_environment and crypto_activation_status. It preserves null countries and recorded zeros.

financecalendar series --category crypto
financecalendar calendar --category crypto --asset ethereum --json
financecalendar next ethereum-network-upgrades --asset ethereum --tz UTC

Coverage includes network schedules, vesting installments, governance voting deadlines and issuer supply projections. The crypto object retains source metadata:

  • Unlocks: schedule_id, installment, beneficiaries, unlock_status, date_basis, token_amount and token_amount_basis when supplied. Scheduled or upper-bound quantities do not prove transfer or sale.
  • Governance: dao, space_id, proposal_id, optional proposal_title, voting_start, voting_end, voting_state, voting_type and choice_count. A voting deadline is not approval, rejection or execution.
  • Supply projections: projection_status, projected_circulating_supply, projected_monthly_supply_change and date_basis. Issuer estimates are not confirmed unlocks or observed circulating supply; decimal strings retain source precision.

Public records combine licensed feeds and independently normalised factual records. source_license carries actual upstream licensing requirements; source_rights carries factual provenance, access basis, review time, attribution and notice without asserting a publisher copyright licence. Either may be null. An optional discovery_url is a discovery-page link, potentially from an aggregator, and is separate from primary source_url and verification evidence. CoinMarketCal internal API evaluation payloads are excluded. Coverage varies by asset and source; empty results do not establish comprehensive coverage.

Raw JSON, calendar_csv and CLI --csv retain these fields; CSV stores nested objects as JSON cells. Preserve record-level rights and licence metadata when sharing data. PatternPlus records require the linked credit Data: PatternPlus, carried in source_license.attribution and source_license.attribution_url, alongside the licence link and adaptation notice. Human CLI output includes source credits, attribution links and factual notices, but remains a summary; use JSON/CSV to retain every metadata field when redistributing.

CLI

financecalendar next fomc
financecalendar next cpi --country uk --tz Europe/London
financecalendar today
financecalendar week --next --impact high
financecalendar calendar --from 2026-11-01 --to 2026-11-30 --country us,gb --holidays
financecalendar calendar --from 2026-11-01 --to 2026-11-30 --csv > november.csv
financecalendar series --country gb
financecalendar show boe
financecalendar history us-cpi --limit 12
financecalendar holidays lse 2027
financecalendar status hkex
financecalendar changes --since 2026-10-18T00:00:00Z
financecalendar countries
financecalendar health

Add --json to any command for the raw response. Global options (accepted before or after the command): --json, --tz ZONE, --api-key KEY, --base-url URL and --version. health prints the API's own /status (snapshot age and counts). Times are shown in your local zone unless you pass --tz:

$ financecalendar --tz America/New_York next fomc
Wed 28 Oct 14:00 ET  FOMC Rate Decision (US)  cons. Hold at 3.50-3.75%  prior Hold
https://www.financecalendar.com/event/fomc-rate-decision-october-2026/

Data terms

Free Developer provides the bounded schedule scope above; richer data and wider features require a paid plan. Use is subject to the current API service terms and applicable source terms and credits. Include a visible link to financecalendar.com wherever the data appears. Retain each record's source_license requirements, including attribution_url, source and licence links, full notices and adaptation labels; PatternPlus records require Data: PatternPlus. Preserve source_rights attribution, evidence, access basis and notice for independently normalised facts. This rights metadata does not assert a publisher copyright licence. Earnings dates are not included. Full terms, rate limits and the changelog: financecalendar.com/api.

Source and issues

Client source and tests · Report an issue.

Development

python3 -m venv .venv
.venv/bin/pip install -e ".[test]"
.venv/bin/python -m pytest -q        # offline: every request is answered by httpx.MockTransport fixtures
.venv/bin/python -m build            # wheel + sdist into dist/

Client source code: MIT, Awareness Days Ltd / financecalendar.com. The code licence does not license upstream data; data terms and record-level rights metadata apply separately.

Official numerical observations

Where a result is explicitly mapped, responses retain observations, observation_status, observation_metric_id and observation_fields. Each observation identifies its value, unit, reference period, source, engine capture time and any revisions. The previous value uses the previous reference period at the current observed vintage; it is not a reconstructed original first print. Numerical-source staleness is separate from calendar schedule staleness. Text output explains this distinction and retains source credits; JSON and CSV retain the available lineage. Unknown consensus stays absent. See the REST reference for the contract.

Expanded US coverage brings consensus forecasts and release results together for CPI, nonfarm payrolls, PPI, retail sales, headline PCE, ISM Manufacturing, industrial production, Consumer Confidence, JOLTS, ADP employment, ISM Services and goods-and-services Trade Balance. Inspect each value's source, reference period and recorded edition through its numerical evidence. Official observations retain priority for mapped actual/prior values. BLS payroll value is already converted to jobs. source_value remains in source_unit thousands of jobs with conversion_factor="1000"; do not multiply the canonical value again. publisher_reported_revisions retains publisher units and is separate from engine-observed revision_history. Neither establishes original first prints. Preserve document manifests, occurrence bindings and record-level source credits when reusing data.

Query quality and observation evidence

The current Python client includes methods for inspecting data quality and publication evidence.

with Client() as fc:
    quality = fc.quality()
    evidence = fc.observations(series="us-cpi", role="actual", limit=100)
    for row in evidence["observations"]:
        print(row["event_id"], row["observation"])

Both methods use the same API key, quotas and FinanceCalendarError handling as the calendar. They return unmodified nested JSON, including source lineage, engine-observed revision history, null values and recorded zeros. quality() reports the current engine snapshot; observations() returns validated evidence per event and role, including retained stale observations where endorsed by the engine contract. Missing evidence does not establish that a release has no result.

For observation paging, pass offset=page["next_offset"] together with snapshot_generated_at=page["snapshot_generated_at"] and the identical filters while has_more is true. On HTTP 409, restart at offset zero against the current snapshot. An observation_id can occur in several event/role entries.

These are engine-observed current vintages. They do not reconstruct original first prints or arbitrary historical knowledge. The API rejects as_of; the client passes it through so callers receive the server's normal HTTP 400 error.

Korean official calendars

Filter with country=KR (aliases korea and south korea) or a kr- series code. MODS and BOK schedules retain explicit reference periods and release stages; unsupported or ambiguous identities are withheld. Coverage ends at the publisher's verified horizon: a year selector does not establish published dates.

These records currently have date precision and all_day=false. BOK's raw media-publication clock is carried in source_clock, distinct from ECOS availability. Its timezone has not been explicitly verified, so release_at_utc and local display time remain null. release_tz=Asia/Seoul identifies the calendar jurisdiction; do not use it to manufacture an instant. Numerical results and consensus remain null until separately verified by an implemented result source.

Indian official release dates

MoSPI dates use country=IN and in- series codes. Publisher-planned dates remain estimated, with no computed holiday adjustment or clock. The source's explicitly recorded publication dates take precedence. A publication month is not the measured month: period and source_reference_period stay null where omitted. GDP publications may bundle multiple quarterly/annual estimate components; these retain their original description and do not imply one headline result. Reference-year conflicts and indistinguishable release identities are held for review. Inspect per-source health and the verified fiscal-year horizon.

Historical archive CLI and Python

Historical archive access: Starter includes one year, Build includes ten years, and Scale includes all available history. Stored depth varies by exact measure and source. Free Developer excludes the archive. The existing recent-event /history route and curated datasets retain their established access; previous agreements are preserved. These commands use paged JSON within the server-authorized window. Scale can traverse all available archive history; its complete current snapshot download is a separate feature.

Inspect coverage first. Its rows expose accessible_range.from, accessible_range.to and date_basis, alongside full stored metadata; top-level access describes your effective rolling UTC calendar-year window. Omitting date bounds below uses the authorized range. Explicit dates before your plan floor return HTTP403.

financecalendar history-coverage --source-id ons --all
financecalendar archive-observations --metric-id gb-cpi-all-items-yoy --limit 100 --all
financecalendar archive-releases --series-code gb-cpi --limit 100

Each command returns JSON with exact decimal strings, nulls, source/vintage metadata, archive revision and continuation. Observation date bounds apply to the measured reference-period start; release bounds apply to publication dates. One page is returned by default. Continue with --cursor and identical original filters/limit. --all buffers every page before printing: a changed revision, invalid continuation or request failure produces no partial success. The optional --as-of uses FC's durable-evidence receipt bound and does not establish original market availability. Check history-coverage for actual stored depth; these clients do not promise twenty years for every metric.

For a Scale key and a measure with stored coverage extending that far, an explicit long-range request can use --from 2006-01-01. Check accessible_range first; available depth is measure-specific. Scale history uses the same paged JSON retrieval.

Dated source editions and historical survey forecasts

Explore numerical values in named source editions with /history/editions and typed public survey aggregates with /history/forecasts. Start with /history/vintage-coverage to inspect each exact metric’s stored scope and your key’s accessible_range. Starter includes one year, Build ten years, and Scale all available history; omit date bounds to use your plan window. Depth varies by metric/source. Free Developer excludes these routes; existing legacy routes and agreements keep their established access.

Edition from/to filters use publication day; edition access also requires the measured reference-period start inside the plan window. A newly published edition does not grant older measured periods beyond your plan. Forecast filters use issue_period_start, an ordering index; reference_period describes the separate target. Preserve forecast_type, aggregation, target definition, native horizon, exact decimal strings, nulls, units, scale and source credits. Published survey aggregates are distinct from event-matched market consensus and FC blends. Historical survey databases may contain publisher corrections; they are not automatically unchanged original archived issues. Inspect first_print_status, first_print_rule_id, native stage and correction status for source editions.

as_of replays Finance Calendar’s durable receipt versions. available_before is a separate strict source-public-availability cutoff: provide exact UTC seconds ending in Z; unknown, date-only and coarse issue clocks are excluded. A valid query may return no rows. These source cutoffs test the selected FC capture version and do not silently fall back to a different earlier capture. Future/coarse/naive cutoffs are rejected. Follow next_cursor with the same original filters and limit; on 409 restart and discard partial results.

from financecalendar import Client

with Client() as calendar:
    scopes = list(calendar.iter_vintage_coverage(kind="forecasts"))
    metric = next((scope["metric_id"] for scope in scopes
                   if (scope.get("accessible_range") or {}).get("from")), None)
    if metric is None:
        raise ValueError("No survey forecasts in this plan window")
    forecasts = list(calendar.iter_archive_forecasts(metric_id=metric, limit=100))
    editions = list(calendar.iter_archive_editions(
        metric_id="us-gdp-real-qoq-saar", limit=100,
    ))

# Use an export only after iteration finishes successfully.
for forecast in forecasts:
    print(forecast["issue_period"], forecast["reference_period"], forecast["value"])
    print(forecast["source_license"]["attribution"])

One-page methods are archive_editions(), archive_forecasts() and vintage_coverage(); complete iterators are iter_archive_editions(), iter_archive_forecasts() and iter_vintage_coverage(). iter_archive(kind="editions"|"forecasts", ...) is also supported. A later error makes previously yielded rows partial: buffer or commit only after success. API values remain exact strings/nulls; use Decimal explicitly for calculations.

financecalendar vintage-coverage --kind forecasts --all
financecalendar historic-editions --metric-id us-gdp-real-qoq-saar --all
financecalendar historic-forecasts --metric-id eu-spf-hicp-annual-mean-p12m --all

Metadata

Release files for financecalendar 0.1.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for financecalendar 0.1.8
File Size Uploaded Provenance Actions
financecalendar-0.1.8.tar.gz 98.8 kB With provenance Details for financecalendar-0.1.8.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for financecalendar 0.1.8
File Interpreter ABI Platform Actions
financecalendar-0.1.8-py3-none-any.whl Python 3 none any Details for financecalendar-0.1.8-py3-none-any.whl

Total release size: 128.3 kB

Release files / financecalendar-0.1.8.tar.gz

Download URL financecalendar-0.1.8.tar.gz
Size 98.8 kB
Tags Source
SHA-256 checksum
How to use checksums
7ba12bda5d80026cf7ed21f0c9f75c3c4c1383c969665d63ee4a0368c3baab67
BLAKE2b-256 checksum
How to use checksums
ae140884183cdd6db2e3d490a6d1ca6d92da3f8f4ff7db9d00d9a8b4a5f50103
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / financecalendar-0.1.8-py3-none-any.whl

Download URL financecalendar-0.1.8-py3-none-any.whl
Size 29.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
22ef27865329597630853d4873db4d92c92bcd35abc7aebb719100cdc5c296dd
BLAKE2b-256 checksum
How to use checksums
4627c8cd6e62339f88a00af2ce02644027525cf2a1db61ccf6bfc77a3da41688
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Security for financecalendar 0.1.8

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for financecalendar-0.1.8.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.8 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page