API Integration Guide

Make real-time forecasts with your deployed time series models using our REST API.

Overview

Once your forecasting model is trained and deployed, you can make real-time predictions using our API endpoint. This allows you to integrate forecasting predictions directly into your applications, websites, or data pipelines.

API Endpoint

POST https://predict.heimdallapp.org/forecast/

Request Headers

• x-api-key - API key that is issued when the endpoint is configured
• x-username - Username associated with your account
• x-forecast-id - Unique identifier associated with the forecasting model

Getting Your Credentials

Follow the steps in our Deployment guide to:

1. Save your model to your Model Inventory
2. Navigate to your model page
3. Generate your API key at the top of the model page
4. Find your Forecast ID in the API Integration tab

Save Your API Key

API Keys are issued one time and cannot be retrieved. If you lose your API key, you'll need to regenerate a new one as API keys cannot be retrieved once generated.

Request Body

• features - Nested dictionary of features. The keys are the names of the columns or features from your data and the values are the new values for those columns.
• horizon - Number of time periods to forecast ahead
• frequency - Time frequency (daily, weekly, monthly)

tip

Below is a high-level structure of the nested features dictionary features : { features : { {name: value}}}

Response Object

The response structure for forecasting models:

Forecast Response

{
  "forecast": [1200, 1350, 1500, 1650, 1800],
  "confidence_intervals": {
    "lower": [1100, 1250, 1400, 1550, 1700],
    "upper": [1300, 1450, 1600, 1750, 1900]
  }
}

tip

• forecast: Array of predicted values for the specified horizon
• confidence_intervals: Lower and upper bounds for prediction uncertainty

Sales Data Example

Let's walk through a sales forecasting dataset and see how each row would look when making API calls:

Date	Sales	Marketing_Spend	Season	Temperature	Target_Sales
2024-01-01	1000	5000	Winter	32	1200
2024-01-02	1200	5500	Winter	35	1400
2024-01-03	1400	6000	Winter	38	1600

API Request for Sales Forecast

{
  "features": {
    "features": {
      "Sales": 1400,
      "Marketing_Spend": 6000,
      "Season": "Winter",
      "Temperature": 38
    }
  },
  "horizon": 5,
  "frequency": "daily"
}

Sample Request

Here's a complete example using sales forecasting data:

import requests

url = 'https://predict.heimdallapp.org/forecast/'
headers = {
    'X-api-key': 'YOUR-API-KEY',
    'X-username': 'YOUR-USERNAME',
    'x-forecast-id': 'YOUR-FORECAST-ID'
}

# Sample features for a sales forecasting model
data = {
    "features": {
        "features": {
            "Sales": 1400,
            "Marketing_Spend": 6000,
            "Season": "Winter",
            "Temperature": 38
        }
    },
    "horizon": 5,
    "frequency": "daily"
}

response = requests.post(url, headers=headers, json=data)

if response.status_code == 200:
    result = response.json()
    forecast = result['forecast']
    print(f"Next 5 days forecast: {forecast}")
else:
    print(f"Error: {response.status_code}")

Understanding the Response

Forecast Values

The forecast array contains predicted values for each time period in your horizon. For example, a 5-day forecast might return [1200, 1350, 1500, 1650, 1800].

Confidence Intervals

Confidence intervals show the uncertainty around your predictions:

• Lower bound: Conservative estimates
• Upper bound: Optimistic estimates
• Range: Indicates prediction confidence

Sales Data Example

In the context of our sales forecasting example, the model has learned patterns from historical sales data. When you send a request with features like:

• Sales (1400): Current sales level
• Marketing_Spend (6000): Marketing investment
• Season ("Winter"): Seasonal indicator
• Temperature (38): External weather factor

The model analyzes these features and predicts future sales based on similar patterns it has seen during training. For example, it might recognize that:

• Higher marketing spend correlates with increased sales
• Winter season affects sales patterns
• Temperature influences consumer behavior

The model essentially finds the best combination of these factors to predict what sales will look like in the coming days.

Error Handling

Common Error Codes

• 400 Bad Request - Invalid request format
• 401 Unauthorized - Invalid API key or username
• 422 Unprocessable Entity - Invalid request body structure
• 500 Internal Server Error - Server-side error

Best Practices

• Always check response status codes
• Implement retry logic for transient errors
• Cache API keys securely
• Monitor API usage and rate limits