Method: customers.generateReachForecast

针对指定定位条件 / 产品组合生成覆盖面预测。

抛出的错误的列表：AuthenticationError AuthorizationError FieldError HeaderError InternalError QuotaError RangeError ReachPlanError RequestError

HTTP 请求

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

网址采用 gRPC 转码语法。

路径参数

参数
customerId

string

必需。客户的 ID。

请求正文

请求正文中包含结构如下的数据：

JSON 表示法 
{
  "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
}
字段
campaignDuration

object (CampaignDuration)

必需。广告系列投放时长。
cookieFrequencyCapSetting

object (FrequencyCap)

选择要应用到每个计划发布的产品的 Cookie 频次上限。这相当于制作广告系列时 Google Ads 中显示的频次上限，表示在指定时间间隔内，广告可向同一用户展示的最大次数。如果未指定，则系统会应用默认值 0（无上限）。

此字段取代了已弃用的 cookieFrequencyCap 字段。
targeting

object (Targeting)

要应用于产品组合中选择的所有产品的定位条件。

这是计划的定位：执行详情可能会因广告产品而异，请咨询实施专家。

请查看具体指标，详细了解定位条件对这些指标有何影响。
plannedProducts[]

object (PlannedProduct)

必需。要预测的产品。计划允许的产品数量上限为 15。
forecastMetricOptions

object (ForecastMetricOptions)

控制响应中返回的预测指标。
currencyCode

string

货币代码。三个字符的 ISO 4217 货币代码。
cookieFrequencyCap

integer

选择要应用到每个计划发布的产品的 Cookie 频次上限。这相当于制作广告系列时 Google Ads 中显示的频次上限，表示广告可向同一用户展示的最大次数。如果未指定，则不应用任何上限。

此字段在 v4 中已弃用，最终将被移除。请改用 cookieFrequencyCapSetting。
minEffectiveFrequency

integer

为报告的覆盖面指标 [1-10] 选择最低有效频次（用户看到相应广告的次数）。这不会影响定位条件，只会影响报表。如果未指定，则系统会应用默认值 1。

此字段不能与 validFrequencyLimit 字段结合使用。
effectiveFrequencyLimit

object (EffectiveFrequencyLimit)

要包含在 Forecast.effective_frequency_breakdowns 中的最高最低有效频次（用户看到广告的次数）值 [1-10]。如果未指定，则不会提供 Forecast.effective_frequency_breakdowns。

此处提供的有效频次值也将用作所报告覆盖面指标的最小有效频次。

此字段不能与 minEffectiveFrequency 字段结合使用。
customerReachGroup

string

目标客户的名称。这是用户定义的值。

响应正文

包含生成的覆盖面曲线的响应消息。

如果成功，响应正文将包含结构如下的数据：

JSON 表示法 
{
  "onTargetAudienceMetrics": {
    object (OnTargetAudienceMetrics)
  },
  "reachCurve": {
    object (ReachCurve)
  }
}
字段
onTargetAudienceMetrics

object (OnTargetAudienceMetrics)

此曲线的目标受众群体的参考文件。
reachCurve

object (ReachCurve)

为计划的产品组合生成的覆盖面曲线。

授权范围

需要以下 OAuth 范围：

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

如需了解详情，请参阅 OAuth 2.0 概览。

CampaignDuration

所规划广告系列的持续时间。

JSON 表示法 
{
  "dateRange": {
    object (DateRange)
  },
  "durationInDays": integer
}
字段
dateRange

object (DateRange)

广告系列的日期范围。日期采用 yyyy-mm-dd 格式（含边界值）。结束日期必须 <1 年后，并且日期范围必须小于等于 92 天。

此字段不能与 durationInDays 字段结合使用。
durationInDays

integer

时长值（以天为单位）。

此字段不能与 dateRange 字段结合使用。

FrequencyCap

指定在特定时间段内广告可向用户展示的最大次数的规则。

JSON 表示法 
{
  "impressions": integer,
  "timeUnit": enum (FrequencyCapTimeUnit)
}
字段
impressions

integer

必需。展示次数（含）。
timeUnit

enum (FrequencyCapTimeUnit)

必需。时间单位的类型。

EffectiveFrequencyLimit

有效频次限制。

JSON 表示法 
{
  "effectiveFrequencyBreakdownLimit": integer
}
字段
effectiveFrequencyBreakdownLimit

integer

要包含在 Forecast.effective_frequency_breakdowns 中的最高有效频次值。此字段支持频率 1-10（含）。

定位

要报告流量指标的定位条件。

JSON 表示法 
{
  "plannableLocationIds": [
    string
  ],
  "ageRange": enum (ReachPlanAgeRange),
  "genders": [
    {
      object (GenderInfo)
    }
  ],
  "devices": [
    {
      object (DeviceInfo)
    }
  ],
  "network": enum (ReachPlanNetwork),
  "audienceTargeting": {
    object (AudienceTargeting)
  },
  "plannableLocationId": string
}
字段
plannableLocationIds[]

string

要使用此预测定位的可规划地理位置 ID 的列表。

如果提供了多个 ID，则所有 ID 都必须具有相同的 parentCountryId。不支持规划超过 parent_county 个区域。可从 ReachPlanService.ListPlannableLocations 获取可规划地理位置 ID 及其 parentCountryId。

请求必须设置此字段或 plannableLocationId。
ageRange

enum (ReachPlanAgeRange)

定位的年龄段。如果未设置值，就相当于定位所有年龄。
genders[]

object (GenderInfo)

定位的性别。如果未设置值，就相当于定位 MALE 和 FEMALE。
devices[]

object (DeviceInfo)

定位的设备。如果未指定，则会定位所有适用的设备。适用设备因产品和地区而异，可从 ReachPlanService.ListPlannableProducts 获取。
network

enum (ReachPlanNetwork)

广告产品的可定位的广告网络。如果未指定，则会定位所有适用的广告网络。适用的广告网络因产品和区域而异，您可以通过 ReachPlanService.ListPlannableProducts 获取。
audienceTargeting

object (AudienceTargeting)

定位的受众群体。如果未指定，则不定位任何特定受众群体。
plannableLocationId

string

所选地理位置的 ID。可从 ReachPlanService.ListPlannableLocations 获取可规划地理位置 ID。

请求必须设置此字段或 plannableLocationIds。

此字段自 V12 起已弃用，并将在未来的版本中移除。请改用 plannableLocationIds。

AudienceTargeting

使用受众群体定位进行预测。

JSON 表示法 
{
  "userInterest": [
    {
      object (UserInterestInfo)
    }
  ]
}
字段
userInterest[]

object (UserInterestInfo)

根据用户兴趣定位的受众群体名单。

PlannedProduct

计划扩大覆盖面的产品。

JSON 表示法 
{
  "advancedProductTargeting": {
    object (AdvancedProductTargeting)
  },
  "plannableProductCode": string,
  "budgetMicros": string
}
字段
advancedProductTargeting

object (AdvancedProductTargeting)

所选产品的定位设置。要列出每个产品的可用定位条件，请使用 ReachPlanService.ListPlannableProducts。
plannableProductCode

string

必需。用于规划的选定产品。与广告产品（例如 TrueView、导视广告）关联的代码。如需列出可用的可规划产品代码，请使用 ReachPlanService.ListPlannableProducts。
budgetMicros

string (int64 format)

必需。为所选产品分配的最高预算（以微单位表示）。该值以所选的计划 currencyCode 指定。例如：1 000 000$ = 1 000 000 000 000 微单位。

AdvancedProductTargeting

产品的高级定位设置。

JSON 表示法 
{
  "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.
}
字段
surfaceTargetingSettings

object (SurfaceTargeting)

此产品的界面定位设置。
targetFrequencySettings

object (TargetFrequencySettings)

设置了目标频次的广告系列的设置。选择 TARGET_FREQUENCY 产品时必须设置。

如需详细了解设置了目标频次的广告系列，请参阅 https://support.google.com/google-ads/answer/12400225。
联合字段 advanced_targeting。此产品的定位选项。advanced_targeting 只能是下列其中一项：
youtubeSelectSettings

object (YouTubeSelectSettings)

YouTube 优选定位设置。

TargetFrequencySettings

受支持产品的“目标频次”设置。

JSON 表示法 
{
  "timeUnit": enum (TargetFrequencyTimeUnit),
  "targetFrequency": integer
}
字段
timeUnit

enum (TargetFrequencyTimeUnit)

必需。用于描述 targetFrequency 的时间范围的时间单位。
targetFrequency

integer

必需。每个所选时间单位的目标频次目标。

YouTubeSelectSettings

为 YouTube 优选频道组申请设置

JSON 表示法 
{
  "lineupId": string
}
字段
lineupId

string (int64 format)

YouTube 优选定位对应的频道组。

ForecastMetricOptions

控制要返回的预测指标。

JSON 表示法 
{
  "includeCoview": boolean
}
字段
includeCoview

boolean

指明是否在回应预测中包含同看指标。

OnTargetAudienceMetrics

所规划产品的受众群体指标。这些指标会考虑以下定位维度：

  • 位置
  • PlannableAgeRange
  • 性别
  • AudienceTargeting（仅适用于 youtubeAudienceSize）
JSON 表示法 
{
  "youtubeAudienceSize": string,
  "censusAudienceSize": string
}
字段
youtubeAudienceSize

string (int64 format)

参考受众群体规模（与考虑使用的 YouTube 定位条件相符）。
censusAudienceSize

string (int64 format)

参考受众群体规模，与考虑的人口普查定位条件相符。

ReachCurve

所规划产品的覆盖面曲线。

JSON 表示法 
{
  "reachForecasts": [
    {
      object (ReachForecast)
    }
  ]
}
字段
reachForecasts[]

object (ReachForecast)

覆盖面曲线上的所有点。

ReachForecast

覆盖面曲线上的一个点。

JSON 表示法 
{
  "costMicros": string,
  "forecast": {
    object (Forecast)
  },
  "plannedProductReachForecasts": [
    {
      object (PlannedProductReachForecast)
    }
  ]
}
字段
costMicros

string (int64 format)

以微单位表示的费用。
forecast

object (Forecast)

此时间点的预测流量指标。
plannedProductReachForecasts[]

object (PlannedProductReachForecast)

每个计划产品在覆盖面曲线上此点的预测分配和流量指标。

预测

所规划产品和定位条件的预测流量指标。

JSON 表示法 
{
  "effectiveFrequencyBreakdowns": [
    {
      object (EffectiveFrequencyBreakdown)
    }
  ],
  "onTargetReach": string,
  "totalReach": string,
  "onTargetImpressions": string,
  "totalImpressions": string,
  "viewableImpressions": string,
  "onTargetCoviewReach": string,
  "totalCoviewReach": string,
  "onTargetCoviewImpressions": string,
  "totalCoviewImpressions": string,
  "views": string
}
字段
effectiveFrequencyBreakdowns[]

object (EffectiveFrequencyBreakdown)

有效频次预测列表。该列表从 1+ 开始排序，并以 GenerateReachForecastRequest.effective_frequency_limit 中设置的值结尾。如果未设置 effectiveFrequencyLimit，则此列表将为空。
onTargetReach

string (int64 format)

覆盖至少 GenerateReachForecastRequest.min_effective_frequency 或 GenerateReachForecastRequest.effective_frequency_limit 时间且与定位条件完全匹配的唯一身份用户的数量。

请注意，要报告相关数据，必须达到最低数量要求。否则，onTargetReach 值将四舍五入为 0。
totalReach

string (int64 format)

至少达到 GenerateReachForecastRequest.min_effective_frequency 或 GenerateReachForecastRequest.effective_frequency_limit 次数的唯一身份用户总数。这包括可能不属于指定定位条件的用户。

请注意，要报告相关数据，必须达到最低数量要求。如果未达到最小数量，totalReach 值将四舍五入为 0。
onTargetImpressions

string (int64 format)

与定位条件完全匹配的广告展示次数。
totalImpressions

string (int64 format)

广告总展示次数。这包括因已登录用户的信息不足而导致超出指定定位条件的展示。
viewableImpressions

string (int64 format)

广告展示被视为可见的次数。如需详细了解如何让广告可见以及如何衡量可见度，请访问 https://support.google.com/google-ads/answer/7029393。
onTargetCoviewReach

string (int64 format)

覆盖的与定位条件完全匹配的唯一身份用户数（包括同看人数）。
totalCoviewReach

string (int64 format)

覆盖的唯一身份用户数（包括同看人数）。这包括可能不属于指定定位条件的用户。
onTargetCoviewImpressions

string (int64 format)

与定位条件完全匹配的广告展示次数（包括同看者）。
totalCoviewImpressions

string (int64 format)

广告总展示次数（包括同看者）。这包括因已登录用户的信息不足而导致超出指定定位条件的展示。
views

string (int64 format)

针对指定产品和定位条件预测的广告浏览次数。当观看者观看广告的大部分内容或全部内容超出展示次数时，就计为一次观看。

如需详细了解数据视图，请参阅 https://support.google.com/google-ads/answer/2375431。

EffectiveFrequencyBreakdown

在指定的有效频次下覆盖的唯一身份用户数细分。

JSON 表示法 
{
  "effectiveFrequency": integer,
  "onTargetReach": string,
  "totalReach": string,
  "effectiveCoviewReach": string,
  "onTargetEffectiveCoviewReach": string
}
字段
effectiveFrequency

integer

有效频率 [1-10]。
onTargetReach

string (int64 format)

至少在有效频次时段中覆盖的与定位条件完全匹配的唯一身份用户数。

请注意，要报告相关数据，必须达到最低数量要求。否则，onTargetReach 值将四舍五入为 0。
totalReach

string (int64 format)

至少覆盖有效频次时间的唯一身份用户总数。这包括可能不属于指定定位条件的用户。

请注意，要报告相关数据，必须达到最低数量要求。如果未达到最小数量，totalReach 值将四舍五入为 0。
effectiveCoviewReach

string (int64 format)

针对关联的 validFrequency 值所覆盖的用户数（包括同看用户）。
onTargetEffectiveCoviewReach

string (int64 format)

在指定方案的受众特征范围内，针对相关 validFrequency 值所覆盖的用户数（包括同看用户）。

PlannedProductReachForecast

特定产品在覆盖面曲线上某个点的预测分配和流量指标。

JSON 表示法 
{
  "plannableProductCode": string,
  "costMicros": string,
  "plannedProductForecast": {
    object (PlannedProductForecast)
  }
}
字段
plannableProductCode

string

用于规划的选定产品。返回的产品代码在 ListPlannableProducts 返回的产品代码集中（使用相同的地理位置 ID 时）。
costMicros

string (int64 format)

以微单位表示的费用。如果一个或多个计划中的产品因库存有限而无法用尽预算，那么此值可能与产品的输入分配不同。
plannedProductForecast

object (PlannedProductForecast)

此产品的预测流量指标。

PlannedProductForecast

所规划产品的预测流量指标。

JSON 表示法 
{
  "onTargetReach": string,
  "totalReach": string,
  "onTargetImpressions": string,
  "totalImpressions": string,
  "viewableImpressions": string,
  "onTargetCoviewReach": string,
  "totalCoviewReach": string,
  "onTargetCoviewImpressions": string,
  "totalCoviewImpressions": string,
  "averageFrequency": number,
  "views": string
}
字段
onTargetReach

string (int64 format)

覆盖的与定位条件完全匹配的唯一身份用户数。

请注意，要报告相关数据，必须达到最低数量要求。否则，onTargetReach 值将四舍五入为 0。
totalReach

string (int64 format)

覆盖的唯一身份用户数。这包括可能不属于指定定位条件的用户。

请注意，要报告相关数据，必须达到最低数量要求。如果未达到最小数量，totalReach 值将四舍五入为 0。
onTargetImpressions

string (int64 format)

与定位条件完全匹配的广告展示次数。
totalImpressions

string (int64 format)

广告总展示次数。这包括因已登录用户的信息不足而导致超出指定定位条件的展示。
viewableImpressions

string (int64 format)

广告展示被视为可见的次数。如需详细了解如何让广告可见以及如何衡量可见度，请访问 https://support.google.com/google-ads/answer/7029393。
onTargetCoviewReach

string (int64 format)

覆盖的与定位条件完全匹配的唯一身份用户数（包括同看人数）。
totalCoviewReach

string (int64 format)

覆盖的唯一身份用户数（包括同看人数）。这包括可能不属于指定定位条件的用户。
onTargetCoviewImpressions

string (int64 format)

与定位条件完全匹配的广告展示次数（包括同看者）。
totalCoviewImpressions

string (int64 format)

广告总展示次数（包括同看者）。这包括因已登录用户的信息不足而导致超出指定定位条件的展示。
averageFrequency

number

在每个选定时间单位内，用户看到一则广告的次数，此次数根据预测时长内的时间单位数计算得出。只有设置了目标频次的广告系列才需要填写此字段。

如需详细了解设置了目标频次的广告系列，请参阅 https://support.google.com/google-ads/answer/12400225。
views

string (int64 format)

针对指定产品和定位条件预测的广告浏览次数。当观看者观看广告的大部分内容或全部内容超出展示次数时，就计为一次观看。

如需详细了解数据视图，请参阅 https://support.google.com/google-ads/answer/2375431。