Request forecast

Available Forecast Request

A request to perform an availability forecast, i.e., querying the predicted inventory to find the total amount of available (and booked) clicks, impressions, revenue, unique users, and custom events that exist at a given Priority level (weight).

These are calculated by applying the supplied targeting rules or new ads after the delivery of all existing campaigns with priority weights equal to or above the supplied Priority.

The priority can be specified in two manners. Either by the Priority or PriorityId fields (only one of them can be defined) or by the priorities that are defined in the Flights when the NewAds field is passed.

When the NewAds field is specified, the Targeting, Priority, and PriorityId fields cannot be, since all the targeting, capping, and priority rules will be encoded in the Flight and Ads passed in NewAds.

Additionally, if the NewAds provided contain a flight that shares the same ID with another one from the Ad Platform inventory, the simulated deliveries to that booked flight will be considered as potentially available for any of the provided Ads from flight.

Note that the available revenue is only calculated when the NewAds field is provided.

Fields

• Type
  Type: string
  Enum: available
  Required

• StartDate
  Type: date-time
  Start date of the available forecast from which availability will be checked, as yyyy-mm-dd'T'HH:mm:SS or yyyy-mm-dd (default time of 00:00:00), in the passed TimeZone or UTC if omitted.

• EndDate
  Type: date-time
  Required
  End date of the available forecast, must be after current date, as yyyy-mm-dd'T'HH:mm:SS or yyyy-mm-dd (default time of 23:59:59), in the passed TimeZone or UTC if omitted.

• TimeZone
  Type: string
  Defaults to UTC
  The time zone of the available forecast's start and end dates (available time zones). Additionally, day parting is evaluated in the available forecast's time zone.

• Targeting
  Type: object
  The specified targeting for the available forecast.

  • Targeting object
    • Priority
      Type: integer
      The priority weight at which availability will be calculated, impressions for existing ads with a "lower" priority than this will be considered available. This does not take into consideration ordering and filtering done at the site or channel level.
    • PriorityId
      Type: integer
      The ID of a Kevel Priority at which availability will be calculated, impressions for existing ads with a "lower" priority than this will be considered available.

• NewAds
  Type: array of objects
  The new ad or ads to consider in the availability request.

  • Modifiers
    Type: object
    Manual Forecast Modifiers to apply to this forecast request. Currently, only Traffic Modifiers are supported. Traffic modifiers operate at the Ad Request level and make it possible to manually modify the volume of Ad Request in a certain date range and, optionally, that follow a targeting rule.

Response Structure

{
  "id": "1978ad40-97da-403e-ad5d-c3e71c75a593",
  "desc": "This forecast is still being processed. Partial results are available",
  "eta": "2022-11-17T21:48:37+00:00",
  "status": "partial",
  "progress": 33.3,
  "requestDateTime": "2023-07-19T16:24:46.648Z",
  "lastUpdateDateTime": "2023-07-19T16:24:46.648Z",
  "startDateTime": "2023-07-19T16:24:46.648Z",
  "endDateTime": "2023-06-29T13:57:32.321",
  "forecastStartDate": "2023-06-19T16:24:46.648Z",
  "forecastEndDate": "2023-07-19T16:24:46.648Z",
  "resultStatus": "success",
  "result": {
    "total": {
      "411981212": {
        "clicks": 0,
        "impressions": 50,
        "revenue": 1,
        "uniqueUsers": 34
      },
      "412081539": {
        "clicks": 0,
        "impressions": 0,
        "revenue": 0,
        "uniqueUsers": 0
      }
    },
    "grouped": [
      {
        "key": {
          "request.localDate": "2023-08-17"
        },
        "value": {
          "411981212": {
            "clicks": 0,
            "impressions": 46,
            "revenue": 2,
            "uniqueUsers": 32
          },
          "412081539": {
            "clicks": 0,
            "impressions": 0,
            "revenue": 0,
            "uniqueUsers": 0
          }
        }
      },
      {
        "key": {
          "request.localDate": "2023-08-18"
        },
        "value": {
          "411981212": {
            "clicks": 0,
            "impressions": 4,
            "revenue": 0,
            "uniqueUsers": 2
          },
          "412081539": {
            "clicks": 0,
            "impressions": 0,
            "revenue": 0,
            "uniqueUsers": 0
          }
        }
      }
    ]
  },
  "warnings": [
    {
      "code": "DATETRF",
      "message": "string",
      "causes": ["string"],
      "metadata": {}
    }
  ],
  "forecastEnvironment": {
    "campaignSyncDateTime": "string",
    "seasonalityUsed": true,
    "reservedCampaignsSyncDateTime": "string",
    "reservedCampaignSalesWeightCutOff": 0
  }
}