Four numbers, one release, four different meanings
Ask four sources what US core PCE will print next month, and you can get four different numbers. One is a survey of professional forecasters. One is a statistical model updated daily as new inputs arrive. One is the Federal Reserve's own projection, made once a quarter on an annual horizon. One is an estimate we generated ourselves.
They are all forecasts. They are not interchangeable, and treating them as one thing is the single most common mistake we see in evaluation. A model nowcast and a forecaster survey have different accuracy, different revision behaviour, different horizons, and different meanings when a print surprises them. If you are building a surprise index, only one of them belongs in the denominator.
Every forecast row the FXMacroData predictions API returns carries a prediction_class field that says which kind of number you are holding. This article explains the seven classes, which two of them are genuinely a consensus, and how to check what exists for a release before you build on it.
The two classes that represent a consensus
A consensus means a group of forecasters, aggregated. Two classes qualify.
compiled_consensus
A publisher collects forecasts from many independent forecasters and publishes the compilation. This is the closest thing in our catalogue to the consensus figure printed on an economic calendar.
- HM Treasury publishes Forecasts for the UK Economy, a monthly comparison of independent forecasts.
- Banco Central do Brasil publishes the Focus Market Readout, aggregating forecasts submitted by around 130 institutions.
- The Reserve Bank of Australia publishes market economists' forecasts in Table J1 of its Statement on Monetary Policy.
forecaster_survey
An official institution surveys professional forecasters or market participants directly and publishes the aggregate. This is a real consensus of opinion, with one important caveat: the survey runs on its own horizon and cadence, which is usually quarterly or annual, not one reading per release.
- ECB Survey of Professional Forecasters and the Philadelphia Fed Survey of Professional Forecasters — the same instrument, run on different continents.
- New York Fed Survey of Market Expectations, a survey of primary dealers and market participants ahead of FOMC meetings.
- RBNZ Survey of Expectations, the Norges Bank Expectations Survey, the BCRP Macroeconomic Expectations Survey and the Bank of Canada Market Participants Survey.
The caveat matters more than it looks. The NY Fed SME asks about the level of PCE inflation in December of a given year. That is a genuine consensus, and it is not an answer to the question "what will next Thursday's print be?".
The five classes that are not a consensus
market_implied
Derived from traded instrument prices, usually options or futures. The Atlanta Fed Market Probability Tracker turns options on interest-rate futures into probabilities for FOMC outcomes. No person forecast anything: this is what the market is priced for. That makes it valuable and makes it a different object from a survey. It moves continuously, it embeds a risk premium, and it can disagree with the survey consensus for long stretches.
model_nowcast
A published statistical model's estimate of the current period, updated as inputs arrive. The Cleveland Fed inflation nowcast produces a daily estimate of CPI and PCE inflation; Atlanta Fed GDPNow does the same for GDP. These are the deepest and most regular pre-release series we carry for US inflation, and they are frequently mistaken for consensus because they are the only number available for many releases.
A nowcast is a model output. It has no opinion, it revises whenever its inputs revise, and its errors are correlated across releases in ways a survey median's are not.
central_bank_projection
The central bank's own published projection: the FOMC Summary of Economic Projections, ECB and Eurosystem staff macroeconomic projections, the Bank of Canada Monetary Policy Report, the RBNZ Monetary Policy Statement. One institution, published on a fixed schedule, usually on an annual or multi-year horizon.
This is the forecast that moves markets when it changes, because it tells you about the reaction function rather than about the data. It is not what the market expects; it is what the policymaker expects.
institutional_projection
A projection from an institution that is not the currency's central bank, such as the IMF World Economic Outlook or the OECD Economic Outlook. Typically annual, revised a few times per year. Useful for long-horizon context and almost never useful for an event-driven strategy.
fxmacrodata
An estimate we generate, combining central-bank guidance, survey consensus, historical trends and recent prints. We produce one for every confirmed release on the calendar, which makes it the only forecast available for many series.
It is our number. Do not label it a market consensus, do not put it on a chart with "consensus" on the axis, and do not use it as the expectation term in a published surprise index without saying what it is.
Availability is set by the publisher, not by your plan
This is the part that surprises people during evaluation, so it is worth stating plainly.
Every paid plan returns the same forecast sources. A paid key widens the date window you can query. It does not add forecast sources. There is no plan, tier or add-on that unlocks a consensus for a release where no publisher produces one.
And no publisher produces one for a lot of releases. Specifically, for the US headline releases most people ask about first:
- CPI and Core CPI — no consensus of any class. What exists is the Cleveland Fed nowcast, on every monthly release, back to August 2013.
- PCE and Core PCE — the Cleveland Fed nowcast back to July 2013, plus NY Fed SME values for a handful of annual December targets. There is no per-release consensus.
- Nonfarm Payrolls and Average Hourly Earnings — no external forecast publisher at all. The FXMacroData blended forecast only.
- Unemployment Rate — the FOMC SEP projection path, annual December targets, from 2015.
- The FOMC target range — this one does have a usable consensus run: NY Fed SME on most meetings since July 2023.
The reason is not a licensing gap on our side. The sell-side survey median printed on retail economic calendars is a commercial product compiled by data vendors from bank research desks. It is not published by any official source, and we do not redistribute it. Everything in our catalogue traces to an official publisher.
Check before you build
Filter on prediction_class and read the availability block that comes back. Every response carries it, including responses with no rows.
GET /v1/predictions/gbp/inflation
?prediction_class=compiled_consensus
&pre_release_only=true
X-API-Key: YOUR_API_KEYWhen a filter matches nothing, the response still returns HTTP 200 and tells you why:
"availability": {
"classes_with_sources": ["model_nowcast", "institutional_projection", "fxmacrodata"],
"returned_classes": [],
"reason": { "compiled_consensus": "no_source_for_pair" }
}Three reason codes, and they mean different things:
no_source_for_pair— no publisher produces this class for this currency and indicator. A property of the data. No subscription adds it, so stop looking and design around what exists.outside_requested_window— a source does cover this pair, but published nothing inside your dates. Widen the range.outside_freemium_window— a source covers this pair, but the matching rows need a key.
Always pass pre_release_only=true when you are measuring forecast accuracy. It restricts results to forecasts whose generated_at is strictly before the announcement, which is what keeps lookahead out of a backtest.
A note on the older prediction_type field
Every response still carries prediction_type, and it still works as a filter, so nothing built against it breaks.
It is the original field, and it grew one value at a time as each source was added, which left seams. The ECB and Philadelphia Fed Surveys of Professional Forecasters are the same instrument and landed in two different values, market_consensus and survey. The value market_prediction holds an options-implied series rather than a forecaster's prediction. The values imf_weo and oecd_eo name a publisher rather than a category.
prediction_class is derived from the source rather than from whichever value a fetcher recorded, which is why it is consistent across currencies. Build on it. Here is how the old values map:
Legacy prediction_type | Reported as prediction_class |
|---|---|
market_consensus | compiled_consensus or forecaster_survey, by source |
survey | forecaster_survey |
market_prediction | market_implied |
model_nowcast | model_nowcast |
central_bank_forecast | central_bank_projection |
central_bank_projection | central_bank_projection |
imf_weo, oecd_eo | institutional_projection |
fxmacrodata | fxmacrodata |
The short version
Before you treat a forecast as a consensus, check two things. Is its prediction_class one of compiled_consensus or forecaster_survey? And is its horizon the release you care about, rather than a December target eleven months out?
If the answer to either is no, you are holding something else. It may still be the best available number for that release, and for US CPI it probably is. Just do not call it the consensus.
The predictions API documentation carries the full class reference and a per-pair coverage matrix showing which sources cover which currency and indicator, with verified pre-release history depth.
