API Reference

Complete reference for all ForecastAPI endpoints, parameters, and response formats.

Base URL

https://forecastapi.com/v2

Authentication

Bearer YOUR_API_KEY

Endpoints

Generate Forecast

POST /forecast

Generate forecasts for your time series data with automatic model selection.

Request Body

{
  "identifier": "SKU-12345",
  "data": [
    {"date": "2024-01", "value": 120},
    {"date": "2024-02", "value": 135},
    {"date": "2024-03", "value": 155}
  ],
  "periods": 6,
  "frequency": "M",
  "data_type": "sales",
  "confidence_level": 0.80
}

Parameters

Parameter Type Required Description
identifier string Yes Unique identifier for the data series (e.g., SKU, product ID)
data array Yes Array of time series datapoints with date and value
periods integer Yes Number of forecast periods to generate (1-100 for hourly frequency)
frequency string Yes Data frequency: D, W, M, Q, Y, H
data_type string No Data type for optimized model selection. Default: "sales"
confidence_level float No Confidence level for intervals (0.8-0.99). Default: 0.80
selection_metric string No Back-testing error metric used to pick the best model: auto (default), combined (0.6·MASE + 0.4·sMAPE), mase, or smape. auto uses combined for demand/sales/inventory and sMAPE otherwise.

Data Types

Specialized Types

Support intermittent demand patterns:

  • "sales" - Sales data
  • "demand" - Demand forecasting
  • "inventory" - Inventory levels
Generic Types

Use standard forecasting methods:

  • "web_traffic" - Website analytics
  • "cpu_usage" - System metrics
  • "revenue" - Financial data

Choosing the winning model (selection_metric)

For every request we back-test a set of candidate models on your own history and keep the one that made the smallest error. selection_metric controls which error metric decides the winner. Lower is always better.

Value Picks the model with the lowest…
auto (default) combined for sales/demand/inventory, and sMAPE for every other data type. Preserves the historical default behavior.
combined A blend of 0.6·MASE + 0.4·sMAPE. Balances raw accuracy with trend capture so sparse or intermittent series don't collapse onto a flat line.
mase MASE — error measured against a naive forecast. Scale-free and robust for intermittent demand.
smape sMAPE — symmetric percentage error, bounded 0–200% and safe around zero values.
Caveats
  • Applies to the standard model. The advanced models (advanced-quantized, advanced-patched) honor mase and smape, but combined and auto fall back to their own default metric. On single-model foundation forecasts the value is recorded but does not change the output.
  • Model comparison only runs when there is enough history to back-test (at least 6 data points and periods greater than 1). With less data no comparison happens and the field has no effect.
  • Changing the metric changes which model wins, and therefore the forecast values themselves — not just how they're scored. The winner under smape is often not the winner under combined.
  • MAPE is intentionally not offered — it is undefined at zero and unstable near it, which is why we rank on sMAPE and MASE instead.

Response

{
  "result": {
    "identifier": "SKU-12345",
    "tenant_context": null,
    "forecasts": [
      { "period": 1, "date": "2024-04-01", "forecast": 168.5, "lower": 162.3, "upper": 174.7 },
      { "period": 2, "date": "2024-05-01", "forecast": 175.2, "lower": 168.1, "upper": 182.3 }
    ],
    "model_info": {
      "best_model": "AutoETS",
      "models_evaluated": ["AutoETS", "AutoARIMA", "AutoTheta", "SeasonalNaive"],
      "selection_metric": "smape",
      "interval_source": "conformal",
      "validation_performed": true,
      "smape": { "AutoETS": 6.1, "AutoARIMA": 7.4 },
      "mase": { "AutoETS": 0.82, "AutoARIMA": 0.95 }
    }
  },
  "meta": {
    "selection_metric": "smape",
    "timing": {
      "validation": 8.2,
      "selection": 45.6,
      "forecasting": 72.1,
      "total": 125.9
    }
  }
}

Response Fields

Field Type Description
result object The forecast payload (see fields below)
result.identifier string Echoes the series identifier from your request
result.forecasts array One object per forecast period, each with period, date, forecast (point value), and lower/upper prediction bounds
result.model_info object The selected model (best_model), the models evaluated, the interval source, and per-model back-testing scores (smape/mape/mase) when validation runs
meta.selection_metric string The back-testing metric that chose the winning model
meta.timing object Per-stage timings in milliseconds (validation, selection, forecasting, total)

Model Options

Important Note About Models

ForecastAPI offers multiple models with varying levels of accuracy and computational cost. The advanced variants and the ensemble model provide superior accuracy but consume 25% more API usage than the standard model.

Choose the right forecasting model based on your accuracy requirements and budget. All models use the same automatic algorithm selection, but differ in their underlying implementation and computational complexity.

Available Models

Standard Model

Default

The default forecasting model that balances accuracy and speed. Suitable for most use cases and provides reliable forecasts across a wide range of data patterns.

Performance

Fast processing time, suitable for real-time forecasting

API Usage Cost

1× standard rate

Best for:

  • • General-purpose forecasting
  • • High-volume batch processing
  • • Real-time forecasting needs
  • • Cost-sensitive applications
{
  "data": [...],
  "periods": 6,
  "frequency": "M"
  // model defaults to "standard" if not specified
}

Advanced Models

+25% cost

Enhanced forecasting models built on our most sophisticated algorithms for improved accuracy. Particularly effective for new identifiers, smaller datasets, and complex patterns. Two variants are available:

  • advanced-quantized — our most thorough advanced variant. Evaluates and ensembles multiple candidate models per request for the highest single-model accuracy, at the cost of slower processing.
  • advanced-patched — a patch-based advanced variant with response times comparable to the standard model. Choose this when you want advanced-level accuracy for real-time forecasting.

The advanced value is kept for backwards-compatibility reasons and behaves identically to advanced-quantized.

Performance Notice

The advanced-quantized variant processes slower than the standard model and is not recommended for real-time forecasting with large datasets. Use advanced-patched when response time matters.

Accuracy

Up to 30% improvement across accuracy scores

API Usage Cost

1.25× standard rate

Best for:

  • • New products or identifiers with limited history
  • • Small to medium datasets (5-50 datapoints)
  • • Critical forecasts where accuracy is paramount
  • • Complex or irregular patterns
{
  "data": [...],
  "periods": 6,
  "frequency": "M",
  "model": "advanced-quantized"
}

// or for faster responses:
{
  "data": [...],
  "periods": 6,
  "frequency": "M",
  "model": "advanced-patched"
}

Ensemble Model

Best Accuracy +25% cost

Our most accurate model that combines the standard model and both advanced variants into a single forecast. Uses ensemble techniques to smooth out extreme outliers and deliver superior reliability.

Performance Notice

Slowest processing option. Best suited for batch processing or non-time-sensitive forecasting.

Accuracy

17% improvement over advanced, 50%+ over standard

API Usage Cost

1.25× standard rate

Best for:

  • • Mission-critical forecasts requiring highest accuracy
  • • Data with extreme outliers or volatility
  • • Strategic planning and long-term projections
  • • Batch processing where speed is less critical
{
  "data": [...],
  "periods": 6,
  "frequency": "M",
  "model": "ensemble"
}

API Usage Calculation

The advanced variants (advanced, advanced-quantized, advanced-patched) and the ensemble model consume 25% more API usage than the standard model. Here's how it works:

Example Calculation

10 API calls with standard model: 10 × 1.00 = 10.0 usage
10 API calls with an advanced variant: 10 × 1.25 = 12.5 usage
10 API calls with ensemble model: 10 × 1.25 = 12.5 usage

Applies to All Endpoints

The model parameter and usage multiplier applies to all forecasting endpoints including /forecast, /batch, /traffic-forecasting, and /inventory-planning.

Quick Model Selection Guide

Use Case Recommended Model Reason
High-volume real-time forecasting standard Fast processing, cost-effective
New product launch forecasting advanced Better with limited historical data
Strategic planning & budgeting ensemble Highest accuracy for critical decisions
Overnight batch processing ensemble Time is less critical, accuracy is key
Volatile or erratic data ensemble Smooths out extreme outliers
Cost-sensitive applications standard No additional usage cost

Error Responses

HTTP Status Codes

400
Bad Request
Invalid request parameters or malformed JSON
401
Unauthorized
Invalid or missing API key
429
Too Many Requests
Rate limit exceeded
500
Internal Server Error
Server error during forecast generation

Error Response Format

{
  "error": {
    "code": "invalid_data_format",
    "message": "Data array must contain at least 3 datapoints",
    "details": {
      "received_points": 2,
      "minimum_required": 3
    }
  }
}

Next Steps

Code Examples

See practical examples for different programming languages and use cases.

SDKs & Libraries

Official client libraries for popular programming languages.