Method: networks.runAvailabilityForecast

Gets the availability forecast for a [ProposalLineItem][] or LineItem. An availability forecast reports the maximum number of available units that the line item can book, and the total number of units matching the line item's targeting.

HTTP request

POST https://admanager.googleapis.com/v1/{parent}:runAvailabilityForecast

Path parameters

Parameters
parent

string

Required. Format: networks/{networkCode}

Request body

The request body contains data with the following structure:

JSON representation 
{
  "availabilityForecastOptions": {
    object (AvailabilityForecastOptions)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "existingLineItem": string
  // End of mutually exclusive fields.
}
Fields
availabilityForecastOptions

object (AvailabilityForecastOptions)

Required. The availability forecast options.
The LineItem to be forecasted. Only one of the following fields can be set. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response:
existingLineItem

string

Optional. The resource name of the LineItem to be forecasted. Format: networks/{networkCode}/lineItems/{lineItemId}
End of mutually exclusive fields.

Response body

Response object for [networks.runAvailabilityForecast][] method.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "availabilityForecastResult": {
    object (AvailabilityForecast)
  }
}
Fields
availabilityForecastResult

object (AvailabilityForecast)

The availability forecast.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/admanager
  • https://www.googleapis.com/auth/admanager.readonly

For more information, see the OAuth 2.0 Overview.

AvailabilityForecastOptions

Forecasting options for ProspectiveLineItem availability forecasts.

JSON representation 
{
  "targetingCriteriaBreakdownIncluded": boolean,
  "contendingLineItemsIncluded": boolean,
  "breakdown": {
    object (ForecastBreakdownOptions)
  }
}
Fields
targetingCriteriaBreakdownIncluded

boolean

Optional. When specified, forecast result for the availability line item will also include breakdowns by its targeting in [AvailabilityForecast.targetingCriteriaBreakdowns][].
contendingLineItemsIncluded

boolean

Optional. When specified, the forecast result for the availability line item will also include contending line items in [AvailabilityForecast.contendingLineItems][].
breakdown

object (ForecastBreakdownOptions)

Optional. Configurations of forecast breakdowns.

ForecastBreakdownOptions

Configuration of forecast breakdown.

JSON representation 
{
  "timeWindows": [
    string
  ],
  "targets": [
    {
      object (ForecastBreakdownTarget)
    }
  ]
}
Fields
timeWindows[]

string (Timestamp format)

Optional. The boundaries of time windows to configure time breakdown.

By default, the time window of the forecasted LineItem is assumed if none are explicitly specified in this field. But if set, at least two DateTimes are needed to define the boundaries of minimally one time window.

Also, the time boundaries are required to be in the same time zone, in strictly ascending order.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
targets[]

object (ForecastBreakdownTarget)

Optional. For each time window, these are the breakdown targets. If none specified, the targeting of the forecasted LineItem is assumed.

ForecastBreakdownTarget

Specifies inventory targeted by a breakdown entry.

JSON representation 
{
  "displayName": string,
  "targeting": {
    object (Targeting)
  },
  "creativePlaceholder": {
    object (CreativePlaceholder)
  }
}
Fields
displayName

string

An optional name for this breakdown target, to be populated in the corresponding [ForecastBreakdownEntry.displayName][] field.
targeting

object (Targeting)

If specified, the targeting for this breakdown. Format: networks/{networkCode}/targetings/{targeting}
creativePlaceholder

object (CreativePlaceholder)

If specified, restrict the breakdown to only inventory matching this creative.

AvailabilityForecast

Describes predicted inventory availability for a ProspectiveLineItem. Inventory has three threshold values along a line of possible inventory. From least to most, these are:

Available units -- How many units can be booked without affecting any other line items. Booking more than this number can cause lower and same priority line items to underdeliver. Possible units -- How many units can be booked without affecting any higher priority line items. Booking more than this number can cause the line item to underdeliver. Matched (forecast) units -- How many units satisfy all specified criteria.

Underdelivery is caused by overbooking. However, if more impressions are served than are predicted, the extra available inventory might enable all inventory is able to be met without overbooking.

JSON representation 
{
  "breakdowns": [
    {
      object (ForecastBreakdown)
    }
  ],
  "targetingCriteriaBreakdowns": [
    {
      object (TargetingCriteriaBreakdown)
    }
  ],
  "contendingLineItems": [
    {
      object (ContendingLineItem)
    }
  ],
  "alternativeUnitTypeForecasts": [
    {
      object (AlternativeUnitTypeForecast)
    }
  ],
  "demographicBreakdowns": [
    {
      object (GrpDemographicBreakdown)
    }
  ],
  "lineItem": string,
  "order": string,
  "unitType": enum (UnitType),
  "availableUnits": string,
  "deliveredUnits": string,
  "matchedUnits": string,
  "possibleUnits": string,
  "reservedUnits": string
}
Fields
breakdowns[]

object (ForecastBreakdown)

The breakdowns for each time window defined in [ForecastBreakdownOptions.timeWindows][].

If no breakdown was requested through AvailabilityForecastOptions.breakdown, this field will be empty.
targetingCriteriaBreakdowns[]

object (TargetingCriteriaBreakdown)

The forecast result broken down by the targeting of the forecasted line item.
contendingLineItems[]

object (ContendingLineItem)

List of ContendingLineItem contending line items for this forecast.
alternativeUnitTypeForecasts[]

object (AlternativeUnitTypeForecast)

Views of this forecast, with alternative unit types.
demographicBreakdowns[]

object (GrpDemographicBreakdown)

The forecast result broken down by demographics.
lineItem

string

Uniquely identifies this availability forecast. This value is read-only and is assigned by Google when the forecast is created. The attribute will be either the resource name of the LineItem object it represents, or null if the forecast represents a prospective line item. Format: networks/{networkCode}/lineItems/{lineItemId}
order

string

The resource name for the Order object that this line item belongs to, or null if the forecast represents a prospective line item without an LineItem.order set. Format: networks/{networkCode}/orders/{orderId}
unitType

enum (UnitType)

The unit with which the goal or cap of the LineItem is defined. Will be the same value as [Goal.unitType][] for both a set line item or a prospective one.
availableUnits

string (int64 format)

The number of units, defined by [Goal.unitType][], that can be booked without affecting the delivery of any reserved line items. Exceeding this value won't cause an overbook, but lower priority line items may not run.
deliveredUnits

string (int64 format)

The number of units, defined by [Goal.unitType][], that have already been served if the reservation is already running.
matchedUnits

string (int64 format)

The number of units, defined by [Goal.unitType][], that match the specified targeting and delivery settings.
possibleUnits

string (int64 format)

The maximum number of units, defined by [Goal.unitType][], that could be booked by taking inventory away from lower priority line items and some same priority line items.

Booking this number may cause lower priority line items and some same priority line items to underdeliver.
reservedUnits

string (int64 format)

The number of reserved units, defined by [Goal.unitType][], requested. This can be an absolute or percentage value.

ForecastBreakdown

Represents the breakdown entries for a list of targetings and creatives.

JSON representation 
{
  "startTime": string,
  "endTime": string,
  "namedEntries": [
    {
      object (ForecastBreakdownEntry)
    }
  ]
}
Fields
startTime

string (Timestamp format)

The starting time of the represented breakdown.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
endTime

string (Timestamp format)

The end time of the represented breakdown.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
namedEntries[]

object (ForecastBreakdownEntry)

The forecast breakdown entries in the same order as in the ForecastBreakdownOptions.targets field.

ForecastBreakdownEntry

A single forecast breakdown entry.

JSON representation 
{
  "forecast": {
    object (DeliveryForecast)
  },
  "displayName": string
}
Fields
forecast

object (DeliveryForecast)

The forecast of this entry.
displayName

string

The optional name of this entry, as specified in the corresponding [ForecastBreakdownTarget.displayName][] field.

DeliveryForecast

Represents a single delivery data point, with both available and forecast number.

JSON representation 
{
  "matched": string,
  "available": string,
  "possible": string
}
Fields
matched

string (int64 format)

The number of units matching the specified targeting and delivery settings.
available

string (int64 format)

The number of units that can be booked without affecting the delivery of any reserved LineItems.
possible

string (int64 format)

The number of units that can be booked without affecting the delivery of any reserved LineItem or lower priority LineItem.

TargetingCriteriaBreakdown

A single targeting criteria breakdown result.

JSON representation 
{
  "targetingDimension": enum (ForecastingTargetingDimension),
  "targetingCriteriaId": string,
  "targetingCriteria": string,
  "excluded": boolean,
  "availableUnits": string,
  "matchedUnits": string
}
Fields
targetingDimension

enum (ForecastingTargetingDimension)

The dimension of this breakdown
targetingCriteriaId

string (int64 format)

The unique ID of the targeting criteria.
targetingCriteria

string

The name of the targeting criteria.
excluded

boolean

When true, the breakdown is negative.
availableUnits

string (int64 format)

The available units for this breakdown.
matchedUnits

string (int64 format)

The matched units for this breakdown.

ForecastingTargetingDimension

Targeting dimension of targeting breakdowns.

Enums
FORECASTING_TARGETING_DIMENSION_UNSPECIFIED Default value. This value is unused.
AD_SIZE The targeting dimension is ad size.
AD_UNIT The targeting dimension is ad unit.
BANDWIDTH_GROUP The targeting dimension is bandwidth group.
BROWSER The targeting dimension is browser.
BROWSER_LANGUAGE The targeting dimension is browser language.
CONTENT The targeting dimension is content.
CONTENT_LABEL The targeting dimension is content label.
CUSTOM_CRITERIA The targeting dimension is custom criteria.
DEVICE_CAPABILITY The targeting dimension is device capability.
DEVICE_CATEGORY The targeting dimension is device category.
DEVICE_MANUFACTURER The targeting dimension is device manufacturer.
FORECASTED_CREATIVE_RESTRICTION The targeting dimension is forecasted creative restriction.
GEOGRAPHY The targeting dimension is geography.
MOBILE_APPLICATION The targeting dimension is mobile application.
MOBILE_CARRIER The targeting dimension is mobile carrier.
OPERATING_SYSTEM The targeting dimension is operating system.
PLACEMENT The targeting dimension is placement.
USER_DOMAIN The targeting dimension is user domain.
VERTICAL The targeting dimension is vertical.
VIDEO_POSITION The targeting dimension is video position.

ContendingLineItem

Describes contending line items for a forecast.

JSON representation 
{
  "lineItem": string,
  "contendingUnits": string
}
Fields
lineItem

string

The resource name of the contending line item. Format: networks/{networkCode}/lineItems/{lineItemId}
contendingUnits

string (int64 format)

The number of impressions contended for by both the forecasted line item and this line item.

AlternativeUnitTypeForecast

Views of this forecast, with alternative unit types.

JSON representation 
{
  "unitType": enum (UnitType),
  "matchedUnits": string,
  "availableUnits": string,
  "possibleUnits": string
}
Fields
unitType

enum (UnitType)

The alternative unit type being presented.
matchedUnits

string (int64 format)

The number of units matching the specified targeting and delivery settings.
availableUnits

string (int64 format)

The number of units that can be booked without affecting the delivery of any reserved line items.
possibleUnits

string (int64 format)

The number of units that can be booked without affecting the delivery of any reserved line items or lower priority line items.

GrpDemographicBreakdown

GRP forecast breakdown counts associated with a gender and age demographic.

JSON representation 
{
  "availableUnits": string,
  "matchedUnits": string,
  "unitType": enum (ForecastingGrpUnit),
  "gender": enum (ForecastingGrpGender),
  "age": enum (ForecastingGrpAge)
}
Fields
availableUnits

string (int64 format)

The number of units matching the demographic breakdown that can be booked without affecting the delivery of any reserved line items.
matchedUnits

string (int64 format)

The number of units matching the demographic and matching specified targeting and delivery settings.
unitType

enum (ForecastingGrpUnit)

The GrpUnitType associated with this demographic breakdown.
gender

enum (ForecastingGrpGender)

The GrpGender associated with this demographic breakdown.
age

enum (ForecastingGrpAge)

The GrpAge associated with this demographic breakdown.

ForecastingGrpUnit

Type of unit represented in a GRP demographic breakdown.

Enums
FORECASTING_GRP_UNIT_UNSPECIFIED Default value. This value is unused.
IMPRESSIONS The type of unit represented in the GRP demographic breakdown is impressions.

ForecastingGrpGender

The demographic gender associated with a GRP demographic forecast.

Enums
FORECASTING_GRP_GENDER_UNSPECIFIED Default value. This value is unused.
GENDER_FEMALE The demographic gender is female.
GENDER_MALE The demographic gender is male.
GENDER_UNKNOWN When gender is not available due to low impression levels, GRP privacy thresholds are activated and prevent us from specifying gender.

ForecastingGrpAge

The age range associated with a GRP demographic forecast.

Enums
FORECASTING_GRP_AGE_UNSPECIFIED Default value. This value is unused.
AGE_0_TO_17 GRP age range from 0 to 17 years old.
AGE_18_TO_24 GRP age range from 18 to 24 years old.
AGE_18_TO_49 GRP age range from 18 to 49 years old.
AGE_21_PLUS GRP age range from 21 years old and up.
AGE_21_TO_34 GRP age range from 21 to 34 years old.
AGE_21_TO_44 GRP age range from 21 to 44 years old.
AGE_21_TO_49 GRP age range from 21 to 49 years old.
AGE_21_TO_54 GRP age range from 21 to 54 years old.
AGE_21_TO_64 GRP age range from 21 to 64 years old.
AGE_25_TO_34 GRP age range from 25 to 34 years old.
AGE_25_TO_49 GRP age range from 25 to 49 years old.
AGE_35_TO_44 GRP age range from 35 to 44 years old.
AGE_35_TO_49 GRP age range from 35 to 49 years old.
AGE_45_TO_54 GRP age range from 45 to 54 years old.
AGE_55_TO_64 GRP age range from 55 to 64 years old.
AGE_65_PLUS GRP age range from 65 years old and up.
AGE_UNKNOWN When the age range is not available due to low impression levels, GRP privacy thresholds are activated and prevent us from specifying age.