type AvailabilityForecast (v201808)

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/v201808

    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.
    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, availbleUnits=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],
                    ForecastBreakdow{startTime=2am, endTime=3am, breakdownEntries=[availalbleUnits=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=[availalbleUnits=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.

    demographicBreakdowns

    GrpDemographicBreakdown[]

    The forecast result broken down by demographics.

    Send feedback about...

    Ad Manager API
    Ad Manager API
    Need help? Visit our support page.