Method: customers.generateReachForecast

針對特定指定目標 / 產品組合產生觸及預測資料。

擲回錯誤清單：AuthenticationError AuthorizationError FieldError HeaderError InternalError QuotaError RangeError ReachPlanError RequestError

HTTP 要求

POST https://googleads.googleapis.com/v14/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

貨幣代碼。3 個字元的 ISO 4217 貨幣代碼。
cookieFrequencyCap

integer

選擇要套用至每個規劃產品的 Cookie 展示頻率上限。這相當於 Google Ads 在建立廣告活動時顯示的展示頻率上限，代表廣告可向同一位使用者顯示的次數上限。如未指定，系統不會套用任何上限。

這個欄位已在 v4 中淘汰，且最終會移除。請改用 cookieFrequencyCapSetting。
minEffectiveFrequency

integer

為報表中的觸及指標選擇最低有效展示頻率 (使用者看到廣告的次數) 。這不會影響指定目標，而只會影響報表。如果未指定，系統會套用預設值 1。

這個欄位無法與 validFrequencyLimit 欄位合併。
effectiveFrequencyLimit

object (EffectiveFrequencyLimit)

最高有效展示頻率 (使用者看到廣告的次數) 的值 [1-10]，用於「Forecast.effective_frequency_breakdowns」。如未指定，系統就不會提供 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 天。

這個欄位不得與 timeInDays 欄位合併。
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的預算。可規劃地區 ID 及其 parentCountryId 可從 ReachPlanService.ListPlannableLocations 取得。

要求必須設定這個欄位或 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。可規劃地區 ID 可從 ReachPlanService.ListPlannableLocations 取得。

要求必須設定這個欄位或 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 表示法 
{

  // 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.
}
欄位
聯集欄位 advanced_targeting。這項產品的指定目標選項。advanced_targeting 只能是下列其中一項：
youtubeSelectSettings

object (YouTubeSelectSettings)

YouTube Select 指定目標的設定。

YouTubeSelectSettings

YouTube Select 首選頻道請求設定

JSON 表示法 
{
  "lineupId": string
}
欄位
lineupId

string (int64 format)

YouTube Select 指定目標首選頻道。

ForecastMetricOptions

控管要傳回的預測指標。

JSON 表示法 
{
  "includeCoview": boolean
}
欄位
includeCoview

boolean

指出是否要在回應預測中加入共視指標。

OnTargetAudienceMetrics

預定產品的目標對象指標。這些指標考量的指定目標維度如下：

  • 位置
  • PlannableAgeRange
  • 性別
  • 指定目標對象 (僅適用於 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
}
欄位
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 次的不重複總人數。包括可能不屬於指定指定目標的使用者。

請注意，報表須觸及最少不重複使用者，才能回報資料。如果未達最低數據，則總觸及值會四捨五入為 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)

廣告曝光總數 (含共視觀眾)。這包括因為登入使用者的資訊不足，而可能不屬於指定指定目標的曝光。

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)

觸及至少有效展示頻率的不重複使用者總數。包括可能不屬於指定指定目標的使用者。

請注意，報表須觸及最少不重複使用者，才能回報資料。如果未達最低數據，則總觸及值會四捨五入為 0。
effectiveCoviewReach

string (int64 format)

相關聯的有效展示頻率值觸及的使用者人數 (包括共視使用者)，
onTargetEffectiveCoviewReach

string (int64 format)

在指定企劃書客層內，相關聯的有效展示頻率值所觸及的使用者人數 (包括共視使用者)。

PlannedProductReachForecast

特定產品在觸及數曲線上的預測分配情形和流量指標。

JSON 表示法 
{
  "plannableProductCode": string,
  "costMicros": string,
  "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
}
欄位
onTargetReach

string (int64 format)

與指定目標完全相符的不重複使用者人數。

請注意，報表須觸及最少不重複使用者，才能回報資料。如果未達最低數量，onTargetReach 值會四捨五入為 0。
totalReach

string (int64 format)

已觸及的不重複使用者人數。包括可能不屬於指定指定目標的使用者。

請注意，報表須觸及最少不重複使用者，才能回報資料。如果未達最低數據，則總觸及值會四捨五入為 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)

廣告曝光總數 (含共視觀眾)。這包括因為登入使用者的資訊不足，而可能不屬於指定指定目標的曝光。