Forecasting

Run statistical forecasts on macroeconomic indicators.

The forecasting engine lets you run time-series models on any registered indicator directly through the API. Forecast runs and exports require a signed-in Research or Pro session.

Available models

Model	Family	Best for
ARIMA	Classical	Univariate series with trend and seasonality
ETS	Classical	Exponential smoothing with error/trend/season decomposition
VAR	Multivariate	Joint forecasting of related series
Holt-Winters	Classical	Strong seasonal patterns

Running a forecast

curl -X POST https://macrobymark.com/api/forecast/run \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "us-cpi-all-items",
    "model": "arima",
    "horizon": 12,
    "vintage": { "mode": "latest" }
  }'

The response includes point forecasts, confidence bands, model diagnostics, and a cache key you can use to export results.

Model Expected Values

Calendar and release surfaces may show a Model expected value. This is the platform's one-period-ahead forecast generated from the indicator's own observation history. It is not a survey estimate and it is not a licensed consensus feed.

When available, release payloads include:

Field	Meaning
`forecastValue`	Numeric model expected value.
`expectationSource`	`model` today; `consensus` is reserved for a future licensed feed.
`expectationModelId`	Selected model id such as `ensemble`, `arima`, `ridge`, or `ets`.
`expectationModelLabel`	Human-readable model label.
`expectationObservationCount`	Number of observations used by the model.
`expectationSelectionNote`	Model-selection note from the forecasting engine.

The expectation engine tries ensemble first, then ARIMA, ridge, and ETS when a series has enough observations. If no model can be fit, the field is omitted and the UI says the model expected value is unavailable.

Vintage-aware forecasting

You can run forecasts against historical data vintages to backtest how a model would have performed in real time:

curl -X POST https://macrobymark.com/api/forecast/run \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "us-cpi-all-items",
    "model": "arima",
    "horizon": 6,
    "vintage": { "mode": "specific", "date": "2024-01-15" }
  }'

FRED series support native vintage retrieval. BLS and BEA use simulated vintages derived from revision history. Other providers fall back to the current snapshot with a disclaimer in the audit metadata.

Exporting results

Use the cache key from the forecast response to download results:

# CSV
curl -G "https://macrobymark.com/api/forecast/run/{cacheKey}/csv"

# JSON
curl -G "https://macrobymark.com/api/forecast/run/{cacheKey}/json"