Overview

Kevel's Forecast seasonality looks at the yearly traffic patterns and applies them to inventory and campaign forecasts. Once you've been running with Kevel for over a year, the traffic Kevel receives is used to determining the yearly seasonality for your sites and apps. But before you have a full year, or if you have been actively changing your Kevel inventory setup in a way that changes the expected seasonal patterns, you can feed an external traffic source to serve as the training data set, enabling a better seasonal forecast without having to wait for a year of stable traffic patterns.

You can also enable or disable the feature all together, as well as check the impact the seasonality settings are having on the forecasted traffic shape.

Bootstrapping with external traffic sources

The Forecast Seasonality API allows networks to submit traffic patterns to Kevel from external systems, such as analytics tools. You can upload external seasonal data by submitting a CSV file that breaks down key events, like page and app views, by day. The file may have the following columns:

date the date of the event
eventsthe total number of events for that particular day
site:<ID>the total number of events for a specific site where <ID> is the Kevel's Site identifier

Here's an example:

date,events,site:4572,site:7643
2025-01-01,236632,206845,29787
2025-01-02,690062,288547,401515
...

To upload the file, you must first request an Ingest URL by making a request to the following endpoint and specifying an arbitrary CSV filename.

Example:
POST https://api.kevel.co/v1/forecaster/auto-seasonality/ingest-url

{
  "filename": "example.csv"
}

Response:

{"url":"https://..."}

You can then send a file to the provided URL:
curl 'https://...' --upload-file ../AdForecaster2/example.csv

Preview Seasonality

The seasonality trend is generated at the beginning of the day (UTC). Once 13 months or more of data points are available, either internally (from Kevel's own ADRs) or imported (as described above), you can fetch a preview of the total predicted ad traffic with and without seasonality via the following endpoint:

Example:
GET https://api.kevel.co/v1/forecaster/auto-seasonality/preview
Response:

{
 "status" : "Success.",
 "results" : {
   "withoutSeasonality" : [
     [ "2025-01-01", 292577 ],
     [ "2025-01-02", 310822 ],
     ...
   ],
   "withSeasonality" : [
     [ "2025-01-01", 262031 ],
     [ "2025-01-02", 223945 ],
     ...
   ]
 }
 ...
}

Toggling Seasonality

You can use the following endpoints to determine if (a) seasonality should be enabled and if (b) it should be correlated with the imported files.

For (a), once auto seasonality is enabled, it will only take effect the next day (UTC) as the total ad traffic prediction process runs once per day. The same applies when disabling this setting. We recommend consulting the preview first to ensure the traffic shape is acceptable before enabling the feature.

Forecast also provides an option to (b) correlate the counts derived from Kevel ADRs with those imported. For this to take effect, the internal counts must overlap with the imported data for 28 days, and the integration must be complete. Partial integrations might result in lower-than-expected volumes. We suggest consulting the preview before enabling the seasonality feature.

Enabling/Disabling Seasonality
Example:
PUT https://api.kevel.co/v1/forecaster/auto-seasonality

{
 "enabled" : true,
 "correlateImportedCounts" : true
}

Checking If Seasonality is Enabled
Example:
GET https://api.kevel.co/v1/forecaster/auto-seasonality
Response:

{
 "enabled" : true,
 "correlateImportedCounts" : true
}

Forecasts with Auto Seasonality

After making a forecast request, you can check if auto seasonality is being considered by looking at the seasonalityUsed value in the forecastEnvironment field in the forecast response.

Example:
GET /forecast/:id
Response:

{
  "id": ":id",
  "status": "finished",
  "progress": 100.0,
  "desc": "Forecast is finished",
  "forecastEnvironment": {
    "campaignSyncDateTime": "2025-10-28T12:16:30.885",
    "seasonalityUsed": true
  },
  ...
}