## 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`: ```json { "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: ```json { "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.