Caution: You are viewing documentation for the API's REST interface. Most of our official client libraries use gRPC. See the REST Introduction for details.

Method: customers.generateReachForecast

Stay organized with collections Save and categorize content based on your preferences.

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/v11/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)
  }
}
Fields
campaignDuration

object (CampaignDuration)

Required. Campaign duration.

cookieFrequencyCapSetting

object (FrequencyCap)

Desired 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, please 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

Desired 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. Please use cookieFrequencyCapSetting instead.

minEffectiveFrequency

integer

Desired 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.

Response body

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

Response message containing the generated reach curve.

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
{
  "ageRange": enum (ReachPlanAgeRange),
  "genders": [
    {
      object (GenderInfo)
    }
  ],
  "devices": [
    {
      object (DeviceInfo)
    }
  ],
  "network": enum (ReachPlanNetwork),
  "plannableLocationId": string
}
Fields
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.

plannableLocationId

string

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

PlannedProduct

A product being planned for reach.

JSON representation
{
  "plannableProductCode": string,
  "budgetMicros": string
}
Fields
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.

ForecastMetricOptions

Controls forecast metrics to return.

<
JSON representation