Skip to main content
The economic calendar lists what is due when — CPI, payrolls, GDP, PMIs, rate decisions — with the previous figure, the consensus estimate and the actual once published. Beside those rows it carries the release schedules the statistics offices and central banks publish themselves, which reach years further out, and the days each Asian market is closed. A second view keeps the daily history of the consensus, so “what did the market expect a week before the print” is answered from the row captured that day.
Plan: Free and above · Credits: 1 per call · MCP tool: get_economic_calendar

​
What you can use the calendar for

Know what prints this week and which of it matters. Compare an actual with the consensus that stood the day before, not the one that stood a month out. Line up a company’s earnings date against the macro releases around it.

​
GET /v1/macro/calendar

Oldest first. The default window is today to 30 days ahead; pass date_gte and date_lte to look elsewhere, back to 2013.
​
string
default:"schedule"
schedule returns the calendar as it stands. snapshots returns the point-in-time history: one row per event per day it was captured.
​
string
Only one kind of row: release (a data release or central-bank decision), election (a national election or referendum) or holiday (a market or public holiday). Schedule view only — with view=snapshots it returns 400, because only releases have a consensus history.
​
string
Two-letter ISO code. EU is the euro area, GB the United Kingdom, WL world events.
​
string
A fragment of the event name, matched ignoring spaces and punctuation: CPI, Nonfarm, Interest Rate Decision.
​
string
Earliest scheduled_date, YYYY-MM-DD; defaults to today. date_lte sets the ceiling and defaults to today plus 30 days.
​
integer
default:"100"
Rows per page, between 1 and 500. Page through with cursor.

​
Two kinds of rows, and one of them has no consensus

official_schedule says which kind a row is, and the two answer different questions. So a date more than four months out will have no estimate, and that is not a gap in the consensus — it is a row that exists precisely because the publisher said the date before any forecaster wrote a number.

​
status is the publisher’s own word

Official-schedule release rows may carry status: provisional (the date is announced but not fixed), confirmed, or postponed (announced, then moved). Rows without it are simply dated. The United Kingdom marks the most rows this way, and a provisional date months out does move — treat it as the plan it is.

​
Market holidays are rows too

The days the Japanese, Taiwanese, Korean, Hong Kong and mainland Chinese markets are closed appear as calendar events (Market holiday / Public holiday), through 2027 for most of them, with event_type: "holiday". They are the reason a daily series has no observation on a date, and the reason a filing deadline slips — worth reading before concluding a series stopped updating.

​
Elections are rows too

National elections and referendums appear with event_type: "election", about 18 months ahead, one row per country and voting day (Election: General, Election: Presidential (second round)). Pass type=election to get only those. An election row’s status says how firm the date is: US state elections — primaries, runoffs and special elections, each state on its own day — are separate rows with subdivision set to the ISO 3166-2 code (US-GA); the national row has no subdivision. Election dates before October 2026 come from the market calendar and are often incomplete.

​
One release is several rows

A CPI day carries the index, the year-on-year rate and the month-on-month rate as separate events, each with its own previous, estimate and actual in its own unit. They are not duplicates and must not be averaged.

​
A far-out estimate is a placeholder

estimate is meaningful only close to the release. Weeks out it is a placeholder — a round number, or the previous value carried forward. Do not report a far-dated estimate as consensus.

​
The snapshot history starts 2026-09-09

view=snapshots carries one row per event per snapshot_date, captured every day since 2026-09-09 for events from 21 days back to 30 days ahead. Nothing earlier exists and nothing earlier can be reconstructed: “what was consensus a week before the August 2026 CPI” is unanswerable, and stays so.

​
Key calendar fields

Schedule rows carry country, country_name, event, scheduled_date, scheduled_at (UTC, when the source gives a time), period_hint, unit, impact, previous, estimate, actual, official_meeting, which is true for FOMC and ECB Governing Council decisions taken from the central bank’s own schedule, plus official_schedule and status described above, event_type (release, election or holiday) and subdivision (an ISO 3166-2 code on US state election rows, otherwise null). Snapshot rows carry country, event, scheduled_date, snapshot_date, estimate, previous and actual. The response’s coverage block states schedule_from, schedule_to_days_ahead, official_schedule_to_days_ahead, official_schedule_from, snapshots_from and the snapshot window — two horizons because one number would be a lie about half the rows. Publishers are named on the attribution list; rows themselves carry no source column.

​
Taiwan and Hong Kong used to be nearly empty

They are not any more: both now carry the official release schedules from the Directorate-General of Budget, Accounting and Statistics and the Census and Statistics Department respectively, running through 2026 and 2027. Those rows are official_schedule: true, so they carry dates and no consensus. Taiwan’s statistics themselves are in Series. See Series for the values a release updates, Analyst consensus for company-level estimates, Earnings consensus for prediction-market EPS bars, and Prediction markets for traded odds on macro outcomes.