YouTube 基准分析

BenchmarksService 可让广告客户和代理机构 将其 YouTube 广告效果与行业基准进行比较。 借助此服务，您可以评估您的广告系列在特定产品和服务类别中相对于行业垂直领域或所有广告客户的效果。

主要功能

借助 BenchmarksService，您可以：

• 比较效果：将客户的平均费率指标（例如 每千次展示费用、每次观看费用、点击率和可见度）与汇总的行业平均值进行比较。
• 分析市场份额：了解客户的相对市场占有率 通过广告占有率（相对展示次数）和支出份额。
• 评估竞争地位：使用百分位指标衡量客户的竞争 地位，这些指标可将关键 维度的效果划分为不同的竞争层级（例如“市场领导者”或“竞争者”）。
• 按时间细分：按周、月或 季度对基准指标进行分组。
• 发现受支持的基准维度：查询可用的日期范围、 地理位置、广告产品和基准来源（行业 垂直领域或产品和服务类别）。

发现方法

在生成基准指标之前，请使用发现方法检索请求的有效参数和范围界定条件。

列出可用日期

ListBenchmarksAvailableDates 方法会在 ListBenchmarksAvailableDatesResponse中返回支持基准数据的历史日期范围。

响应提供两个不同的日期范围：

• supported_dates：支持基准指标的总体日期范围（含边界值）。基准请求可以查询此范围内的日期。
• supported_dates_for_all_metrics（在 v25 及更高版本中）：supported_dates 的子集，支持全套 基准指标。由于数据可用性有限，某些指标（特别是客户份额指标 （share_of_voice 和 share_of_spend） 以及基准来源的平均费率指标）仅在 此日期范围内可用。如果请求的 date_range 未完全落在 supported_dates_for_all_metrics 内，则响应中会省略这些指标。

列出位置

ListBenchmarksLocations 方法会返回支持基准数据的地理位置（例如国家/地区）列表 。

响应中的每个 BenchmarksLocation 都包含：

• location_name：唯一的英文位置名称（例如 "United States"）。
• location_type：与 target_type 在 Google Ads API 中的位置类型（例如 "Country"）。
• location_info：一个 LocationInfo 对象，其中包含 地理位置目标常量（例如 geo_target_constant: "geoTargetConstants/2840"）。

列出商品

The ListBenchmarksProducts 方法会返回可用于基准比较的商品和营销目标列表 。

每个 BenchmarksProductMetadata 条目都包含：

• product_name：人性化的商品名称。
• product_code：商品的唯一标识符字符串，用于 构建 ProductFilter。
• marketing_objective：关联的营销目标 (BenchmarksMarketingObjective)：
  • AWARENESS：旨在提高品牌或商品认知度的广告系列。
  • CONSIDERATION：旨在鼓励潜在客户考虑品牌或商品的广告系列。
  • ACTION：旨在促成特定转化操作的广告系列。

列出基准来源

The ListBenchmarksSources 方法会检索可用的 基准来源。使用 BenchmarksSourceType指定要检索的来源类型：

• INDUSTRY_VERTICAL：行业细分分类（例如 "Technology" 或 "Finance"）。
• CATEGORY（在 v25 及更高版本中）：产品和服务类别（例如 "/Apparel/Clothing"）。与所有广告客户进行比较时，类别可用作过滤条件来界定 基准比较的范围。

响应会返回一个 BenchmarksSourceMetadata 对象列表，其中包含 以下任一项：

• IndustryVerticalInfo：包含 industry_vertical_name、industry_vertical_id 和 parent_industry_vertical_id（如果适用）。
• CategoryInfo （在 v25 及更高版本中）：包含 category_name、category_id 和 category_path（完整类别层次结构）。

生成基准指标

调用 GenerateBenchmarksMetrics 可将客户的 YouTube 广告指标与行业基准进行比较。

请求参数

A GenerateBenchmarksMetricsRequest 用于界定分析范围 。您至少必须指定客户 customer_id、地理位置 locationLocationInfo、 benchmarks_source（industry_vertical_id 或 v25 及更高版本中由 category_filter界定范围的all_advertisers）和 product_filter。 您可以选择执行以下操作：

• 提供 date_range（如果省略，则返回 最近一个季度的数据，前提是有可用数据）。
• 使用 breakdown_definition 对指标进行分组。
• 指定由 3 个字符组成的 ISO 4217 currency_code（如果省略，则货币指标（例如每千次展示费用和费用）默认使用 USD）。
• 为计划中的客户指定用户定义的 customer_benchmarks_group 名称。
• 通过 supplemental_data （在 v25 及更高版本中）请求其他功能，例如 PERCENTILE_DATA。

如需了解完整的参数定义和要求，请参阅 GenerateBenchmarksMetricsRequest参考 文档。

日期细分

您可以通过设置 breakdown_definition.date_breakdown 使用 BenchmarksTimeGranularity 对指标进行分组。设置 date_breakdown is set, date_range in GenerateBenchmarksMetricsRequest 后，date_range in GenerateBenchmarksMetricsRequest 中的 date_range in GenerateBenchmarksMetricsRequest 是 必需的，并且必须与所选粒度的边界对齐：

• WEEK：按周汇总指标。date_range 必须以周日 开始，以周六 结束（请注意，这与 ISO 8601 不同）。
• MONTH：按月汇总指标。date_range 必须以当月的第一天开始，以当月的最后一天结束。
• QUARTER：按日历季度汇总指标。date_range 必须以当季度的第一天开始，以当季度的最后一天结束。

响应指标

GenerateBenchmarksMetricsResponse 会返回：

• customer_metrics（在 v25 及更高版本中为 CustomerMetrics类型；在 v24 及 更早版本中为仅包含 average_rate_metrics 的 Metrics类型）：表示客户 YouTube 广告效果的指标， 包括：
  • average_rate_metrics：客户的平均费率指标。
  • share_metrics （在 v25 及更高版本中）：相对市场占有率指标（share_of_voice 和 share_of_spend）。仅当 benchmarks_source 选择 all_advertisers = true（设置了 category_filter）且 date_range 落在 supported_dates_for_all_metrics 内时，才会填充此字段。
  • aggregate_metrics （在 v25 及更高版本中）：客户的汇总总数（例如 cost、impressions、clicks 和 video_trueview_views）。
  • percentile_metrics （在 v25 及更高版本中）：关键维度上的竞争地位百分位层级。
• average_benchmarks_metrics：所选基准来源的汇总费率指标 (RateMetrics)。
• breakdown_metrics：一个指标列表，按 breakdown_definition 中定义的细分进行细分。

如需了解完整的字段规范，请参阅 GenerateBenchmarksMetricsResponse 参考文档。

百分位指标

百分位指标表示客户在界定范围的分析中相对于其他广告客户的竞争地位，以百分位层级表示。

前提条件

如需检索百分位指标，您的请求必须满足以下要求：

1. 基准来源：benchmarks_source 必须选择 all_advertisers = true。
2. 类别过滤条件：必须提供 category_filter，其中包含一个或 多个有效 category_ids，这些有效是从 ListBenchmarksSources 检索到的。
3. 补充数据：您必须将 PERCENTILE_DATA添加到supplemental_data 中的 GenerateBenchmarksMetricsRequest字段。

百分位层级

客户的效果分为以下 BenchmarksCustomerPercentileTier enum values:

• DEVELOPING：低于第 10 个百分位 ([0%, 10%))。
• ENTRY_LEVEL：第 10 个到第 25 个百分位 ([10%, 25%))。
• EMERGING_PLAYER：第 25 个到第 50 个百分位 ([25%, 50%))。
• COMPETITOR：第 50 个到第 75 个百分位 ([50%, 75%))。
• STRONG_COMPETITOR：第 75 个到第 90 个百分位 ([75%, 90%))。
• MARKET_LEADER：达到或高于第 90 个百分位 ([90%, 100%])。

示例请求

以下示例展示了一个 REST JSON 请求载荷，用于生成基准指标（包含百分位层级），以便用户将其客户的 YouTube 广告效果与在 /Apparel/Clothing 类别中投放广告的其他广告客户进行比较：

{
  "customerId": "1234567890",
  "location": {
    "geoTargetConstant": "geoTargetConstants/2840"
  },
  "benchmarksSource": {
    "allAdvertisers": true
  },
  "categoryFilter": {
    "categoryIds": ["10176"]
  },
  "productFilter": {
    "marketingObjectiveList": {
      "marketingObjectives": ["AWARENESS", "CONSIDERATION"]
    }
  },
  "supplementalData": [
    "PERCENTILE_DATA"
  ]
}

响应（包括请求的额外百分位数据）：

{
  "customerMetrics": {
    "averageRateMetrics": {
      "averageCpm": 5.42,
      "clickThroughRate": 0.0185
    },
    "shareMetrics": {
      "shareOfVoice": 0.0345,
      "shareOfSpend": 0.0410
    },
    "aggregateMetrics": {
      "cost": 15200.0,
      "impressions": 2800000.0,
      "clicks": 51800.0
    },
    "percentileMetrics": {
      "costPercentileTier": "STRONG_COMPETITOR",
      "impressionsPercentileTier": "STRONG_COMPETITOR",
      "clicksPercentileTier": "MARKET_LEADER",
      "videoTrueviewViewsPercentileTier": "COMPETITOR",
      "viewableImpressionsPercentileTier": "STRONG_COMPETITOR",
      "interactionsPercentileTier": "MARKET_LEADER",
      "engagementsPercentileTier": "COMPETITOR"
    }
  },
  "averageBenchmarksMetrics": {
    "averageRateMetrics": {
      "averageCpm": 6.15,
      "clickThroughRate": 0.0142
    }
  }
}

错误处理

调用 BenchmarksService 时，您可能会遇到 BenchmarksError 中特定于 基准查询的错误：

• MAX_QUERY_COMPLEXITY_EXCEEDED：请求的输入组合过于复杂，无法处理。如需降低查询的复杂性，请执行以下操作：
  • 选择更具体或更精细的基准来源或类别过滤条件。
  • 缩短请求的 date_range。
  • 减少 product_filter 中的商品数量。
• NO_METRICS_FOUND （在 v25 及更高版本中）：未找到请求的输入组合的指标（例如，在特定位置和日期范围内，没有广告客户投放广告的小众类别）。 请尝试调整类别、位置、日期范围或商品。

如需了解常规 API 错误处理和最佳实践，请参阅 错误处理指南。