Predictions API contract
Market consensus is not the same field as an FXMacroData forecast
Use prediction_type to identify what a forecast represents. A row with prediction_type="fxmacrodata" is an FXMacroData-generated estimate. It is not a market-consensus figure. A true compiled market or economist consensus is labelled market_consensus.
Market consensus
market_consensus
Compiled market or economist event-consensus feed, where available.
FXMacroData estimate
fxmacrodata
An FXMacroData-generated prediction. Do not label it as market consensus.
Availability
Not guaranteed for every release
A supported announcement series can exist without a consensus or any prediction row.
Request the exact forecast type you need
Filter the dedicated endpoint instead of treating an unfiltered first result as consensus. An empty data array means no matching prediction is available in the requested date window and series selection.
GET https://api.fxmacrodata.com/v1/predictions/usd/inflation
?prediction_type=market_consensus
&pre_release_only=true
&api_key=YOUR_API_KEYUse prediction_source for a specific provider or publication. Use prediction_source_label for display. The source slug and label describe the forecast source; they do not guarantee a source URL.
Prediction type reference
| prediction_type | Meaning | Safe customer label |
|---|---|---|
| market_consensus | Compiled market or economist event consensus | Market consensus |
| market_prediction | Point prediction from professional forecasters | Professional forecast |
| model_nowcast | Central-bank or reserve-bank model nowcast | Model nowcast |
| survey | Survey of professional forecasters | Forecaster survey |
| central_bank_forecast | Forecast published by a central bank | Central-bank forecast |
| central_bank_projection | Official central-bank projection | Central-bank projection |
| imf_weo | IMF World Economic Outlook projection | IMF WEO projection |
| fxmacrodata | FXMacroData-generated estimate | FXMacroData forecast |
Join forecast to actual
Each prediction group includes announcement_id. Match it to the same field from /v1/announcements/{currency}/{indicator}. The realised value is data[].val. Request revisions=all when you need revision history; do not infer revisions from a later overwrite.
GET https://api.fxmacrodata.com/v1/announcements/usd/inflation
?revisions=all
&api_key=YOUR_API_KEYUnderstand official source links
source_url is optional. When present on an announcement, source_url_scope tells you whether it points to the exact release, the broader dataset, or the underlying series. Do not promise an exact BLS, BEA, or other official release permalink for every event.
For a customer-facing citation, show the link only when it is present and label its scope honestly. The forecast source fields are separate from the announcement's official source fields.
Run the coverage preflightProduction preflight
- 1. Query each required currency and indicator pair.
- 2. Filter
prediction_type=market_consensusif consensus is mandatory. - 3. Check several upcoming and recent releases, not one sample row.
- 4. Verify
source_urlandsource_url_scopeseparately. - 5. Confirm revision and history needs on the announcements endpoint.
- 6. Design a clear unavailable state for missing optional fields.