Getting Started with Kevel Forecast

Kevel Forecast provides the insights you need to see what inventory is available and how a campaign will deliver. You have the ability to predict future ad traffic levels and campaign inventory availability using an unlimited number of targeting variables, including geo, keyword, key-value, user segment, or frequency capping.

For Forecast use cases and types, check out the Forecast Overview.

Getting Started

APIs available:

Forecast:

Available forecast, provides a fast forecast with the amount of available inventory for a given new or modified set of ads, flights and campaigns
Deliverable forecast, provides simulated forecasted delivery of a new campaign, re-estimating the changes that will occur to all other ads in the network
Existing forecast, provides forecasts for all currently booked and active campaigns, flights and ads
Yield forecast, provides a set of interfaces for configuring network yield forecast settings, creating ad products and obtaining their forecasts. There is a handy guide for how to build your own yield forecast dashboard using these apis.

Forecast setup:

Traffic modifiers, provides means to adjust traffic shapes for enforcing business seasonality rules
Static audiences, provides a way to bootstrap new static audiences segments in Forecast, skipping the need to wait a few days for inventory to build up and improving their forecast accuracy by better modelling the behaviour of a static user list vs a continuously updates audience segment

Asynchronous API

It’s important to note that the Kevel Forecast API is asynchronous. You can request a forecast to be performed via a POST to https://api.kevel.co/v1/forecaster/ with the appropriate API key and you always get back a response such as the following:

JSON

{
  "id": "8a6f6bf5-f823-409f-8746-9ae047190cc3",
  "status": "enqueued",
  "progress": 0.0,
  "desc": "Forecast is queued"
}

This object contains an id that you can use in a GET request to https://api.kevel.co/v1/forecaster/{id} to get the forecast result back. Forecasts can take a few seconds to some minutes to complete, depending on the amount of ads involved, how far into the future we’re forecasting and the sampling level. A complete forecast result is one whose response has the status “finished”. For example, the following is a response to a finished forecast:

JSON

{
  "resultStatus": "success",
  "result": {
    "total": {
      "329797406": {
        "impressions": 0,
        "uniqueUsers": 0
      },
      "336416380": {
        "impressions": 76792,
        "uniqueUsers": 31718
      }
    }
  },
  "id": "8a6f6bf5-f823-409f-8746-9ae047190cc3",
  "status": "finished",
  "progress": 100.0,
  "desc": "Forecast is finished"
}

Forecast dates

Forecast requests require an end date and, optionally, in some forecast types, the start date as parameters. These dates can suffer minor adjustments to reflect the availability of future inventory and existing campaigns' information.

The dates effectively used by the forecast are returned in its results as forecastStartDate and forecastEndDate.

Grouping-by and time zone considerations

In GroupBy you can define any key you can use in custom targeting, as well as some custom ones like $datetime.date. For example, the following payload triggers a forecast request for existing ads using sampling level 3 and grouping results by site and date:

JSON

{
  "Type": "existing",
  "EndDate": "2023-03-20",
  "Params": {
    "Sampling": 3,
    "GroupBy": ["$site", "$datetime.date"],
    "TimeZone": "UTC"
  }
}

Forecast results for requests with a GroupBy parameter have an additional field in the result object, called grouped, where you can see results for each ad grouped by the possible values of each tuple of grouping keys. The TimeZone parameter in the Params field specifies in which time zone should time-related fields in the GroupBy be considered in, defaulting to UTC if no TimeZone is set.

JSON

{
  "resultStatus": "success",
  "result": {
    "total": {
      "1234567891": {
        "impressions": 0,
        "uniqueUsers": 0
      },
      "1234567890": {
        "impressions": 76136,
        "uniqueUsers": 31680
      },
      "1234567899": {
        "impressions": 294776,
        "uniqueUsers": 97152
      },
      (...) 
    },
    "grouped": [
      {
        "key": {
          "$site": 1234567,
          "$datetime.date": "2023-03-14"
        },
        "values": {
          "1234567891": {
            "impressions": 0,
            "uniqueUsers": 0
          },
          "1234567890": {
            "impressions": 38488,
            "uniqueUsers": 17464
          },
          "1234567899": {
            "impressions": 0,
            "uniqueUsers": 0
          },
          (...) 
        }
      },
      (...) 
    ]
  },
  "id": "33665016-a0e6-4bc0-98a2-ad14aca86053",
  "status": "finished",
  "progress": 100.0,
  "desc": "Forecast is finished"
}

Large result set warning

Note that large combinations of grouping keys can result in very large forecast results. Settings within the Params object can be used with any forecast type.

When no value is available for the specified GroupBy key in the predicted impression, the results will be grouped by the value null for that key.

Click forecasts

Forecast responses also return the estimated number of Clicks, alongside the Impression and Unique Users. This enables CTR can be easily derived (Clicks / Impressions) for any resulting forecast at any grouping level (e.g. CTR by Site, Geo and Placement):

JSON

{
    "requestDateTime": "2023-09-22T14:14:08.540Z",
    "lastUpdateDateTime": "2023-09-22T14:14:15.070Z",
    "startDateTime": "2023-09-22T14:14:09.176Z",
    "endDateTime": "2023-09-22T14:14:15.070Z",
    "resultStatus": "success",
    "result": {
        "total": {
            "clicks": 880,
            "impressions": 135392,
            "uniqueUsers": 43952
        },
        "grouped": [
            {
                "key": {
                    "$site": 12345679
                },
                "value": {
                    "clicks": 0,
                    "impressions": 168,
                    "uniqueUsers": 24
                }
            }
            ...
        ]
    },
    "id": "45dff65f-e4a0-4f8a-98b9-960a9f5b7240",
    "status": "finished",
    "progress": 100.0,
    "desc": "Forecast is finished"
}

🚧

Lag between impression and click event tracking

A drift/delay in sending Click events may result in missed and inaccurate click predictions, so it is advised to minimize the delay between a click happening and sending it to Kevel.