借助 BenchmarksService，广告客户和代理机构可以将其 YouTube 广告效果与行业基准进行比较。借助此服务，您可以评估广告系列在特定产品和服务类别中相对于行业细分或所有广告客户的效果。
主要功能
借助 BenchmarksService，您可以执行以下操作：
- 比较效果：将客户的平均费率指标（例如 CPM、CPV、点击率和可见度）与汇总的行业平均水平进行比较。
- 分析市场份额：通过广告占有率（相对展示次数）和支出份额了解客户的相对市场占有率。
- 评估竞争地位：使用百分位指标衡量客户的竞争地位，这些指标可将关键维度方面的表现划分为不同的竞争层级（例如市场领导者或竞争者）。
- 按时间段细分：按每周、每月或每季度的时间粒度对基准指标进行分组。
- 发现支持的基准维度：查询可用的日期范围、地理位置、广告产品和基准来源（行业细分或产品和服务类别）。
发现方法
在生成基准指标之前，请使用发现方法检索请求的有效参数和范围界定条件。
列出可用的日期
ListBenchmarksAvailableDates 方法会返回 ListBenchmarksAvailableDatesResponse 中支持基准数据的历史日期范围。
响应会提供两个不同的日期范围：
supported_dates：支持基准比较指标的总体日期范围（含边界值）。基准比较请求可以查询此范围内的日期。supported_dates_for_all_metrics：supported_dates的子集，支持全套基准指标。由于数据可用性有限，某些指标（尤其是客户份额指标 [share_of_voice和share_of_spend] 以及基准来源的平均费率指标）仅在此日期范围内可用。如果所请求的date_range未完全落在supported_dates_for_all_metrics内，则响应中会省略这些指标。
列出位置
ListBenchmarksLocations 方法会返回支持基准数据的地理位置（例如国家/地区）列表。
响应中的每个 BenchmarksLocation 都包含：
location_name：英文的唯一位置名称（例如"United States"）。location_type：与 Google Ads API 中的target_type对应的位置类型（例如，"Country"）。location_info：一个LocationInfo对象，其中包含地理位置定位常量（例如geo_target_constant: "geoTargetConstants/2840"）。
列出商品
ListBenchmarksProducts 方法会返回可用于基准比较的产品和营销目标列表。
每个 BenchmarksProductMetadata 条目都包含：
product_name：简单易记的产品名称。product_code：商品的唯一标识符字符串，用于构建ProductFilter时。marketing_objective：关联的营销目标（BenchmarksMarketingObjective）：AWARENESS：旨在提高品牌或产品认知度的广告系列。CONSIDERATION：旨在鼓励潜在客户考虑品牌或产品的广告系列。ACTION：旨在促成特定转化操作的广告系列。
列出基准来源
ListBenchmarksSources 方法可检索可用的基准来源。使用 BenchmarksSourceType 指定要检索的来源类型：
INDUSTRY_VERTICAL：行业细分的分类（例如“技术”或“金融”）。CATEGORY：商品和服务类别（例如，“/服装/衣物”）。在与所有广告客户进行比较时，类别可用作过滤条件来确定基准比较范围。
响应会返回一个 BenchmarksSourceMetadata 对象列表，其中包含以下任一内容：
IndustryVerticalInfo：包含industry_vertical_name、industry_vertical_id和parent_industry_vertical_id（如果适用）。CategoryInfo：包含category_name、category_id和category_path（完整类别层次结构）。
生成基准指标
调用 GenerateBenchmarksMetrics 将客户的 YouTube 广告指标与行业基准进行比较。
请求参数
GenerateBenchmarksMetricsRequest 用于限定分析范围。您必须至少指定一个客户 customer_id、地理位置 location、一个 benchmarks_source（例如特定行业或所有以 category_filter 为范围的广告客户）和一个 product_filter。您可以选择性地提供 date_range、使用 breakdown_definition 对指标进行分组、指定 currency_code，或通过 supplemental_data 请求其他功能（例如 PERCENTILE_DATA）。
如需查看完整的参数定义和要求，请参阅 GenerateBenchmarksMetricsRequest 参考文档。
日期细分
您可以使用 BenchmarksTimeGranularity 设置 breakdown_definition.date_breakdown 来对指标进行分组：
WEEK：按周汇总指标。date_range必须从周日开始，到周六结束（请注意，这与 ISO 8601 不同）。MONTH：按月汇总指标。date_range必须从当月的第一天开始，到当月的最后一天结束。QUARTER：按日历季度汇总指标。date_range必须从季度的第一天开始，到季度的最后一天结束。
回答指标
GenerateBenchmarksMetricsResponse
会返回：
customer_metrics：表示客户 YouTube 广告效果的指标，包括average_rate_metrics、share_metrics、aggregate_metrics和percentile_metrics。average_benchmarks_metrics：所选基准来源的汇总比率指标 (RateMetrics)。breakdown_metrics：按breakdown_definition中定义细分维度细分的指标列表。
如需查看完整的字段规范，请参阅 GenerateBenchmarksMetricsResponse 参考文档。
百分位数指标
百分位指标表示客户在指定范围的分析中，与其他广告客户相比的竞争地位（以百分位层级表示）。
前提条件
如需检索百分位指标，您的请求必须满足以下要求：
- 基准来源：
benchmarks_source必须选择all_advertisers = true。 - 类别过滤条件：必须提供
category_filter，其中包含从ListBenchmarksSources检索到的一个或多个有效category_ids。 - 补充数据：您必须在
GenerateBenchmarksMetricsRequest的supplemental_data字段中添加PERCENTILE_DATA。
百分位层级
客户的效果分为若干个 BenchmarksCustomerPercentileTier 枚举值之一（从较低层级的 DEVELOPING 到效果出色的广告客户的 MARKET_LEADER）。如需了解每个层级及其百分位边界，请参阅 BenchmarksCustomerPercentileTier 参考文档。
示例请求
以下示例展示了一个 REST JSON 请求载荷，用于生成具有百分位层级的基准指标，以便用户将其客户的 YouTube 广告效果与在“服装/服装”类别中投放广告的其他广告客户进行比较：
{
"customer_id": "1234567890",
"location": {
"geo_target_constant": "geoTargetConstants/2840"
},
"benchmarks_source": {
"all_advertisers": true
},
"category_filter": {
"category_ids": ["10176"]
},
"product_filter": {
"marketing_objective_list": {
"marketing_objectives": ["AWARENESS", "CONSIDERATION"]
}
},
"supplemental_data": [
"PERCENTILE_DATA"
]
}
包含所请求的额外百分位数数据的响应：
{
"customer_metrics": {
"average_rate_metrics": {
"average_cpm": 5.42,
"click_through_rate": 0.0185
},
"share_metrics": {
"share_of_voice": 0.0345,
"share_of_spend": 0.0410
},
"aggregate_metrics": {
"cost": 15200.0,
"impressions": 2800000.0,
"clicks": 51800.0
},
"percentile_metrics": {
"cost_percentile_tier": "STRONG_COMPETITOR",
"impressions_percentile_tier": "STRONG_COMPETITOR",
"clicks_percentile_tier": "MARKET_LEADER",
"video_trueview_views_percentile_tier": "COMPETITOR",
"viewable_impressions_percentile_tier": "STRONG_COMPETITOR",
"interactions_percentile_tier": "MARKET_LEADER",
"engagements_percentile_tier": "COMPETITOR"
}
},
"average_benchmarks_metrics": {
"average_rate_metrics": {
"average_cpm": 6.15,
"click_through_rate": 0.0142
}
}
}
错误处理
调用 BenchmarksService 时，您可能会遇到 BenchmarksError 中与基准比较查询相关的特定错误：
MAX_QUERY_COMPLEXITY_EXCEEDED：所请求输入的组合过于复杂，无法处理。如需降低查询复杂性，请执行以下操作：- 选择更具体或更精细的基准比较对象或类别过滤条件。
- 缩短所请求的
date_range。 - 减少
product_filter中的商品数量。
NO_METRICS_FOUND：未找到所请求的输入组合对应的指标（例如，在特定位置和日期范围内，没有广告客户投放广告系列的利基类别）。尝试调整类别、位置、日期范围或商品。
如需了解常规 API 错误处理和最佳实践，请参阅错误处理指南。