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

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/v7/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)
    }
  ],
  "currencyCode": string,
  "cookieFrequencyCap": integer,
  "minEffectiveFrequency": integer
}
Fields
campaignDuration

object (CampaignDuration)

Required. Campaign duration.

cookieFrequencyCapSetting

object (FrequencyCap)

Desired cookie frequency cap that will 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, 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.

currencyCode

string

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

cookieFrequencyCap

integer

Desired cookie frequency cap that will 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.

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
{
  "durationInDays": integer
}
Fields
durationInDays

integer

The duration value in days.

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.

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. If not specified, targets all age ranges.

genders[]

object (GenderInfo)

Targeted genders. If not specified, targets all genders.

devices[]

object (DeviceInfo)

Targeted devices. If not specified, targets all applicable devices. Applicable devices vary by product and region and can be obtained from v4.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 v4.listPlannableProducts.

plannableLocationId

string

Required. The ID of the selected location. Plannable locations ID can be obtained from v4.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. E.g. Trueview, Bumper To list the available plannable product codes use v4.listPlannableProducts.

budgetMicros

string (int64 format)

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

OnTargetAudienceMetrics

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

  • Location
  • PlannableAgeRange
  • Gender
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
{
  "onTargetReach": string,
  "totalReach": string,
  "onTargetImpressions": string,
  "totalImpressions": string,
  "viewableImpressions": string
}
Fields
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.

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 v4.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
}
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.