Method: customers.generateReachForecast

Generates a reach forecast for a given targeting / product mix.

List of thrown errors: AuthenticationError AuthorizationError FieldError HeaderError InternalError QuotaError RangeError ReachPlanError RequestError

HTTP request

POST https://googleads.googleapis.com/v17/customers/{customerId}:generateReachForecast

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
customerId

string

Required. The ID of the customer.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "campaignDuration": {
    object (CampaignDuration)
  },
  "cookieFrequencyCapSetting": {
    object (FrequencyCap)
  },
  "targeting": {
    object (Targeting)
  },
  "plannedProducts": [
    {
      object (PlannedProduct)
    }
  ],
  "forecastMetricOptions": {
    object (ForecastMetricOptions)
  },
  "currencyCode": string,
  "cookieFrequencyCap": integer,
  "minEffectiveFrequency": integer,
  "effectiveFrequencyLimit": {
    object (EffectiveFrequencyLimit)
  },
  "customerReachGroup": string
}
Fields
campaignDuration

object (CampaignDuration)

Required. Campaign duration.
cookieFrequencyCapSetting

object (FrequencyCap)

Chosen cookie frequency cap to be applied to each planned product. This is equivalent to the frequency cap exposed in Google Ads when creating a campaign, it represents the maximum number of times an ad can be shown to the same user during a specified time interval. If not specified, a default of 0 (no cap) is applied.

This field replaces the deprecated cookieFrequencyCap field.
targeting

object (Targeting)

The targeting to be applied to all products selected in the product mix.

This is planned targeting: execution details might vary based on the advertising product, consult an implementation specialist.

See specific metrics for details on how targeting affects them.
plannedProducts[]

object (PlannedProduct)

Required. The products to be forecast. The max number of allowed planned products is 15.
forecastMetricOptions

object (ForecastMetricOptions)

Controls the forecast metrics returned in the response.
currencyCode

string

The currency code. Three-character ISO 4217 currency code.
cookieFrequencyCap

integer

Chosen cookie frequency cap to be applied to each planned product. This is equivalent to the frequency cap exposed in Google Ads when creating a campaign, it represents the maximum number of times an ad can be shown to the same user. If not specified, no cap is applied.

This field is deprecated in v4 and will eventually be removed. Use cookieFrequencyCapSetting instead.
minEffectiveFrequency

integer

Chosen minimum effective frequency (the number of times a person was exposed to the ad) for the reported reach metrics [1-10]. This won't affect the targeting, but just the reporting. If not specified, a default of 1 is applied.

This field cannot be combined with the effectiveFrequencyLimit field.
effectiveFrequencyLimit

object (EffectiveFrequencyLimit)

The highest minimum effective frequency (the number of times a person was exposed to the ad) value [1-10] to include in Forecast.effective_frequency_breakdowns. If not specified, Forecast.effective_frequency_breakdowns will not be provided.

The effective frequency value provided here will also be used as the minimum effective frequency for the reported reach metrics.

This field cannot be combined with the minEffectiveFrequency field.
customerReachGroup

string

The name of the customer being planned for. This is a user-defined value.

Response body

Response message containing the generated reach curve.

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

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

object (OnTargetAudienceMetrics)

Reference on target audiences for this curve.
reachCurve

object (ReachCurve)

The generated reach curve for the planned product mix.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/adwords

For more information, see the OAuth 2.0 Overview.

CampaignDuration

The duration of a planned campaign.

JSON representation 
{
  "dateRange": {
    object (DateRange)
  },
  "durationInDays": integer
}
Fields
dateRange

object (DateRange)

Date range of the campaign. Dates are in the yyyy-mm-dd format and inclusive. The end date must be < 1 year in the future and the date range must be <= 92 days long.

This field cannot be combined with the durationInDays field.
durationInDays

integer

The duration value in days.

This field cannot be combined with the dateRange field.

FrequencyCap

A rule specifying the maximum number of times an ad can be shown to a user over a particular time period.

JSON representation 
{
  "impressions": integer,
  "timeUnit": enum (FrequencyCapTimeUnit)
}
Fields
impressions

integer

Required. The number of impressions, inclusive.
timeUnit

enum (FrequencyCapTimeUnit)

Required. The type of time unit.

EffectiveFrequencyLimit

Effective frequency limit.

JSON representation 
{
  "effectiveFrequencyBreakdownLimit": integer
}
Fields
effectiveFrequencyBreakdownLimit

integer

The highest effective frequency value to include in Forecast.effective_frequency_breakdowns. This field supports frequencies 1-10, inclusive.

Targeting

The targeting for which traffic metrics will be reported.

JSON representation 
{
  "plannableLocationIds": [
    string
  ],
  "ageRange": enum (ReachPlanAgeRange),
  "genders": [
    {
      object (GenderInfo)
    }
  ],
  "devices": [
    {
      object (DeviceInfo)
    }
  ],
  "network": enum (ReachPlanNetwork),
  "audienceTargeting": {
    object (AudienceTargeting)
  },
  "plannableLocationId": string
}
Fields
plannableLocationIds[]

string

The list of plannable location IDs to target with this forecast.

If more than one ID is provided, all IDs must have the same parentCountryId. Planning for more than parent_county is not supported. Plannable location IDs and their parentCountryId can be obtained from ReachPlanService.ListPlannableLocations.

Requests must set either this field or plannableLocationId.
ageRange

enum (ReachPlanAgeRange)

Targeted age range. An unset value is equivalent to targeting all ages.
genders[]

object (GenderInfo)

Targeted genders. An unset value is equivalent to targeting MALE and FEMALE.
devices[]

object (DeviceInfo)

Targeted devices. If not specified, targets all applicable devices. Applicable devices vary by product and region and can be obtained from ReachPlanService.ListPlannableProducts.
network

enum (ReachPlanNetwork)

Targetable network for the ad product. If not specified, targets all applicable networks. Applicable networks vary by product and region and can be obtained from ReachPlanService.ListPlannableProducts.
audienceTargeting

object (AudienceTargeting)

Targeted audiences. If not specified, does not target any specific audience.
plannableLocationId

string

The ID of the selected location. Plannable location IDs can be obtained from ReachPlanService.ListPlannableLocations.

Requests must set either this field or plannableLocationIds.

This field is deprecated as of V12 and will be removed in a future release. Use plannableLocationIds instead.

AudienceTargeting

Audience targeting for reach forecast.

JSON representation 
{
  "userInterest": [
    {
      object (UserInterestInfo)
    }
  ]
}
Fields
userInterest[]

object (UserInterestInfo)

List of audiences based on user interests to be targeted.

PlannedProduct

A product being planned for reach.

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

object (AdvancedProductTargeting)

Targeting settings for the selected product. To list the available targeting for each product use ReachPlanService.ListPlannableProducts.
plannableProductCode

string

Required. Selected product for planning. The code associated with the ad product (for example: Trueview, Bumper). To list the available plannable product codes use ReachPlanService.ListPlannableProducts.
budgetMicros

string (int64 format)

Required. Maximum budget allocation in micros for the selected product. The value is specified in the selected planning currencyCode. For example: 1 000 000$ = 1 000 000 000 000 micros.

AdvancedProductTargeting

Advanced targeting settings for products.

JSON representation 
{
  "surfaceTargetingSettings": {
    object (SurfaceTargeting)
  },
  "targetFrequencySettings": {
    object (TargetFrequencySettings)
  },

  // Union field advanced_targeting can be only one of the following:
  "youtubeSelectSettings": {
    object (YouTubeSelectSettings)
  }
  // End of list of possible types for union field advanced_targeting.
}
Fields
surfaceTargetingSettings

object (SurfaceTargeting)

Surface targeting settings for this product.
targetFrequencySettings

object (TargetFrequencySettings)

Settings for a Target frequency campaign. Must be set when selecting the TARGET_FREQUENCY product.

See https://support.google.com/google-ads/answer/12400225 for more information about Target Frequency campaigns.
Union field advanced_targeting. Targeting options for this product. advanced_targeting can be only one of the following:
youtubeSelectSettings

object (YouTubeSelectSettings)

Settings for YouTube Select targeting.

TargetFrequencySettings

Target Frequency settings for a supported product.

JSON representation 
{
  "timeUnit": enum (TargetFrequencyTimeUnit),
  "targetFrequency": integer
}
Fields
timeUnit

enum (TargetFrequencyTimeUnit)

Required. The time unit used to describe the time frame for targetFrequency.
targetFrequency

integer

Required. The target frequency goal per selected time unit.

YouTubeSelectSettings

Request settings for YouTube Select Lineups

JSON representation 
{
  "lineupId": string
}
Fields
lineupId

string (int64 format)

Lineup for YouTube Select Targeting.

ForecastMetricOptions

Controls forecast metrics to return.

JSON representation 
{
  "includeCoview": boolean
}
Fields
includeCoview

boolean

Indicates whether to include co-view metrics in the response forecast.

OnTargetAudienceMetrics

Audience metrics for the planned products. These metrics consider the following targeting dimensions:

  • Location
  • PlannableAgeRange
  • Gender
  • AudienceTargeting (only for youtubeAudienceSize)
JSON representation 
{
  "youtubeAudienceSize": string,
  "censusAudienceSize": string
}
Fields
youtubeAudienceSize

string (int64 format)

Reference audience size matching the considered targeting for YouTube.
censusAudienceSize

string (int64 format)

Reference audience size matching the considered targeting for Census.

ReachCurve

The reach curve for the planned products.

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

object (ReachForecast)

All points on the reach curve.

ReachForecast

A point on reach curve.

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

string (int64 format)

The cost in micros.
forecast

object (Forecast)

Forecasted traffic metrics for this point.
plannedProductReachForecasts[]

object (PlannedProductReachForecast)

The forecasted allocation and traffic metrics for each planned product at this point on the reach curve.

Forecast

Forecasted traffic metrics for the planned products and targeting.

JSON representation 
{
  "effectiveFrequencyBreakdowns": [
    {
      object (EffectiveFrequencyBreakdown)
    }
  ],
  "onTargetReach": string,
  "totalReach": string,
  "onTargetImpressions": string,
  "totalImpressions": string,
  "viewableImpressions": string,
  "onTargetCoviewReach": string,
  "totalCoviewReach": string,
  "onTargetCoviewImpressions": string,
  "totalCoviewImpressions": string,
  "views": string
}
Fields
effectiveFrequencyBreakdowns[]

object (EffectiveFrequencyBreakdown)

A list of effective frequency forecasts. The list is ordered starting with 1+ and ending with the value set in GenerateReachForecastRequest.effective_frequency_limit. If no effectiveFrequencyLimit was set, this list will be empty.
onTargetReach

string (int64 format)

Number of unique people reached at least GenerateReachForecastRequest.min_effective_frequency or GenerateReachForecastRequest.effective_frequency_limit times that exactly matches the Targeting.

Note that a minimum number of unique people must be reached in order for data to be reported. If the minimum number is not met, the onTargetReach value will be rounded to 0.
totalReach

string (int64 format)

Total number of unique people reached at least GenerateReachForecastRequest.min_effective_frequency or GenerateReachForecastRequest.effective_frequency_limit times. This includes people that may fall outside the specified Targeting.

Note that a minimum number of unique people must be reached in order for data to be reported. If the minimum number is not met, the totalReach value will be rounded to 0.
onTargetImpressions

string (int64 format)

Number of ad impressions that exactly matches the Targeting.
totalImpressions

string (int64 format)

Total number of ad impressions. This includes impressions that may fall outside the specified Targeting, due to insufficient information on signed-in users.
viewableImpressions

string (int64 format)

Number of times the ad's impressions were considered viewable. See https://support.google.com/google-ads/answer/7029393 for more information about what makes an ad viewable and how viewability is measured.
onTargetCoviewReach

string (int64 format)

Number of unique people reached that exactly matches the Targeting including co-viewers.
totalCoviewReach

string (int64 format)

Number of unique people reached including co-viewers. This includes people that may fall outside the specified Targeting.
onTargetCoviewImpressions

string (int64 format)

Number of ad impressions that exactly matches the Targeting including co-viewers.
totalCoviewImpressions

string (int64 format)

Total number of ad impressions including co-viewers. This includes impressions that may fall outside the specified Targeting, due to insufficient information on signed-in users.
views

string (int64 format)

Number of ad views forecasted for the specified product and targeting. A view is counted when a viewer views a larger portion or the entirety of an ad beyond an impression.

See https://support.google.com/google-ads/answer/2375431 for more information on views.

EffectiveFrequencyBreakdown

A breakdown of the number of unique people reached at a given effective frequency.

JSON representation 
{
  "effectiveFrequency": integer,
  "onTargetReach": string,
  "totalReach": string,
  "effectiveCoviewReach": string,
  "onTargetEffectiveCoviewReach": string
}
Fields
effectiveFrequency

integer

The effective frequency [1-10].
onTargetReach

string (int64 format)

The number of unique people reached at least effectiveFrequency times that exactly matches the Targeting.

Note that a minimum number of unique people must be reached in order for data to be reported. If the minimum number is not met, the onTargetReach value will be rounded to 0.
totalReach

string (int64 format)

Total number of unique people reached at least effectiveFrequency times. This includes people that may fall outside the specified Targeting.

Note that a minimum number of unique people must be reached in order for data to be reported. If the minimum number is not met, the totalReach value will be rounded to 0.
effectiveCoviewReach

string (int64 format)

The number of users (including co-viewing users) reached for the associated effectiveFrequency value.
onTargetEffectiveCoviewReach

string (int64 format)

The number of users (including co-viewing users) reached for the associated effectiveFrequency value within the specified plan demographic.

PlannedProductReachForecast

The forecasted allocation and traffic metrics for a specific product at a point on the reach curve.

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

string

Selected product for planning. The product codes returned are within the set of the ones returned by ListPlannableProducts when using the same location ID.
costMicros

string (int64 format)

The cost in micros. This may differ from the product's input allocation if one or more planned products cannot fulfill the budget because of limited inventory.
plannedProductForecast

object (PlannedProductForecast)

Forecasted traffic metrics for this product.

PlannedProductForecast

Forecasted traffic metrics for a planned product.

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

string (int64 format)

Number of unique people reached that exactly matches the Targeting.

Note that a minimum number of unique people must be reached in order for data to be reported. If the minimum number is not met, the onTargetReach value will be rounded to 0.
totalReach

string (int64 format)

Number of unique people reached. This includes people that may fall outside the specified Targeting.

Note that a minimum number of unique people must be reached in order for data to be reported. If the minimum number is not met, the totalReach value will be rounded to 0.
onTargetImpressions

string (int64 format)

Number of ad impressions that exactly matches the Targeting.
totalImpressions

string (int64 format)

Total number of ad impressions. This includes impressions that may fall outside the specified Targeting, due to insufficient information on signed-in users.
viewableImpressions

string (int64 format)

Number of times the ad's impressions were considered viewable. See https://support.google.com/google-ads/answer/7029393 for more information about what makes an ad viewable and how viewability is measured.
onTargetCoviewReach

string (int64 format)

Number of unique people reached that exactly matches the Targeting including co-viewers.
totalCoviewReach

string (int64 format)

Number of unique people reached including co-viewers. This includes people that may fall outside the specified Targeting.
onTargetCoviewImpressions

string (int64 format)

Number of ad impressions that exactly matches the Targeting including co-viewers.
totalCoviewImpressions

string (int64 format)

Total number of ad impressions including co-viewers. This includes impressions that may fall outside the specified Targeting, due to insufficient information on signed-in users.
averageFrequency

number

The number of times per selected time unit a user will see an ad, averaged over the number of time units in the forecast length. This field will only be populated for a Target Frequency campaign.

See https://support.google.com/google-ads/answer/12400225 for more information about Target Frequency campaigns.
views

string (int64 format)

Number of ad views forecasted for the specified product and targeting. A view is counted when a viewer views a larger portion or the entirety of an ad beyond an impression.

See https://support.google.com/google-ads/answer/2375431 for more information on views.