# Kevel Forecast

Kevel Forecast allows you to consider long-term seasonality through expert input from your business on how the Ad Requests will vary during particular moments in time throughout the year, across the network and/or on specific sites, zones, formats, geos, or any other dimension Kevel receives as part of the Ad Requests.

This expert input is sent to Kevel Forecast as Traffic Modifiers - the mechanism to adjust predicted Ad Request levels. This enables teams to enforce a "50% more Ad Requests" logic to the entire traffic or a subset of traffic for a given period. Each of these is called a "traffic modifier."

Traffic modifiers operate at the user level to modify the traffic to the desired volume. As such, small deviations from the requested traffic volume can be expected.

To see how traffic modifiers can be created and managed, see the [API documentation](https://dev.kevel.com/reference/post_forecaster-modifiers-traffic).

## Targeting

Each traffic modifier has an `id`, `type`, `startDate`, an `endDate`, and a `rule` field. For more information about the targeting rule format, see [Custom Targeting](https://dev.kevel.com/docs/custom-targeting).

## Traffic Modifier Types

### Ad Request Multiplier

An "Ad Request Multiplier" multiplies the predicted targeted traffic by a given constant factor, against what is the existing Forecast prediction.

For example, it's possible to tell the system about a 10% drop in traffic from the USA during Thanksgiving with the following traffic modifier:

```json
{
    "id": "thanksgiving-2024",
    "type": "adRequestMultiplier",
    "startDate": "2024-11-23T07:00:00",
    "endDate": "2024-11-23T23:00:00",
    "timeZone": "US/Central",
    "multiplier": 0.9,
    "rule": "$location.countryCode = \"US\""
}
```

Note that multiplier traffic modifiers can also be used to upscale traffic, for example:

```json
{
    "id": "blackfriday-2024",
    "type": "adRequestMultiplier",
    "startDate": "2024-11-24T07:00:00",
    "endDate": "2024-11-24T23:00:00",
    "timeZone": "US/Central",
    "multiplier": 1.5,
    "rule": "$location.countryCode = \"US\""
}
```

### Ad Request Count

An "Ad Request count" attempts to set the number of targeted Ad Decision Requests (ADRs) to a constant value. This upscales/downscales the result as needed. For example, to force the forecast to consider 100 000 Ad Requests coming from Great Britain during Christmas, the following traffic modifier could be applied:

```json
{
    "id": "christmas-2024",
    "type": "adRequestCount",
    "startDate": "2024-12-24T07:00:00",
    "endDate": "2024-12-25T23:00:00",
    "count": 100000,
    "rule": "$location.countryCode = \"GB\""
}
```

### Placement Opportunity Ratio

A "Placement Opportunity Ratio" scales the per-placement opportunities of the placements matched by the rule, keeping a given fraction of them. The `ratio` field is a value between `0` and `1`: `1.0` keeps every matching placement, while `0.0` drops them all. Use the `rule` to target individual placements (e.g. `$divName = \"iframe\"`); if no rule is set, every placement is scaled.

This makes it useful to simulate opportunity drops — for example, modeling the impact of removing or reducing a placement (such as an ad slot being deprecated or shown less often) without changing the underlying Ad Request volume.

For example, to keep only half of the placement opportunities served on `iframe` placements:

```json
{
    "id": "iframe-ratio-2024",
    "type": "placementOpportunityRatio",
    "startDate": "2024-09-03T00:00:00",
    "endDate": "2024-09-04T23:59:59",
    "ratio": 0.5,
    "rule": "$divName = \"iframe\""
}
```

## Operations

When making use of both Ad Request Multiplier and Ad Request Counts, Kevel Forecast will always attempt to reach the desired count of each Ad Request Count even when applying the Ad Request Multipliers.

For example, setting traffic modifiers for the US traffic such as an Ad Request Multiplier of 80% and an Ad Request Count of 2 million Ad Requests should be identical to setting only the Ad Request Count. Note, however, if the Ad Request Multiplier has different targeting criteria, for example, ADRs from North America, while Kevel Forecast would still try to force the number of ADRs from the US to 2 million, the Ad Request Multiplier would modify traffic outside the US which could affect the simulation results.

### Sampling considerations

Given that Traffic Modifiers operate at the user level, if an Ad Request Multiplier drives the pool of unique users to a low volume, slight differences between applying _both_ an Ad Request Multiplier and an Ad Request Count and _only_ an Ad Request Count are expected (since the multiplier will reduce the user pool).

### Asynchronous processing

Traffic Modifiers created via the API are asynchronously processed and loaded to the forecast internal engine. This process doesn't necessarily happen right after creating or modifying a Traffic Modifier, which can cause a drift between the current view of the Traffic Modifiers and the modifiers effectively used in Forecasts.

## Warnings and Troubleshooting

### Performance implications

To reliably simulate campaign delivery algorithms, the performance cost of applying a forecaster traffic modifier is similar to the cost of running a forecast in a system with that number of entries (i.e. applying a traffic modifier that doubles the traffic will be as slow as having the network suddenly having with twice as many Ad Requests, but without any hardware scaling happening).

### Warning messages

An incorrectly defined traffic modifier can lead to performance and quality issues that can be hard to debug. To help debug such problems, Kevel Forecast sends Warnings in the forecast response. While the existence of a warning does not mean that a forecast is incorrect, if a forecast is exhibiting slow performance or strange results, it can give some insights about the underlying cause.

### DATETRF
```json
{
  "code": "DATETRF",
  "message": "Forecast considering traffic modifiers as they were defined on 2025-03-11T05:00:00"
}
```

### MODTRF
```json
{
  "code": "MODTRF",
  "message": "Traffic modified by: us-traffic-modifier, minnesota-traffic-modifier",
  "causes": ["$location.countryCode = \"US\"", "$location.region = \"MN\""]
}
```

### OVRTRF
```json
{
  "code": "OVRTRF",
  "message": "Modifiers overlap at: us-traffic-modifier, minnesota-traffic-modifier",
  "causes": ["{$location.countryCode = \"US\", $location.region = \"MN\"}"]
}
```

This warning is raised if Kevel Forecast detects that two or more traffic modifiers overlap each other. This situation may lead to unexpected results if the overlaps weren't considered during the design of the modifiers.