# Time Series Forecaster
Forecast a time series with exponential smoothing, Holt trend, damped trend, or Holt-Winters seasonality, including prediction intervals and accuracy metrics.
## Run it
- **CLI:** `gizza tool time-series-forecaster "month,sales
Jan,120
Feb,132
Mar,141
Apr,158"`
- **Web:** https://gizza.ai/tools/time-series-forecaster/
- **Agents:** machine-readable descriptor (parameters JSON Schema) at https://gizza.ai/tools/time-series-forecaster/tool.json
## Inputs
- `data` — Historical values (oldest first) _(field)_
- `model` — Model _(field)_
- `horizon` — Periods to forecast _(field)_
- `season_length` — Season length (0 = non-seasonal) _(field)_
- `alpha` — Alpha — level weight (0 = fit automatically) _(field)_
- `beta` — Beta — trend weight (0 = fit automatically) _(field)_
- `gamma` — Gamma — seasonal weight (0 = fit automatically) _(field)_
- `phi` — Phi — trend damping (0 = fit automatically) _(field)_
- `confidence` — Prediction interval _(field)_
- `show_fitted` — Show fitted values and residuals _(field)_
- `header` — Header row _(field)_
- `decimals` — Decimal places _(field)_
- `format` — Output _(field)_
## Output
- Forecast (text)
## Query parameters
Open the tool pre-filled and auto-run via URL:
- `data` — Historical values (oldest first)
- `model` — Model
- `horizon` — Periods to forecast
- `season_length` — Season length (0 = non-seasonal)
- `alpha` — Alpha — level weight (0 = fit automatically)
- `beta` — Beta — trend weight (0 = fit automatically)
- `gamma` — Gamma — seasonal weight (0 = fit automatically)
- `phi` — Phi — trend damping (0 = fit automatically)
- `confidence` — Prediction interval
- `show_fitted` — Show fitted values and residuals
- `header` — Header row
- `decimals` — Decimal places
- `format` — Output
Example: `https://gizza.ai/tools/time-series-forecaster/?data=month%2Csales%0AJan%2C120%0AFeb%2C132%0AMar%2C141%0AApr%2C158&model=auto&horizon=6&season_length=0&alpha=0&beta=0&gamma=0&phi=0&confidence=95&show_fitted=true&header=auto&decimals=3&format=text`
---
## About this tool
Forecast a single numeric series without leaving the browser. Paste one value per row, a labelled
CSV-style row such as `Jan,120`, or a single comma-separated series, then choose an exponential
smoothing model: simple level smoothing, Holt's linear trend, a damped trend, or Holt-Winters
seasonality. If you leave **Model** on auto, the tool fits every applicable candidate and picks the
lowest-AICc result.
The output reports the selected model, fitted smoothing weights, in-sample accuracy metrics, and a
future forecast table with lower and upper prediction bands. Optional fitted values make it easier
to see where the model tracked the history well and where residuals were large. Everything is
computed locally with deterministic WebAssembly, so the page, CLI, and chat tool use the same core
logic.
### Worked example
Paste this monthly sales series:
```text
month,sales
Jan,120
Feb,132
Mar,141
Apr,158
May,166
Jun,181
Jul,190
Aug,203
```
Set **Model** to `holt`, **Periods to forecast** to `3`, **Prediction interval** to `95%`, and
**Decimal places** to `2`. The forecast continues the fitted trend and returns a table like:
```text
period forecast lower upper
9 ... ... ...
10 ... ... ...
11 ... ... ...
```
Use **Holt-Winters additive** with a season length such as `12` for monthly data with a yearly cycle,
or `4` for quarterly data. Multiplicative seasonality is useful when seasonal swings grow with the
level, but it requires strictly positive observations.
### Limits and edge cases
- Input needs at least **3 observations** and accepts at most **10,000 observations**.
- Forecast horizon accepts **1–240 periods**; the page slider focuses on the common 1–60 range.
- Seasonal models need `season_length >= 2` and at least **two full cycles** of history.
- Smoothing weights (`alpha`, `beta`, `gamma`, `phi`) left at `0` are fitted automatically; set a
positive value to pin that weight.
- Multiplicative Holt-Winters rejects zero or negative observations because seasonal ratios would be
undefined.
- Prediction intervals are approximate ETS residual bands, not a guarantee. Damped and
multiplicative seasonal intervals are especially approximate at long horizons.
- `MAPE` is omitted when actual values are zero; `MASE` needs enough naive seasonal differences to
establish a scale.
- This is a univariate forecaster. It does not model promotions, regressors, holidays, multiple
series, missing timestamps, or machine-learning features.
## FAQ
Which model should I choose?
Use **auto** when you want a quick baseline: it tries the applicable exponential-smoothing models
and chooses by AICc. Use **simple** for a mostly flat series, **Holt** for a clear trend,
**damped** when the trend should flatten over time, and **Holt-Winters** when the same seasonal
pattern repeats every `season_length` observations.
What does season length mean?
Season length is the number of observations in one repeat cycle. Monthly data with yearly seasonality
uses `12`, quarterly data uses `4`, weekly data with daily observations uses `7`, and non-seasonal
data uses `0`. Seasonal models need at least two complete cycles so the starting seasonal indices can
be estimated.
Do I need to set alpha, beta, gamma, or phi?
Usually no. Leave them at `0` and the tool fits deterministic values by minimising one-step-ahead
squared errors. Set a positive value only when you need to reproduce a known model or compare a
specific smoothing weight against the automatic fit.
Can I paste labelled rows or currency values?
Yes. Rows like `Jan, $120`, percent-marked values, underscores, and accounting negatives such as
`(12.5)` are normalised before fitting. The last field in each row is treated as the numeric value;
earlier fields become labels for the optional fitted table.
Are the prediction intervals statistical confidence guarantees?
No. They are practical residual-based forecast bands for the selected ETS model. They are useful for
rough planning and anomaly checks, but they do not replace a full statistical modelling workflow,
especially for intermittent demand, structural breaks, or long seasonal horizons.
## Related tools
- [Age Calculator](https://gizza.ai/tools/age-calculator/): Calculate your exact age from your date of birth — years, months and days, next birthday countdown and total days lived. Free, private, in-browser.
- [Current UTC Time](https://gizza.ai/tools/clock/): See the current UTC date and time, updating live in your browser. No sign-up, runs offline.
- [Cron Next Run Times](https://gizza.ai/tools/cron-next-runs/): Cron expression parser and next-run calculator — see upcoming run times in UTC with plain-English schedules, free and entirely in your browser.
- [Date Difference Calculator](https://gizza.ai/tools/date-diff/): Calculate the exact duration between two dates: years, months, days, hours, minutes and seconds, with leap years handled. Free, private, in-browser.
- [Deadline Countdown](https://gizza.ai/tools/deadline-countdown/): Compute time remaining or overdue for dated tasks, label urgency, and sort the list by deadline in table, Markdown, JSON, or CSV format.