The Forecasting API is now v1. API v0 is deprecated and stops working on 20 December 2026. Move to v1
The Forecasting Company Logo
Cookbook

Get the forecast as parquet

Every request on these pages comes back as JSON. That's the default; the Accept header picks another format. Parquet is the one to reach for when the forecast goes straight into a dataframe, a warehouse or a lake: the same table, typed and compressed, with nothing to parse.

This request forecasts a week of sales per city from the sample data:

JSONCode
{ "input": { "source": { "uri": "https://tfc-docs-examples-eu-central-1.s3.eu-central-1.amazonaws.com/retail/v1/sales.parquet" }, "columns": { "date": { "kind": "time", "frequency": "1d" }, "store": "identifier", "city": "identifier", "sales": { "kind": "target", "aggregate": "sum" } }, "hierarchies": { "store": [["store", "city"]] } }, "selector": { "city": "any" }, "prediction_length": "1w", "quantiles": [0.1, 0.5, 0.9] }

Ask for parquet with the Accept header:

TerminalCode
curl -X POST "https://api.retrocast.com/v1/forecast?model=t0-gamma" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: application/vnd.apache.parquet" \ -d @request.json \ -o forecast.parquet

The button above sends the same header, and the playground shows the file as a table.

The formats

AcceptWhat comes back
application/json (default)One object, data, holding the table as one array per column.
application/vnd.apache.parquetThe same table as a parquet file, one row per (series, time step).
application/x-ndjsonOne JSON record per series, one per line.
application/vnd.msgpackThe same records as NDJSON, in MessagePack.
application/x-tarA tar archive of the parquet forecast and the input the model read.

Anything else is rejected with 406 Not Acceptable, naming the formats above.

Parquet

One row per city and day, so 14 rows here. The columns are the ones the JSON response carries in data: time and cutoff as UTC timestamps, lead_time and span as ISO 8601 durations, then identifiers and targets as nested structs, and auxiliary, empty for these requests. The first two rows, with the quantiles rounded here:

timecutofflead_timespanidentifierstargets
2024-12-302024-12-29PT0SP1D{"city":"Lyon"}{"sales":{"quantiles":{"0.1":51.63,"0.5":63.59,"0.9":74.74}}}
2024-12-312024-12-29P1DP1D{"city":"Lyon"}{"sales":{"quantiles":{"0.1":44.91,"0.5":56.02,"0.9":67.04}}}

Read it with any parquet reader — pandas.read_parquet, polars.read_parquet, DuckDB's read_parquet — and flatten the structs there if you want one column per quantile.

NDJSON and MessagePack

One record per series instead of one row per step: each target's quantiles are arrays, one value per step. Trimmed to the first step:

JSONCode
{ "identifiers": { "city": "Lyon" }, "cutoff": "2024-12-29T00:00:00Z", "origin": "2024-01-01T00:00:00Z", "first_step": 364, "lead_time": "PT0S", "frequency": "P1D", "span": "P1D", "targets": { "sales": { "quantiles": { "0.1": [51.62795], "0.5": [63.592873], "0.9": [74.73698] } } } }

Times are written as steps from origin: the first forecast step is origin plus first_step steps of frequency — here 2024-01-01 plus 364 days, 30 December.

The last line is not a series. It reports what the request used:

JSONCode
{ "usage": { "forecast_units": 2, "timestamp": 1795013473, "formula": "target-cutoff-v1" } }

The forecast and its input

application/x-tar returns two parquet files:

  • forecast.parquet — the same file the parquet format returns.
  • materialization.parquet — the input rows as the model read them, after selection and roll-ups. Here that's one row per city and day — 728 rows — with each city's stores already summed:
citydatesales
Lyon2024-01-0146
Lyon2024-01-0251

That's the series the model forecast from, so it's what to plot the forecast against, or what to check when a number looks off.

Last modified on