- HTTP 请求
- 路径参数
- 请求正文
- 响应正文
- 授权范围
- CampaignDuration
- FrequencyCap
- EffectiveFrequencyLimit
- 定位
- AudienceTargeting
- PlannedProduct
- AdvancedProductTargeting
- YouTubeSelectSettings
- ForecastMetricOptions
- OnTargetAudienceMetrics
- ReachCurve
- ReachForecast
- 预测
- EffectiveFrequencyBreakdown(有效频率细分)
- PlannedProductReachForecast
- PlannedProductForecast
- 试试看!
针对指定的定位条件 / 产品组合生成覆盖面预测结果。
抛出的错误列表:AuthenticationError AuthorizationError FieldError HeaderError HeaderError InternalError QuotaError RangeError ReachPlanError RequestError
HTTP 请求
POST https://googleads.googleapis.com/v14/customers/{customerId}:generateReachForecast
网址采用 gRPC 转码语法。
路径参数
参数 | |
---|---|
customerId |
必需。客户的 ID。 |
请求正文
请求正文中包含结构如下的数据:
JSON 表示法 |
---|
{ "campaignDuration": { object ( |
字段 | |
---|---|
campaignDuration |
必需。广告系列投放时长。 |
cookieFrequencyCapSetting |
已选择要应用于每个计划产品的 Cookie 频次上限。这相当于在制作广告系列时 Google Ads 中显示的频次上限,表示在指定的时间间隔内,同一广告最多可以向同一用户展示的次数。如果未指定,系统会应用默认值 0(无上限)。 此字段将取代已弃用的 cookieFrequencyCap 字段。 |
targeting |
要应用于产品组合中选定所有产品的定位条件。 这是计划的定位:执行细节可能因广告产品而异,请咨询实施专家。 请查看具体指标,详细了解定位条件对这些指标有何影响。 |
plannedProducts[] |
必需。要预测的产品。允许的计划产品数量上限为 15。 |
forecastMetricOptions |
控制响应中返回的预测指标。 |
currencyCode |
货币代码。三字符的 ISO 4217 货币代码。 |
cookieFrequencyCap |
已选择要应用于每个计划产品的 Cookie 频次上限。这相当于在 Google Ads 中制作广告系列时设置频次上限,表示广告可向同一用户展示的最大次数。如果未指定,则不应用上限。 此字段在 v4 中已弃用,最终将被移除。改为使用 cookieFrequencyCapSetting。 |
minEffectiveFrequency |
为报告的覆盖面指标选择最低有效频次(用户看到广告的次数)[1-10]。这不会影响定位,只会影响报表。如果未指定,系统会应用默认值 1。 此字段不能与 validFrequencyLimit 字段结合使用。 |
effectiveFrequencyLimit |
需要包含在 Forecast.effective_frequency_breakdowns 中的最高最低有效频次(用户看到广告的次数)值 [1-10]。如果未指定,则将不提供 Forecast.effective_frequency_breakdowns。 此处提供的有效频次值也将用作所报告的覆盖面指标的最小有效频次。 此字段不能与 minEffectiveFrequency 字段结合使用。 |
customerReachGroup |
为其规划的客户的名称。这是用户定义的值。 |
响应正文
包含生成的覆盖面曲线的响应消息。
如果成功,响应正文将包含结构如下的数据:
JSON 表示法 |
---|
{ "onTargetAudienceMetrics": { object ( |
字段 | |
---|---|
onTargetAudienceMetrics |
此曲线的目标受众群体参考。 |
reachCurve |
为计划的产品组合生成的覆盖面曲线。 |
授权范围
需要以下 OAuth 作用域:
https://www.googleapis.com/auth/adwords
有关详情,请参阅 OAuth 2.0 概览。
CampaignDuration
规划好的广告系列的持续时间。
JSON 表示法 |
---|
{
"dateRange": {
object ( |
字段 | |
---|---|
dateRange |
广告系列的日期范围。日期格式为 yyyy-mm-dd(含 yyyy-mm-dd)。结束日期必须在未来 1 年内,且日期范围不得超过 92 天。 此字段不能与 durationInDays 字段结合使用。 |
durationInDays |
时长值(以天为单位)。 该字段不能与 dateRange 字段结合使用。 |
FrequencyCap
指定在特定时间段内广告可向用户展示的最大次数的规则。
JSON 表示法 |
---|
{
"impressions": integer,
"timeUnit": enum ( |
字段 | |
---|---|
impressions |
必需。展示次数(含)。 |
timeUnit |
必需。时间单位的类型。 |
EffectiveFrequencyLimit
有效频次限制。
JSON 表示法 |
---|
{ "effectiveFrequencyBreakdownLimit": integer } |
字段 | |
---|---|
effectiveFrequencyBreakdownLimit |
要包含在 Forecast.effective_frequency_breakdowns 中的最高有效频次值。此字段支持 1-10(含 1 和 10)的频率。 |
定位
将报告哪些定位条件的流量指标。
JSON 表示法 |
---|
{ "plannableLocationIds": [ string ], "ageRange": enum ( |
字段 | |
---|---|
plannableLocationIds[] |
要针对此预测定位的可规划地理位置 ID 的列表。 如果提供了多个 ID,则所有 ID 都必须具有相同的 请求必须设置此字段或 |
ageRange |
定位的年龄段。如果未设置值,则等同于定位到所有年龄。 |
genders[] |
定位的性别。不设置值等同于定位到 MALE 和 FEMALE。 |
devices[] |
目标设备。如果未指定,则定位所有适用的设备。适用的设备因产品和地区而异,并可以从 |
network |
广告产品的可定位网络。如果未指定,则定位所有适用的网络。适用的网络因产品和地区而异,并可通过 |
audienceTargeting |
定位的受众群体。如果未指定,则不会定位任何特定受众群体。 |
plannableLocationId |
所选地理位置的 ID。可从 请求必须设置此字段或 此字段自 V12 起弃用,并将在未来的版本中移除。请改用 |
AudienceTargeting
用于覆盖面预测的受众群体定位。
JSON 表示法 |
---|
{
"userInterest": [
{
object ( |
字段 | |
---|---|
userInterest[] |
基于要定位的用户兴趣的受众群体的列表。 |
PlannedProduct
正规划以扩大覆盖面的产品。
JSON 表示法 |
---|
{
"advancedProductTargeting": {
object ( |
字段 | |
---|---|
advancedProductTargeting |
所选产品的定位设置。如需列出每个产品的可用定位条件,请使用 |
plannableProductCode |
必需。已选择规划产品。与广告产品(例如 TrueView、导视广告)相关联的代码。如需列出可用的可计划产品代码,请使用 |
budgetMicros |
必需。所选产品的预算分配上限(以微单位表示)。该值使用所选规划 currencyCode。例如:1 000 000$ = 1 000 000 000 000 微秒。 |
AdvancedProductTargeting
产品的高级定位设置。
JSON 表示法 |
---|
{ // Union field |
字段 | |
---|---|
联合字段 advanced_targeting 。此产品的定位选项。advanced_targeting 只能是下列其中一项: |
|
youtubeSelectSettings |
YouTube 优选定位设置。 |
YouTubeSelectSettings
YouTube 优选频道组的请求设置
JSON 表示法 |
---|
{ "lineupId": string } |
字段 | |
---|---|
lineupId |
适用于 YouTube 优选定位的频道组。 |
ForecastMetricOptions
控制要返回的预测指标。
JSON 表示法 |
---|
{ "includeCoview": boolean } |
字段 | |
---|---|
includeCoview |
指明是否在响应预测中包含同看指标。 |
OnTargetAudienceMetrics
所规划产品的受众群体指标。这些指标考虑以下定位维度:
- 位置
- PlannableAgeRange
- 性别
- 受众群体定位(仅适用于 youtubeAudienceSize)
JSON 表示法 |
---|
{ "youtubeAudienceSize": string, "censusAudienceSize": string } |
字段 | |
---|---|
youtubeAudienceSize |
与考虑的 YouTube 定位条件相符的参考受众群体规模。 |
censusAudienceSize |
与考虑的人口普查定位条件相符的参考受众群体规模。 |
ReachCurve
计划产品的覆盖面曲线。
JSON 表示法 |
---|
{
"reachForecasts": [
{
object ( |
字段 | |
---|---|
reachForecasts[] |
覆盖面曲线上的所有点。 |
ReachForecast
覆盖面曲线上的一个点。
JSON 表示法 |
---|
{ "costMicros": string, "forecast": { object ( |
字段 | |
---|---|
costMicros |
以微单位表示的费用。 |
forecast |
此时间点的预测流量指标。 |
plannedProductReachForecasts[] |
每个计划产品在覆盖面曲线上的此点的预测分配和流量指标。 |
预测
计划的产品和定位条件的预测流量指标。
JSON 表示法 |
---|
{
"effectiveFrequencyBreakdowns": [
{
object ( |
字段 | |
---|---|
effectiveFrequencyBreakdowns[] |
有效频次预测的列表。该列表从 1 开始排序,并以 GenerateReachForecastRequest.effective_frequency_limit 中设置的值结束。如果未设置 validFrequencyLimit 值,则此列表将为空。 |
onTargetReach |
至少覆盖 GenerateReachForecastRequest.min_effective_frequency 或 GenerateReachForecastRequest.effective_frequency_limit 次数与定位条件完全匹配的唯一身份用户数。 请注意,唯一身份用户数量必须达到最低数量要求,系统才会报告数据。如果未达到最小值,onTargetReach 值将四舍五入为 0。 |
totalReach |
至少覆盖 GenerateReachForecastRequest.min_effective_frequency 或 GenerateReachForecastRequest.effective_frequency_limit 次数的唯一身份用户总数。这包括不在指定定位条件范围之内的用户。 请注意,唯一身份用户数量必须达到最低数量要求,系统才会报告数据。如果未达到最小值,totalReach 值将四舍五入为 0。 |
onTargetImpressions |
与定位条件完全匹配的广告展示次数。 |
totalImpressions |
广告的总展示次数。包括由于有关已登录用户的信息不足而导致超出指定定位条件的展示次数。 |
viewableImpressions |
广告展示被视为可见的次数。如需详细了解广告可见的要素以及如何衡量可见度,请参阅 https://support.google.com/google-ads/answer/7029393。 |
onTargetCoviewReach |
与定位条件完全匹配的覆盖的唯一身份用户数(包括同看者)。 |
totalCoviewReach |
覆盖的唯一身份用户数(包括同看者)。这包括不在指定定位条件范围之内的用户。 |
onTargetCoviewImpressions |
与定位条件完全匹配的广告展示次数(包括同看者)。 |
totalCoviewImpressions |
总展示次数,包括同看者。包括由于有关已登录用户的信息不足而导致超出指定定位条件的展示次数。 |
EffectiveFrequencyBreakdown
在指定的有效频次下覆盖的唯一身份用户数的细分数据。
JSON 表示法 |
---|
{ "effectiveFrequency": integer, "onTargetReach": string, "totalReach": string, "effectiveCoviewReach": string, "onTargetEffectiveCoviewReach": string } |
字段 | |
---|---|
effectiveFrequency |
有效频率 [1-10]。 |
onTargetReach |
至少覆盖到与定位条件完全匹配的有效频次时段的唯一身份用户数。 请注意,唯一身份用户数量必须达到最低数量要求,系统才会报告数据。如果未达到最小值,onTargetReach 值将四舍五入为 0。 |
totalReach |
覆盖的唯一身份用户总数至少达到有效频次。这包括不在指定定位条件范围之内的用户。 请注意,唯一身份用户数量必须达到最低数量要求,系统才会报告数据。如果未达到最小值,totalReach 值将四舍五入为 0。 |
effectiveCoviewReach |
针对关联的 validFrequency 值覆盖的用户数(包括同看用户数)。 |
onTargetEffectiveCoviewReach |
在指定方案受众特征内,根据关联的有效频次值所覆盖的用户数(包括同看用户)。 |
PlannedProductReachForecast
特定产品在覆盖面曲线上某一点的预测分配和流量指标。
JSON 表示法 |
---|
{
"plannableProductCode": string,
"costMicros": string,
"plannedProductForecast": {
object ( |
字段 | |
---|---|
plannableProductCode |
已选择规划产品。使用相同地理位置 ID 时,返回的产品代码未超出 ListPlannableProducts 返回的代码集合内。 |
costMicros |
以微单位表示的费用。如果一个或多个计划中的产品因广告资源有限而无法达到预算,则此值可能与产品的输入分配金额不同。 |
plannedProductForecast |
此产品的预测流量指标。 |
PlannedProductForecast
所规划产品的预测流量指标。
JSON 表示法 |
---|
{ "onTargetReach": string, "totalReach": string, "onTargetImpressions": string, "totalImpressions": string, "viewableImpressions": string, "onTargetCoviewReach": string, "totalCoviewReach": string, "onTargetCoviewImpressions": string, "totalCoviewImpressions": string } |
字段 | |
---|---|
onTargetReach |
与定位条件完全匹配的覆盖的唯一身份用户数。 请注意,唯一身份用户数量必须达到最低数量要求,系统才会报告数据。如果未达到最小值,onTargetReach 值将四舍五入为 0。 |
totalReach |
覆盖的唯一身份用户数。这包括不在指定定位条件范围之内的用户。 请注意,唯一身份用户数量必须达到最低数量要求,系统才会报告数据。如果未达到最小值,totalReach 值将四舍五入为 0。 |
onTargetImpressions |
与定位条件完全匹配的广告展示次数。 |
totalImpressions |
广告的总展示次数。包括由于有关已登录用户的信息不足而导致超出指定定位条件的展示次数。 |
viewableImpressions |
广告展示被视为可见的次数。如需详细了解广告可见的要素以及如何衡量可见度,请参阅 https://support.google.com/google-ads/answer/7029393。 |
onTargetCoviewReach |
与定位条件完全匹配的覆盖的唯一身份用户数(包括同看者)。 |
totalCoviewReach |
覆盖的唯一身份用户数(包括同看者)。这包括不在指定定位条件范围之内的用户。 |
onTargetCoviewImpressions |
与定位条件完全匹配的广告展示次数(包括同看者)。 |
totalCoviewImpressions |
总展示次数,包括同看者。包括由于有关已登录用户的信息不足而导致超出指定定位条件的展示次数。 |