Method: advertisers.reachForecast.generateReachForecast

Generates a reach forecast for a given advertiser and targeting configuration.

HTTP request

POST https://displayvideo.googleapis.com/v4/advertisers/{advertiserId}/reachForecast:generateReachForecast

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
advertiserId

string (int64 format)

Required. The ID of the advertiser that will run the planned campaign.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "targeting": {
    object (Targeting)
  },
  "campaignDuration": {
    object (CampaignDuration)
  },
  "currencyCode": string,
  "plannedProducts": [
    {
      object (PlannedProduct)
    }
  ],
  "minEffectiveFrequency": integer
}
Fields
targeting

object (Targeting)

Required. The targeting parameters of the planned campaign.
campaignDuration

object (CampaignDuration)

Required. The duration of the planned campaign.
currencyCode

string

Required. The currency code for the plan in ISO 4217 format.
plannedProducts[]

object (PlannedProduct)

Required. The list of line items to include in the forecast.
minEffectiveFrequency

integer

Optional. The minimum effective frequency for the reported reach metrics. This is the smallest number of times a customer must be exposed to the ad for it to be considered effective. This setting only impacts reporting.

Must be between 1 and 10, inclusive. If not specified, a default of 1 is applied.

Response body

Response message for ReachForecastService.GenerateReachForecast.

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

JSON representation 
{
  "onTargetAudienceMetrics": {
    object (OnTargetAudienceMetrics)
  },
  "reachCurve": {
    object (ReachCurve)
  }
}
Fields
onTargetAudienceMetrics

object (OnTargetAudienceMetrics)

The estimated audience sizes for the targeted geography.
reachCurve

object (ReachCurve)

The generated forecast curve.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/display-video

For more information, see the OAuth 2.0 Overview.

Targeting

Targeting settings for a planned campaign.

JSON representation 
{
  "plannableLocationIds": [
    string
  ],
  "ageRange": enum (PlannableAgeRange),
  "genders": [
    enum (Gender)
  ],
  "devices": [
    enum (DeviceType)
  ]
}
Fields
plannableLocationIds[]

string (int64 format)

Required. IDs of plannable locations to target.

Plannable locations can be retrieved using the reachForecast.retrievePlannableLocations method.
ageRange

enum (PlannableAgeRange)

Optional. The age range to target.
genders[]

enum (Gender)

Optional. The gender options to target.
devices[]

enum (DeviceType)

Optional. The devices to target.

CampaignDuration

The duration of the reach plan.

JSON representation 
{

  // Union field duration can be only one of the following:
  "durationDays": integer,
  "dateRange": {
    object (DateRange)
  }
  // End of list of possible types for union field duration.
}
Fields
Union field duration. Choice of campaign duration. duration can be only one of the following:
durationDays

integer

Required. The number of days the plan covers.
dateRange

object (DateRange)

Required. The date range the plan covers.

PlannedProduct

Configuration for a specific product in the plan.

JSON representation 
{
  "plannableProductCode": string,
  "budgetMicros": string,
  "advancedProductTargeting": {
    object (AdvancedProductTargeting)
  }
}
Fields
plannableProductCode

string

Required. The code for the product, e.g. "VIDEO_REACH_CAMPAIGN".
budgetMicros

string (int64 format)

Required. The budget for this product in micros.
advancedProductTargeting

object (AdvancedProductTargeting)

Optional. Optional line item level targeting overrides.

AdvancedProductTargeting

Product-specific targeting overrides.

JSON representation 
{
  "surfaceTargetingSettings": {
    object (SurfaceTargetingSettings)
  },
  "targetFrequency": {
    object (TargetFrequency)
  },
  "frequencyCap": {
    object (FrequencyCap)
  },
  "ageRange": enum (PlannableAgeRange),
  "genders": [
    enum (Gender)
  ],
  "devices": [
    enum (DeviceType)
  ],
  "userInterestIds": [
    string
  ],
  "userListIds": [
    string
  ],
  "youtubeSelectSettings": {
    object (YouTubeSelectSettings)
  },
  "dateRange": {
    object (DateRange)
  },
  "plannableLocationIds": [
    string
  ],
  "network": enum (PlannableNetwork)
}
Fields
surfaceTargetingSettings

object (SurfaceTargetingSettings)

Optional. Plannable surfaces to target.
targetFrequency

object (TargetFrequency)

Optional. The average number of times the ads will show to the same person over a certain period of time.
frequencyCap

object (FrequencyCap)

Optional. The frequency cap for the specific product.
ageRange

enum (PlannableAgeRange)

Optional. The age range to target.
genders[]

enum (Gender)

Optional. The gender options to target.
devices[]

enum (DeviceType)

Optional. The devices to target.
userInterestIds[]

string

Optional. The user interest IDs to target.

Plannable user interests can be retrieved using the reachForecast.retrievePlannableUserInterests method.
userListIds[]

string

Optional. The user list IDs to target.

Plannable user lists can be retrieved using the reachForecast.retrievePlannableUserInterests method.
youtubeSelectSettings

object (YouTubeSelectSettings)

Optional. YouTube Select settings.
dateRange

object (DateRange)

Optional. The date range to target.
plannableLocationIds[]

string (int64 format)

Optional. Plannable location IDs to target.
network

enum (PlannableNetwork)

Optional. The network to target.

SurfaceTargetingSettings

Surface targeting selection.

JSON representation 
{
  "surfaces": [
    enum (PlannableSurface)
  ]
}
Fields
surfaces[]

enum (PlannableSurface)

Optional. The surfaces to target.

YouTubeSelectSettings

Settings for YouTube Select Lineups.

JSON representation 
{
  "lineupId": string
}
Fields
lineupId

string (int64 format)

Optional. The ID of the YouTube Select Lineup.

OnTargetAudienceMetrics

Estimated audience sizes for a targeted geography.

JSON representation 
{
  "youtubeAudienceSize": string,
  "censusAudienceSize": string
}
Fields
youtubeAudienceSize

string (int64 format)

Estimated size of the YouTube audience.
censusAudienceSize

string (int64 format)

Size of the audience based on the census data of the targeted geography.

ReachCurve

The generated reach curve.

JSON representation 
{
  "reachForecasts": [
    {
      object (ReachForecast)
    }
  ]
}
Fields
reachForecasts[]

object (ReachForecast)

Points along the curve, ordered by cost.

ReachForecast

A single point in the reach curve.

JSON representation 
{
  "costMicros": string,
  "plannedProductReachForecasts": [
    {
      object (PlannedProductReachForecast)
    }
  ],
  "forecast": {
    object (PlannedProductForecast)
  }
}
Fields
costMicros

string (int64 format)

Total cost for this point in micros.
plannedProductReachForecasts[]

object (PlannedProductReachForecast)

Breakdown for individual products at this cost point.
forecast

object (PlannedProductForecast)

Aggregate forecast for the entire plan.

PlannedProductReachForecast

Performance forecast for a specific product.

JSON representation 
{
  "costMicros": string,
  "plannableProductCode": string,
  "plannedProductForecast": {
    object (PlannedProductForecast)
  }
}
Fields
costMicros

string (int64 format)

The cost in micros for this product.
plannableProductCode

string

The code for the product.
plannedProductForecast

object (PlannedProductForecast)

Performance metrics for the product.

PlannedProductForecast

Performance metrics for a forecast point.

JSON representation 
{
  "onTargetReach": string,
  "onTargetImpressions": string,
  "trueviewViews": string,
  "totalReach": string,
  "totalImpressions": string,
  "viewableImpressions": string,
  "onTargetCoviewReach": string,
  "totalCoviewReach": string,
  "onTargetCoviewImpressions": string,
  "totalCoviewImpressions": string
}
Fields
onTargetReach

string (int64 format)

Number of unique people reached that match the on-target definition.
onTargetImpressions

string (int64 format)

Number of on-target impressions.
trueviewViews

string (int64 format)

Number of TrueView views.
totalReach

string (int64 format)

Total number of unique people reached.
totalImpressions

string (int64 format)

Total number of impressions.
viewableImpressions

string (int64 format)

Number of viewable impressions.
onTargetCoviewReach

string (int64 format)

Number of unique people reached that match the on-target definition including co-viewers.
totalCoviewReach

string (int64 format)

Total number of unique people reached including co-viewers.
onTargetCoviewImpressions

string (int64 format)

Number of on-target impressions including co-viewers.
totalCoviewImpressions

string (int64 format)

Total number of impressions including co-viewers.