type AvailabilityForecast (v202402)

Service
ForecastService
Dependencies
getAvailabilityForecast() getAvailabilityForecastById()
▼
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 guarantees to be met without overbooking.

Namespace
https://www.google.com/apis/ads/publisher/v202402

Field

lineItemId

xsd:long

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 ID of the LineItem object it represents, or null if the forecast represents a prospective line item.

orderId

xsd:long

The unique ID for the Order object that this line item belongs to, or null if the forecast represents a prospective line item without an LineItem.orderId set.

unitType

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.

Enumerations
IMPRESSIONS
The number of impressions served by creatives associated with the line item. Line items of all LineItemType support this UnitType.
CLICKS
The number of clicks reported by creatives associated with the line item. The LineItem.lineItemType must be LineItemType.STANDARD, LineItemType.BULK or LineItemType.PRICE_PRIORITY.
CLICK_THROUGH_CPA_CONVERSIONS
The number of click-through Cost-Per-Action (CPA) conversions from creatives associated with the line item. This is only supported as secondary goal and the LineItem.costType must be CostType.CPA.
VIEW_THROUGH_CPA_CONVERSIONS
The number of view-through Cost-Per-Action (CPA) conversions from creatives associated with the line item. This is only supported as secondary goal and the LineItem.costType must be CostType.CPA.
TOTAL_CPA_CONVERSIONS
The number of total Cost-Per-Action (CPA) conversions from creatives associated with the line item. This is only supported as secondary goal and the LineItem.costType must be CostType.CPA.
VIEWABLE_IMPRESSIONS
The number of viewable impressions reported by creatives associated with the line item. The LineItem.lineItemType must be LineItemType.STANDARD.
IN_TARGET_IMPRESSIONS
The number of in-target impressions reported by third party measurements. The LineItem.lineItemType must be LineItemType.STANDARD.
UNKNOWN
The value returned if the actual value is not exposed by the requested API version.

availableUnits

xsd:long

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

deliveredUnits

xsd:long

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

matchedUnits

xsd:long

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

possibleUnits

xsd:long

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.

Please note: booking this number may cause lower priority line items and some same priority line items to underdeliver.

reservedUnits

xsd:long

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

breakdowns

ForecastBreakdown[]

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

If no breakdown was requested through AvailabilityForecastOptions.breakdown, this field will be empty. If targeting breakdown was requested by ForecastBreakdownOptions.targets with no time breakdown, this list will contain a single ForecastBreakdown corresponding to the time window of the forecasted LineItem. Otherwise, each time window defined by ForecastBreakdownOptions.timeWindows will correspond to one ForecastBreakdown in the same order. Targeting breakdowns for every time window are returned in ForecastBreakdown.breakdownEntries. Some examples: For a targeting breakdown in the form of ForecastBreakdownOptions{targets=[IU=A, {IU=B, creative=1x1]}}, the breakdowns field may look like: [ForecastBreakdown{breakdownEntries=[availableUnits=10, availableUnits=20]]} where the entries correspond to {IU=A} and {IU=B, creative=1x1} respectively. For a time breakdown in the form of ForecastBreakdownOptions{timeWindows=[1am, 2am, 3am]}, the breakdowns field may look like:

                              [
                ForecastBreakdown{startTime=1am, endTime=2am, breakdownEntries=[availableUnits=10],
                ForecastBreakdown{startTime=2am, endTime=3am, breakdownEntries=[availableUnits=20]}
                ]
                }
where the two ForecastBreakdown correspond to the [1am, 2am) and [2am, 3am) time windows respecively. For a two-dimensional breakdown in the form of ForecastBreakdownOptions{timeWindows=[1am, 2am, 3am], targets=[IU=A, IU=B], the breakdowns field may look like: 
                              [
                ForecastBreakdown{startTime=1am, endTime=2am,
                breakdownEntries=[availableUnits=10, availableUnits=100],
                ForecastBreakdown{startTime=2am, endTime=3am,
                breakdownEntries=[availableUnits=20, availableUnits=200]}
                ]
                }
where the first ForecastBreakdown respresents the [1am, 2am) time window with two entries for the IU A and IU B respectively; and the second ForecastBreakdown represents the [2am, 3am) time window also with two entries corresponding to the two IUs.

targetingCriteriaBreakdowns

TargetingCriteriaBreakdown[]

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

contendingLineItems

ContendingLineItem[]

List of contending line items for this forecast.

alternativeUnitTypeForecasts

AlternativeUnitTypeForecast[]

Views of this forecast, with alternative unit types.