Available forecast

Availability Forecast

Use an available forecast to estimate future inventory that is available or already booked. Available forecasts support two request shapes:

• Set Priority or PriorityId, plus optional Targeting, to ask how much matching inventory is available at that priority level.
• Set NewAds to ask how much inventory would be available to the supplied ads. When NewAds is present, do not also set Targeting, Priority, or PriorityId. The targeting, capping, priority, and pricing rules come from the supplied ads and their flights.

Forecast uses Kevel's priority ordering for each placement to compare existing booked ads with the requested priority. Opportunities count as available when the requested priority would beat the booked ad, or when no existing ad is booked for that opportunity. Opportunities count as booked when an existing ad would beat or tie the requested priority.

Bid prices affect available forecasts only when the request uses NewAds. A request with Priority or PriorityId does not include an ad or bid, so bid prices do not change the available and booked split. A request with NewAds evaluates the supplied ads with their flight priority and price. For auction priorities, the supplied ad's bid or price is part of the comparison against competing existing ads. If the supplied ad would outrank the competing ad, the opportunity can count as available. If the competing ad would still win, it counts as booked.

The following example uses Priority and Targeting:

{
  "Type": "available",
  "StartDate": "2023-04-10",
  "EndDate": "2023-04-15",
  "TimeZone": "UTC",
  "Targeting": {
    "FreqCapType": 1,
    "FreqCapDuration": 0,
    "FreqCap": 0,
    "Keywords": "dodge\ntruck",
    "ActiveKeywords": [
      "tacocat",
      "potato cat"
    ],
    "GeoTargeting": [
      {
        "CountryCode": "US",
        "Region": "NY",
        "MetroCode": "10001",
        "IsExclude": true
      }
    ],
    "DistanceTargeting": [
      {
        "Distance": 20,
        "Latitude": 41.40338,
        "Longitude": 2.17403,
        "StreetAddress": "1 Kevel Boulevard, Keveltown NY 27701"
      }
    ],
    "SiteZoneTargeting": [
      {
        "SiteId": 1234567,
        "ZoneId": 987654,
        "IsExclude": true
      }
    ],
    "CustomTargeting": [
      "string"
    ],
    "DayParting": [
      {
        "StartTime": "string",
        "EndDate": "string",
        "WeekDays": [
          "TH",
          "FR"
        ]
      }
    ],
    "TemplateValues": "{\"ctString\":\"A string goes here\",\"ctExternalFile\":\"http://cdn.com/ad.gif\"}"
  },
  "Priority": 0,
  "Params": {
    "Sampling": 1,
    "Responsiveness": 1,
    "GroupBy": [
      "$location.city"
    ]
  }
}

An example of the result would be:

{
    "resultStatus": "success",
    "result": {
        "total": {
            "available": {
                "impressions": 200792,
                "uniqueUsers": 75464
            },
            "booked": {
                "impressions": 0,
                "uniqueUsers": 0
            }
        },
        "grouped": [
            {
                "key": {
                    "$location.city": "New York"
                },
                "values": {
                    "available": {
                        "impressions": 200792,
                        "uniqueUsers": 75464
                    },
                    "booked": {
                        "impressions": 0,
                        "uniqueUsers": 0
                    }
                }
            }
        ]
    },
    "id": "27db30f3-3ff8-4a75-b91b-6e20e0553cb2",
    "status": "finished",
    "progress": 100.0,
    "desc": "Forecast is finished"
}

The total amount of impressions are the sum of the available and the booked (the ones reserved for other campaigns).

Interpreting available forecast numbers

An available forecast can use either targeting criteria or NewAds. The request input determines what the result inner fields mean.

• Using targeting criteria: accepts Priority or PriorityId and, optionally, a Targeting field.
• Using NewAds: accepts one or more ads in NewAds. Targeting rules and priorities are encoded in the supplied ads and their flights.

Forecast Explorer builds available forecast requests with PriorityId and Targeting, so its results follow the targeting criteria interpretation below.

Yield Forecast's all-inventory and ad-product trigger endpoints, as well as the Forecast availability widget, build available forecast requests with NewAds, so their results follow the NewAds interpretation below.

Using targeting criteria

A request using targeting criteria asks: "At this targeting and priority level, how many matching future opportunities are not already held by ads that would beat or tie this priority?"

The request does not include an ad. Matching opportunities count toward available when they are unfilled or held by existing ads that the requested priority would beat. Existing ads that would beat or tie the requested priority count toward booked.

Important consequences:

• available is matching opportunity at the requested priority level, not delivery for one concrete ad.
• An eligible multi-winner placement contributes all available impressions. For example, if a placement returns 20 winners, the forecast can count 20 available impressions even though a single ad could not fill all 20 winning spots in that placement.
• Flight distribution rules and advertiser placement limits are not applied, because there is no ad.
• Bid values do not define the available and booked split. The split comes from Kevel's priority ordering for the placement.
• Available revenue is not calculated when using targeting criteria.
• The response does not include the inventory object. At this priority level, available and booked already provide that split.

These numbers are useful when you want a broad view of matching opportunities at a priority level.

Using NewAds

A request using NewAds asks: "If these ads existed, how many opportunities are projected to be available for them to win?"

The forecast considers the supplied NewAds along with the ads already running in the network.

Important consequences:

• available is the number of impressions, clicks, unique users, revenue, and events projected to be available for the supplied ads.
• uncapped is the companion count for opportunities the supplied ads could win if caps and distribution rules were relaxed. Treat it as a separate no-cap view, not as a subtraction from available.
• booked is the count of opportunities where competing existing ads prevent the supplied ads from winning.
• A supplied ad can serve at most once for a placement. Multiple supplied ads can fill multiple slots only when serving rules allow it.
• Flight distribution rules, campaign and advertiser limits, ad caps, frequency caps, and daily caps can reduce available.
• Auction priorities consider bid or price.
• Available revenue is calculated when using NewAds.

The response for this variant also includes an inventory object that contains:

• bookedAtHigher: forecasted opportunities already booked by existing ads that would be selected ahead of the supplied ads.
• bookedAtLower: forecasted opportunities already booked by existing ads that would be selected after the supplied ads.
• empty: forecasted opportunities not booked by any existing ad.