注意：您正在查看 API 的 REST 接口的文档。我们的大多数官方客户端库都使用 gRPC。如需了解详情，请参阅 REST 简介。

此页面由 Cloud Translation API 翻译。

Method: customers.generateReachForecast

HTTP 请求
路径参数
请求正文
- JSON 表示法
响应正文
- JSON 表示法
授权范围
CampaignDuration
- JSON 表示法
FrequencyCap
- JSON 表示法
EffectiveFrequencyLimit
- JSON 表示法
定位
- JSON 表示法
AudienceTargeting
- JSON 表示法
PlannedProduct
- JSON 表示法
AdvancedProductTargeting
- JSON 表示法
TargetFrequencySettings
- JSON 表示法
YouTubeSelectSettings
- JSON 表示法
ForecastMetricOptions
- JSON 表示法
OnTargetAudienceMetrics
- JSON 表示法
ReachCurve
- JSON 表示法
ReachForecast
- JSON 表示法
预测
- JSON 表示法
EffectiveFrequencyBreakdown（有效频率细分）
- JSON 表示法
PlannedProductReachForecast
- JSON 表示法
PlannedProductForecast
- JSON 表示法
试试看！

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

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

HTTP 请求

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

网址采用 gRPC 转码语法。

路径参数

参数

参数
`customerId`	`string` 必需。客户的 ID。

customerId

string

必需。客户的 ID。

请求正文

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

JSON 表示法

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)
  },
  "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)` 为计划的产品组合生成的覆盖面曲线。

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（含 yyyy-mm-dd）。结束日期必须在未来 1 年内，且日期范围不得超过 92 天。此字段不能与 durationInDays 字段结合使用。
`durationInDays`	`integer` 时长值（以天为单位）。该字段不能与 dateRange 字段结合使用。

dateRange

object (DateRange)

广告系列的日期范围。日期格式为 yyyy-mm-dd（含 yyyy-mm-dd）。结束日期必须在未来 1 年内，且日期范围不得超过 92 天。

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

durationInDays

integer

时长值（以天为单位）。

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

FrequencyCap

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

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

字段

字段
`impressions`	`integer` 必需。展示次数（含）。
`timeUnit`	`enum (FrequencyCapTimeUnit)` 必需。时间单位的类型。

impressions

integer

必需。展示次数（含）。

timeUnit

enum (FrequencyCapTimeUnit)

必需。时间单位的类型。

EffectiveFrequencyLimit

有效频次限制。

JSON 表示法
{ "effectiveFrequencyBreakdownLimit": integer }

字段

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

effectiveFrequencyBreakdownLimit

integer

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

定位

将报告哪些定位条件的流量指标。

JSON 表示法

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

{
  "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)` 基于要定位的用户兴趣的受众群体的列表。

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

object (AdvancedProductTargeting)

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

plannableProductCode

string

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

budgetMicros

string (int64 format)

必需。所选产品的预算分配上限（以微单位表示）。该值使用所选规划 currencyCode。例如：1 000 000$ = 1 000 000 000 000 微秒。

AdvancedProductTargeting

产品的高级定位设置。

JSON 表示法

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)
  },

  // 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)` 此产品的 Surface 定位设置。
`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` 必需。每个所选时间单位的目标频次目标。

timeUnit

enum (TargetFrequencyTimeUnit)

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

targetFrequency

integer

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

YouTubeSelectSettings

YouTube 优选频道组的请求设置

JSON 表示法
{ "lineupId": string }

字段

字段
`lineupId`	`string (int64 format)` 适用于 YouTube 优选定位的频道组。

lineupId

string (int64 format)

适用于 YouTube 优选定位的频道组。

ForecastMetricOptions

控制要返回的预测指标。

JSON 表示法
{ "includeCoview": boolean }

字段

字段
`includeCoview`	`boolean` 指明是否在响应预测中包含同看指标。

includeCoview

boolean

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

OnTargetAudienceMetrics

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

位置
PlannableAgeRange
性别
受众群体定位（仅适用于 youtubeAudienceSize）

JSON 表示法
{ "youtubeAudienceSize": string, "censusAudienceSize": string }

字段

字段
`youtubeAudienceSize`	`string (int64 format)` 与考虑的 YouTube 定位条件相符的参考受众群体规模。
`censusAudienceSize`	`string (int64 format)` 与考虑的人口普查定位条件相符的参考受众群体规模。

youtubeAudienceSize

string (int64 format)

与考虑的 YouTube 定位条件相符的参考受众群体规模。

censusAudienceSize

string (int64 format)

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

ReachCurve

计划产品的覆盖面曲线。

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

字段

字段
`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)` 每个计划产品在覆盖面曲线上的此点的预测分配和流量指标。

costMicros

string (int64 format)

以微单位表示的费用。

forecast

object (Forecast)

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

plannedProductReachForecasts[]

object (PlannedProductReachForecast)

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

预测

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

JSON 表示法

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)
    }
  ],
  "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 中设置的值结束。如果未设置 validFrequencyLimit 值，则此列表将为空。
`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)` 在指定方案受众特征内，根据关联的有效频次值所覆盖的用户数（包括同看用户）。

PlannedProductReachForecast

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

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

字段

字段
`plannableProductCode`	`string` 已选择规划产品。使用相同地理位置 ID 时，返回的产品代码未超出 ListPlannableProducts 返回的代码集合内。
`costMicros`	`string (int64 format)` 以微单位表示的费用。如果一个或多个计划中的产品因广告资源有限而无法达到预算，则此值可能与产品的输入分配金额不同。
`plannedProductForecast`	`object (PlannedProductForecast)` 此产品的预测流量指标。

plannableProductCode

string

已选择规划产品。使用相同地理位置 ID 时，返回的产品代码未超出 ListPlannableProducts 返回的代码集合内。

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 }

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。