API Reference
Complete reference for all ForecastAPI endpoints, parameters, and response formats.
Base URL
https://forecastapi.com/v1
Authentication
Bearer YOUR_API_KEY
Endpoints
Generate Forecast
/forecast
Generate forecasts for your time series data with automatic model selection.
Request Body
{
"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.95
}Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| data | array | Yes | Array of time series datapoints with date and value |
| periods | integer | Yes | Number of forecast periods to generate (1-24) |
| 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.95 |
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
Response
{
"forecast": [
{
"date": "2024-04",
"value": 168.5,
"lower": 162.3,
"upper": 174.7
},
{
"date": "2024-05",
"value": 175.2,
"lower": 168.1,
"upper": 182.3
}
],
"method": "exponential_smoothing",
"confidence": 0.95,
"analysis": {
"pattern_type": "regular",
"trend": "increasing",
"seasonality": "none_detected",
"characteristics": {
"total_periods": 12,
"non_zero_events": 12,
"mean_value": 142.5,
"coefficient_of_variation": 0.23
}
},
"performance": {
"response_time_ms": 287,
"model_selection_time_ms": 45
}
}Response Fields
| Field | Type | Description |
|---|---|---|
| forecast | array | Array of forecast periods with values and confidence intervals |
| method | string | Forecasting method that was automatically selected |
| confidence | float | Confidence level used for prediction intervals |
| analysis | object | Data pattern analysis and characteristics |
| performance | object | API performance metrics |
Model Options
Important Note About Models
ForecastAPI offers three different models with varying levels of accuracy and computational cost. The advanced and ensemble models 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
DefaultThe default forecasting model that balances accuracy and speed. Suitable for most use cases and provides reliable forecasts across a wide range of data patterns.
Fast processing time, suitable for real-time forecasting
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 Model
+25% costEnhanced forecasting model that combines our most sophisticated algorithms for improved accuracy. Particularly effective for new identifiers, smaller datasets, and complex patterns.
Performance Notice
Slower processing than standard model. Not recommended for real-time forecasting with large datasets.
Up to 30% improvement across accuracy scores
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"
}Ensemble Model
Our most accurate model that combines both standard and advanced models 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.
17% improvement over advanced, 50%+ over standard
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 and ensemble
models consume 25% more API usage than the standard model. Here's how it works:
Example Calculation
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
Error Response Format
{
"error": {
"code": "invalid_data_format",
"message": "Data array must contain at least 3 datapoints",
"details": {
"received_points": 2,
"minimum_required": 3
}
}
}