Forecasting Engine

Beta Feature

The forecasting engine is currently in Beta status. Use forecasts as rough estimates for planning purposes rather than guarantees. The engine provides directionally accurate inventory predictions but has known limitations.

The ad server includes a forecasting engine that predicts how many ad impressions will be available for a potential campaign, helping advertisers plan budgets and publishers optimize inventory allocation. The system identifies conflicts between line items competing for the same traffic.

Key Features

• Historical pattern analysis: Queries 30 days of ClickHouse analytics data matching targeting criteria
• Conflict detection: Identifies competing line items with overlapping targeting and schedules
• Basic eCPM filtering: Filters out same-priority conflicts when bid differences exceed 10%
• Priority-based impact: Reduces available inventory based on higher-priority campaign competition
• Multi-budget type support: Handles CPM and CPC campaigns with eCPM normalization
• Publisher-wide fallback: Provides rough estimates when no exact historical match exists

API Endpoint

POST /forecast

Request a forecast for a potential line item configuration.

Request Parameters

Field	Type	Required	Description
start_date	string	Yes	Campaign flight start date and time (ISO 8601 format)
end_date	string	Yes	Campaign flight end date and time (ISO 8601 format)
budget_type	string	Yes	Pricing model: cpm (cost per 1000 impressions), cpc (cost per click), or flat (fixed price)
budget	float	Yes	Total budget amount in dollars
publisher_id	int	Yes	Target publisher ID
cpm	float	If CPM	Cost per thousand impressions (used for eCPM comparison)
cpc	float	If CPC	Cost per click (converted to eCPM using estimated CTR)
priority	int	No	Priority level (1=high, 2=medium, 3=low)
countries	array	No	ISO country codes for geographic targeting (e.g., ["US", "CA"])
device_types	array	No	Device types: mobile, desktop, tablet
key_values	object	No	Custom targeting key-value pairs
daily_cap	int	No	Maximum impressions per day (prevents over-delivery)
pacing	string	No	Delivery pacing strategy: ASAP (deliver as fast as possible) or Even (spread evenly across campaign flight)

Example Request

{
  "start_date": "2024-06-01T00:00:00Z",  // Replace with your campaign start date
  "end_date": "2024-06-08T00:00:00Z",    // Replace with your campaign end date (7 days later)
  "budget_type": "cpm",
  "budget": 1000.0,
  "cpm": 5.0,
  "publisher_id": 1  // Example publisher ID - replace with your publisher ID
}

Response Fields

Field	Type	Description
Summary Metrics
total_opportunities	int	Total ad requests matching targeting
available_impressions	int	Unfilled inventory available
estimated_impressions	int	Projected impressions for this line item
estimated_clicks	int	Projected clicks (CPM/CPC campaigns)
estimated_spend	float	Projected spend
fill_rate	float	Current fill rate for matching traffic
estimated_ctr	float	Expected click-through rate
Arrays
daily_forecast	array	Daily projections with date and metrics
conflicts	array	Competing line items with overlap info
warnings	array	Advisory messages about data quality

Conflict Object Fields

Field	Type	Description
line_item_id	int	Competing line item ID
line_item_name	string	Line item name
priority	int	Priority level
overlap_percentage	float	Targeting overlap (0.0 to 1.0)
estimated_impact_impressions	int	Delivery impact
conflict_type	string	higher_priority, same_priority, or lower_priority

Data Requirements

ClickHouse Schema

The forecasting engine requires the enhanced events table with key-values:

ALTER TABLE events ADD COLUMN key_values Map(String, String);

Historical Data

• Minimum 7 days of ad request data recommended
• Key-values are captured only from ad_request events
• Impressions and clicks are joined via request_id

Implementation Details

Query Strategy

1. Query 30 days of ad_request events with targeting filters
2. Join with impression events to calculate fill rates
3. Analyze existing line items for targeting overlap
4. Apply pacing and budget constraints for projections

Queries use 15-minute time buckets and are limited to 10,000 patterns for performance.

Limitations

The forecasting engine provides useful planning estimates but has several known limitations:

• No rate limiting simulation: Does not account for line item rate limits
• No frequency cap simulation: Cannot predict frequency cap impact on delivery
• Static CTR baseline: Uses 1% CTR for all CPC eCPM calculations instead of actual predictions
• No budget exhaustion timing: Cannot predict when higher-priority campaigns will run out of budget
• Estimated overlap percentages: Uses approximate targeting overlap instead of actual traffic analysis
• Single publisher only: Cannot forecast across multiple publishers
• No seasonality modeling: Does not account for traffic seasonality or trends
• No programmatic bid simulation: Cannot predict programmatic demand competition

For production-grade forecasting with higher accuracy, additional development would be required to integrate with CTR prediction, simulate frequency caps, and model budget exhaustion over time.

Error Handling

Status Code	Description	Common Causes
200	Successful forecast	-
400	Invalid request	Missing fields, invalid dates, unknown publisher
500	Server error	Database issues, insufficient data

Testing

# Generate test data
docker compose exec openadserve go run ./tools/traffic_simulator

# Run unit tests
go test ./internal/forecasting/ -v

# Test API endpoint
curl -X POST http://localhost:8787/forecast \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2024-06-01T00:00:00Z",
    "end_date": "2024-06-08T00:00:00Z",
    "budget_type": "cpm",
    "budget": 1000,
    "cpm": 5,
    "publisher_id": 1
  }'

---

Related Topics

Core Concepts

• Ad Decisioning - The forecasting engine mirrors the same selection algorithm and conflict resolution logic
• Analytics - Historical impression and click data powers traffic pattern analysis

Integration

• API Reference - Complete documentation for the /forecast endpoint
• AdCP Integration - AI-powered inventory discovery using natural language queries

Campaign Setup

• Campaign Management - Use forecasting insights when planning campaign budgets and schedules
• Targeting - Forecasting accounts for all targeting criteria when predicting availability