Traffic Modifiers

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 .

🚧

Advanced feature warning

Use this feature with caution. Due to its ability to reshape the entire predicted Ad request traffic, it can impact quality and performance of forecasts. Always test new modifiers before storing them via API by attaching them to individual forecasts to see the results. Please read the "Warnings and Troubleshooting" section carefully before using this feature.

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.

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:

{
    "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:

{
    "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:

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

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.

Kevel Forecast raises the DATETRF warning to help understand when this loading process happened. Additionally, the MODTRF warning also conveys the IDs and respective rules of the traffic modifiers that were applied.

Currently, the loading process happens daily and we are working on reducing that interval.

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.

Apart from the DATETRF, each warning has a message field that contains the IDs of the traffic modifiers and a causes field with the respective traffic modifier rules (or the value "All" when no rule is specified).

DATETRF

This warning is raised if any traffic modifier is applied during the forecast. It conveys the data of when the traffic modifiers were loaded into the simulation engine. While this warning can usually be safely ignored, it helps to understand why an update or change to the traffic modifiers via the API isn't yet being reflected.

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

MODTRF

This warning is raised if any traffic modifier is applied during the forecast. While this warning can usually be safely ignored, it helps to debug common problems (e.g. the targeting rule of a traffic modifier might be too broad).

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

OVRTRF

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. In this warning, the causes field contains all the distinct combinations of rules that overlap.

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

For example, imagine that a human expert wants to define a small "ramp-up" in traffic, by multiplying the traffic on the first day by 1.5 and the traffic on the second day by 2.0. Assume that, due to an oversight, the rules were defined as follows, with an overlap from "2024-02-02 00:00:00" to "2024-02-02 12:00:00":

{
    "id": "traffic-modifier-a",
    "type": "multiplier",
    "startDate": "2024-02-01 00:00:00",
    "endDate": "2024-02-02 12:00:00",
    "multiplier": 1.5,
}

{
    "id": "traffic-modifier-b",
    "type": "multiplier",
    "startDate": "2024-02-02 00:00:00",
    "endDate": "2024-02-03 00:00:00",
    "multiplier": 2,
}

If this happens, the traffic from "2024-02-02 00:00:00" to "2024-02-02 12:00:00" will be multiplied by 3 (1.5 * 2), which is not the behavior intended by the expert. This can be particularly disruptive if an Ad Request Multiplier is inserted twice (effectively squaring the original multiplier) or if an Ad Request Multiplier overlaps with an Ad Request Count.