Skip to main content

​
Data Format Requirements

​
Time Series Structure

Your time series data must follow this JSON structure: 
{
  "series": [
    {
      "timestamps": ["2023-01-01T00:00:00", "2023-01-02T00:00:00", "2023-01-03T00:00:00"],
      "values": [100, 102, 98]
    }
  ],
  "forecast_horizon": 7,
  "data_frequency": "Daily",
  "forecast_frequency": "Daily",
  "confidence": 0.95
}

​
Timestamp Format

All timestamps must be in ISO 8601 format: YYYY-MM-DDTHH:MM:SSExamples:
  • 2023-01-01T00:00:00 (Daily data)
  • 2023-01-01T10:30:00 (Hourly data)
  • 2023-01-01T10:30:45 (Minute-level data)
Use consistent timezone formatting. We recommend UTC for global applications.
The API supports these data frequencies:
  • Seconds: High-frequency data (e.g., stock prices, sensor readings)
  • Minutes: Sub-hourly data (e.g., website traffic, IoT metrics)
  • Hours: Hourly data (e.g., energy consumption, temperature)
  • Daily: Daily data (e.g., sales, website visits)
  • Weekly: Weekly aggregations (e.g., weekly revenue, user growth)
  • Monthly: Monthly data (e.g., monthly sales, subscription metrics)
  • Quarterly: Quarterly data (e.g., quarterly earnings, seasonal trends)
  • Yearly: Annual data (e.g., yearly revenue, long-term trends)

​
Data Quality Requirements

Minimum Data Points

Daily/Weekly: At least 30 data points
Monthly/Quarterly: At least 12 data points
Yearly: At least 5 data points
Hourly/Minutes/Seconds: At least 100 data points

Data Completeness

No missing values in timestamps or values arrays
Arrays must have equal length
Values must be numeric (integers or floats)
Timestamps must be in chronological order

​
Data Preparation Best Practices

​
1. Data Cleaning

Before sending data to the API, ensure you’ve handled missing values:
# Example: Forward fill missing values
import pandas as pd

df = pd.DataFrame({
    'timestamp': timestamps,
    'value': values
})
df = df.fillna(method='ffill')  # Forward fill
# or
df = df.interpolate()  # Linear interpolation
Consider removing or smoothing extreme outliers that could skew forecasts:
# Example: Remove outliers using IQR method
Q1 = df['value'].quantile(0.25)
Q3 = df['value'].quantile(0.75)
IQR = Q3 - Q1

df_clean = df[
    (df['value'] >= Q1 - 1.5 * IQR) & 
    (df['value'] <= Q3 + 1.5 * IQR)
]

​
2. Seasonality Considerations

Daily Seasonality

For daily data, consider day-of-week patterns. Include at least 4 weeks of data to capture weekly seasonality.

Monthly Seasonality

For monthly data, include at least 2 years of data to capture annual seasonality patterns.

​
3. Data Granularity

Choose the right frequency: Use the highest frequency that makes sense for your use case. Higher frequency data can capture more patterns but requires more data points.

​
Setup Considerations

​
API Configuration

Choose the appropriate model based on your data characteristics:
  • forecast-model-1: General purpose, good for most use cases
  • forecast-model-2: Better for complex seasonal patterns
  • forecast-model-3: Optimized for high-frequency data
  • forecast-model-4: Advanced deep learning for complex patterns
Set your forecast horizon based on your business needs:
  • Short-term: 1-7 periods for immediate planning
  • Medium-term: 8-30 periods for operational planning
  • Long-term: 30+ periods for strategic planning
Longer forecast horizons generally have higher uncertainty. Consider using confidence intervals for planning.

​
Common Data Patterns

​
Example: E-commerce Sales Data

{
  "series": [
    {
      "timestamps": [
        "2023-01-01T00:00:00", "2023-01-02T00:00:00", "2023-01-03T00:00:00",
        "2023-01-04T00:00:00", "2023-01-05T00:00:00", "2023-01-06T00:00:00",
        "2023-01-07T00:00:00", "2023-01-08T00:00:00", "2023-01-09T00:00:00",
        "2023-01-10T00:00:00"
      ],
      "values": [1200, 1350, 1100, 1400, 1600, 1800, 2200, 1500, 1300, 1400]
    }
  ],
  "forecast_horizon": 14,
  "data_frequency": "Daily",
  "forecast_frequency": "Daily",
  "confidence": 0.95
}

​
Example: Website Traffic (Hourly)

{
  "series": [
    {
      "timestamps": [
        "2023-01-01T00:00:00", "2023-01-01T01:00:00", "2023-01-01T02:00:00",
        "2023-01-01T03:00:00", "2023-01-01T04:00:00", "2023-01-01T05:00:00"
      ],
      "values": [150, 120, 80, 60, 50, 70]
    }
  ],
  "forecast_horizon": 24,
  "data_frequency": "Hours",
  "forecast_frequency": "Hours",
  "confidence": 0.90
}

​
Troubleshooting

“Invalid timestamp format”: Ensure timestamps are in ISO 8601 format
“Arrays must have equal length”: Check that timestamps and values arrays have the same number of elements
“Insufficient data points”: Add more historical data points
“Invalid frequency”: Use one of the supported frequency values
  • Use consistent time intervals when possible
  • Pre-process data to remove noise and outliers
  • Consider data seasonality when choosing forecast horizon
  • Test with smaller datasets before processing large volumes

​
Next Steps

Make Your First Request

Follow the quickstart guide to make your first forecast request with properly formatted data.

API Reference

Explore the complete API reference for detailed parameter documentation.