Long Table, Frequency & Time Zones

This page covers how to write the series long table, which timestamp formats the default cleaning path accepts, the freq frequency strings, and how time zones are converted, with a data format quick reference at the end. The raw preset is stricter, see the raw preset.

1. Long-table records

series is a flat array with one observation per row:

[
{"unique_id": "grid_01", "ds": "2026-09-01T00:00:00Z", "y": 120.5},
{"unique_id": "grid_01", "ds": "2026-09-01T01:00:00Z", "y": null},
{"unique_id": "grid_02", "ds": "2026-09-01T00:00:00Z", "y": 88.0}
]

• Rows may come in any order and need not be grouped by entity; default cleaning sorts them by time and records it in the report.
• Other numeric fields on a row are past covariates; they are aligned and reported per column; no model uses them today, see Covariate Support.
• Forecasts are returned per entity, with every timestamp in UTC ending in Z.

2. Timestamp formats

Under the default and strict presets, ds may use any of the formats below. Keep one format per entity; non-ISO formats are recorded as a timestamp_format issue in the cleaning report.

D/M/YYYY and M/D/YYYY are accepted only when the data proves the day/month order (for example a 13/09/2026 row). Otherwise the request returns AMBIGUOUS_DATE_FORMAT; pass options.ds_format (dmy or mdy) or switch to ISO 8601.

3. Frequency strings

freq is optional. When omitted, the service infers it and reports the result and its confidence in the cleaning report's series[].freq. Inference failure returns FREQ_INFERENCE_FAILED; entities that infer different frequencies, or several candidates, return FREQ_AMBIGUOUS. For irregular data, always pass it.

• Every form except B takes an integer multiple prefix, for example 15min, 2h, 3MS, 3M@15.
• Case matters: M is month end, m is minutes.
• The freq field echoes your string verbatim; when omitted, it echoes the inferred canonical form, such as min, h, d, w, MS, QE, M@15, or 15min with a multiple.
• Calendar frequencies (month, quarter, year) step on the local wall clock (time zones below) and handle month lengths, leap years and daylight saving time.
• The raw preset accepts fixed-step frequencies only (seconds, minutes, hours, days, weeks); calendar frequencies return RAW_INPUT_INVALID.

4. Time zones

• Stamps with an offset (Z or ±HH:MM) are parsed with their own offset; options.timezone does not override it.
• Stamps without an offset are parsed in options.timezone (an IANA name such as Asia/Shanghai); without it they are read as UTC and the report records a naive_timestamps_assumed_utc issue (info level).
• An invalid zone name returns VALIDATION_ERROR.
• Output: timestamps in model_input and forecast are always UTC; convert back to local time on the client if needed.

The cleaning report's series[].timezone records the zone each entity actually used:

The example below treats monthly Beijing-time data as month-start. Each month starts at local 00:00, which is 16:00 UTC on the previous day:

// Request
{"series": [{"unique_id": "sales", "ds": "2025-01-01", "y": 101}, ...],
"h": 2, "freq": "MS", "options": {"timezone": "Asia/Shanghai"}}

// model_input[0].ds is "2024-12-31T16:00:00Z"
// the two forecast stamps are "2026-08-31T16:00:00Z" and "2026-09-30T16:00:00Z"
// cleaning_report.series[0].timezone
{"used": "Asia/Shanghai", "source": "option", "naive_rows": 20,
"explicit_rows": 0, "explicit_offsets": []}

5. Data format quick reference

The /v1/forecast request fields that shape your data at a glance. For every field, its default and the validation order, see POST /v1/forecast.