您可以使用 ContentCreatorInsightsService 中的创作者分析功能,发现并获取有关 YouTube 创作者的分析洞见。此服务可帮助代理机构和广告客户找到与目标受众群体相关的创作者。
该 API 具有四项主要功能:
- 创作者可发现性 :根据给定的主题、受众特征、受众群体或创作者属性,查找相关创作者。
- 创作者主题分析 :获取制作指定主题相关内容的创作者的分析洞见。
- 创作者分析 :获取特定 YouTube 频道的分析洞见,例如订阅人数、观看次数和受众群体特征。
- 趋势分析 :根据特定受众群体或主题,获取特定趋势的分析洞见。
当您使用基于主题的“发现创作者”功能或趋势分析功能时,可以通过请求补充数据来支持本地创作者发现(查找位于给定国家/地区或从该国家/地区发布内容且在该国家/地区被观看的创作者)。您还可以通过请求补充数据,为基于主题的趋势分析请求品牌情绪分析洞见。
资格要求
GenerateCreatorInsights 是 Google Ads API 的私有组件,提供非独占的免版税数据许可。已签署
协议的合作伙伴可以使用标准 Google Ads 客户端库 来探索
YouTube 创作者和内容。若要符合资格,合作伙伴必须满足以下条件:
- 拥有集成 Google Ads API 的规划工具或界面。
- 使用该 API 探索 YouTube 内容和创作者,以寻找潜在的广告机会。
- 完成预筛选评估以验证资格。
- 遵循数据使用要求并接受定期数据审核。
- 接受 Google Ads API 服务条款和 相关的数据使用政策。
如需了解详情,请与您的 Google 代表联系。
生成创作者分析洞见
如需生成创作者分析洞见,请向
GenerateCreatorInsights 方法发送请求。此方法的每秒查询次数 (QPS) 上限为 5。它接受不同的条件,具体取决于您是需要创作者曝光度、基于主题的创作者搜索,还是特定频道的创作者分析洞见。您必须在 country_locations 中提供目标国家/地区
。
创作者可发现性 (
search_attributes): 使用search_attributes字段提供 受众群体属性列表(例如年龄、性别和用户兴趣(兴趣相似的受众群体、 有购买意向的受众群体和人生大事受众群体)),以查找受众群体与这些属性相符的创作者。您还可以提供创作者属性,以过滤出内容与特定属性相符的创作者。通过 指定所需的维度(例如
KNOWLEDGE_GRAPH表示感兴趣的主题),使用ListAudienceInsightsAttributes检索可用的受众群体属性。如需使用布尔值AND和OR组组合属性,请使用audience_combinations,如复杂受众群体 组合中所述。创作者主题分析 (
search_topics): 使用search_topics字段提供内容 主题列表。该 API 会返回制作指定主题相关内容的相关创作者。系统会针对 中指定的国家/地区提取数据country_locations(此选项支持每个请求指定一个 国家/地区)。search_topics中支持的实体必须使用CONTENT_TRENDING_INSIGHTS或CREATOR_TOPIC_INSIGHTS功能进行标记。使用ListAudienceInsightsAttributes检索支持的实体功能。创作者分析 (
search_channels): 使用search_channels字段提供 YouTube 频道 ID 列表、YouTube 频道帐号 (youtube_channel_handles,可在v25及更高版本中使用),或两者的组合。该 API 会返回有关这些特定频道的分析洞见。
复杂受众群体组合
在 GenerateCreatorInsights 和 GenerateTrendingInsights 中,您都可以使用 audience_combinations 定义复杂的受众群体属性关系。借助此字段,您可以使用布尔逻辑(AND 和 OR)组合受众群体属性,而不仅仅是 audience_attributes 的扁平并集 (OR) 行为:
audience_combinations中的每个InsightsAudienceAttributeGroup都使用逻辑OR组合其属性。audience_combinations中的多个InsightsAudienceAttributeGroup项使用逻辑AND组合。
例如,如需定位对 ("Skin care" OR "Hair
care") AND "Cosmetics" 感兴趣的受众群体,请在 audience_combinations 中添加两个 InsightsAudienceAttributeGroup 项
:
- 第 1 组包含
"Skin care"和"Hair care"的知识图谱实体属性。 - 第 2 组包含
"Cosmetics"的知识图谱实体属性(例如/m/014trl)。
补充数据和本地创作者
默认情况下,系统只会返回核心分析洞见数据。您可以通过设置重复字段
supplemental_data,在响应中请求可选
功能和其他数据。
例如,您可以通过将 LOCAL_CREATOR_DATA 枚举值添加到 supplemental_data 来请求本地创作者数据。如果您使用 search_topics 搜索
创作者(并且该主题是使用 CREATOR_TOPIC_INSIGHTS 功能标记的知识图谱实体
),则该 API 会在响应中填充
local_creator_insights 字段,其中包含已同意分享其位置数据的本地创作者
。
请注意以下“发现创作者”功能本地发现规范:
- 定义 :本地创作者是指位于所选国家/地区或从该国家/地区发布内容且在该国家/地区被观看的创作者。
- 限制:如果在请求中设置了
sub_country_locations,则不支持本地“发现创作者”功能。 - 功能:您可以使用知识图谱
实体及其功能列表,使用
ListAudienceInsightsAttributes检索支持的知识图谱实体及其功能列表。
GenerateCreatorInsights 方法会返回一个 GenerateCreatorInsightsResponse
对象,其中包含以下字段:
creator_insights:与您的核心条件相符的YouTubeCreatorInsights对象列表。local_creator_insights:本地创作者的YouTubeCreatorInsights对象列表。仅当请求了LOCAL_CREATOR_DATA且使用的条件为search_topics时,才会填充此字段。
每个 YouTubeCreatorInsights 对象都包含:
creator_name:创作者的名称。creator_channels:YouTubeChannelInsights对象列表。频道 详细信息和channel_metrics(YouTubeMetrics) 会 在每个YouTubeChannelInsights对象内返回,位于creator_channels中。
The YouTubeMetrics 对象包含:
- 订阅人数、观看次数和视频数量
- 频道所有视频的点赞、分享和评论总数
- 生命周期互动率(总互动次数除以总观看次数)
- 过去 28 天内每个视频的平均观看次数、点赞次数、分享次数和评论次数
- Shorts 观看次数和视频数量
- 创作者是活跃的 Shorts 短视频创作者还是活跃的直播创作者(在过去 90 天内发布过一个视频)
- 合作伙伴机会
互动率和每个视频的平均观看次数、点赞次数和评论次数是非公开指标,只有在创作者同意分享这些指标时才会填充。
如需检查创作者是否有资格参与原创品牌合作内容合作伙伴计划,
请检查 partnership_opportunities;如果该列表包含
CREATOR_PARTNERSHIPS,则表示创作者符合资格。
YouTubeChannelInsights 对象包含以下有关 YouTube 频道的信息:
- 频道名称、ID、帐号、网址、说明和缩略图网址
- 频道创建日期和关联的国家/地区
- 频道指标
- 频道受众群体属性(例如年龄、性别和用户兴趣细分)
- 频道属性(与频道内容关联的属性)
- 热门视频
- 频道类型和内容语言
- 相关性得分(仅适用于热搜)
- 创作者是否已同意分享非公开指标
GenerateCreatorInsights 请求和响应参考
在
以下端点对
ContentCreatorInsightsService调用GenerateCreatorInsights:
POST https://googleads.googleapis.com/v26/customers/{customer_id}:generateCreatorInsights
下表总结了
GenerateCreatorInsightsRequest中的字段:
| 字段路径 | 要求 | 格式和限制 |
|---|---|---|
customer_id |
必填 | 10 位数的客户 ID (string),不含连字符。 |
customer_insights_group |
必填 | 用户定义的要规划的客户或品牌的名称 (string)。 |
country_locations[] |
必填 | 国家/地区 LocationInfo 对象列表 (geo_target_constant,例如 "geoTargetConstants/2840")。使用 search_topics 时,必须包含单个国家/地区。 |
sub_country_locations[] |
可选 | 国家/地区以下级 LocationInfo 过滤条件;仅支持 search_attributes,且与 LOCAL_CREATOR_DATA 不兼容。 |
search_attributes |
criteria (oneof) |
SearchAttributes 包含以下内容:• audience_attributes[]:age_range、gender、device、parental_status、income_range(如果未使用 audience_combinations,则还包括 user_interest、entity 或 category)。• audience_combinations[]:AND-of-ORs InsightsAudienceAttributeGroup 项。• creator_attributes[]:具有 CREATOR_ATTRIBUTE 功能的知识图谱 entity 项。 |
search_topics |
criteria (oneof) |
SearchTopics 包含 entities[](AudienceInsightsEntity,其中 knowledge_graph_machine_id 使用 CREATOR_TOPIC_INSIGHTS 或 CONTENT_TRENDING_INSIGHTS 标记)。 |
search_channels |
criteria (oneof) |
YouTubeChannels 包含 youtube_channels[] (channel_id) 和/或 youtube_channel_handles[](以 @ 开头的帐号,例如 "@youtubecreators")。 |
supplemental_data[] |
可选 | ContentCreatorInsightsSupplementalData 值。在单个国家/地区的 search_topics 请求(适用于具有 CREATOR_TOPIC_INSIGHTS 的实体)中设置 LOCAL_CREATOR_DATA,以填充 local_creator_insights[]。 |
insights_application_info |
可选 | AdditionalApplicationInfo 有关发出请求的应用的元数据。 |
GenerateCreatorInsightsResponse 消息会返回
以下字段:
| 响应字段 | 类型 | 说明 |
|---|---|---|
creator_insights[] |
YouTubeCreatorInsights |
与您的核心条件(creator_name 和 creator_channels[])相符的创作者。 |
local_creator_insights[] |
YouTubeCreatorInsights |
已同意分享位置数据的本地创作者(当针对具有 CREATOR_TOPIC_INSIGHTS 的实体使用 search_topics 请求 LOCAL_CREATOR_DATA 时填充)。 |
creator_channels[] |
YouTubeChannelInsights |
元数据: display_name、youtube_channel.channel_id、handle、channel_url、publish_date、country_location 和 data_sharing_consent_given。分析洞见和内容: channel_audience_attributes[](需要同意)、channel_attributes[]、top_videos[]、language_distributions[]、relevance_score(仅针对使用 search_topics 的 GenerateTrendingInsights 填充)和 channel_metrics。 |
channel_metrics |
YouTubeMetrics |
公开指标:subscriber_count、views_count、video_count、likes_count、shares_count、comments_count、shorts_views_count、shorts_video_count、is_active_shorts_creator、is_active_live_stream_creator 和 partnership_opportunities[]。需要同意的指标: engagement_rate 和 28 天内每个视频的平均值(average_views_per_video、average_likes_per_video、average_shares_per_video、average_comments_per_video)。 |
GenerateCreatorInsights REST 请求和响应示例
以下示例使用 searchAttributes(包含
受众特征 audienceAttributes、布尔值 audienceCombinations("Skin care"
OR "Hair care"、AND "Cosmetics")和 creatorAttributes)发现创作者:
POST https://googleads.googleapis.com/v26/customers/{customer_id}:generateCreatorInsights
{
"customerInsightsGroup": "Spring Skincare Campaign",
"countryLocations": [
{
"geoTargetConstant": "geoTargetConstants/2840"
}
],
"searchAttributes": {
"audienceAttributes": [
{
"ageRange": {
"type": "AGE_RANGE_25_34"
}
},
{
"gender": {
"type": "FEMALE"
}
}
],
"audienceCombinations": [
{
"attributes": [
{
"entity": {
"knowledgeGraphMachineId": "/m/015c4z"
}
},
{
"entity": {
"knowledgeGraphMachineId": "/m/018bb_"
}
}
]
},
{
"attributes": [
{
"entity": {
"knowledgeGraphMachineId": "/m/014trl"
}
}
]
}
],
"creatorAttributes": [
{
"entity": {
"knowledgeGraphMachineId": "/m/014trl"
}
}
]
}
}
如需获取基于主题的创作者以及本地创作者,请使用 searchTopics 并
在 supplementalData 中添加 "LOCAL_CREATOR_DATA":
POST https://googleads.googleapis.com/v26/customers/{customer_id}:generateCreatorInsights
{
"customerInsightsGroup": "Spring Skincare Campaign",
"countryLocations": [
{
"geoTargetConstant": "geoTargetConstants/2840"
}
],
"supplementalData": [
"LOCAL_CREATOR_DATA"
],
"searchTopics": {
"entities": [
{
"knowledgeGraphMachineId": "/m/014trl"
}
]
}
}
如需按频道 ID 或帐号获取特定 YouTube 频道的分析洞见,请使用 searchChannels:
POST https://googleads.googleapis.com/v26/customers/{customer_id}:generateCreatorInsights
{
"customerInsightsGroup": "Spring Skincare Campaign",
"countryLocations": [
{
"geoTargetConstant": "geoTargetConstants/2840"
}
],
"searchChannels": {
"youtubeChannels": [
{
"channelId": "UCxxxxxxxxxxxxxxxxxxxxxx"
}
],
"youtubeChannelHandles": [
"@exampleskincare"
]
}
}
如果 GenerateCreatorInsightsResponse 成功,则会返回
creatorInsights[](如果请求了 localCreatorInsights[],则还会返回 LOCAL_CREATOR_DATA):
{
"creatorInsights": [
{
"creatorName": "Example Skincare Creator",
"creatorChannels": [
{
"displayName": "Example Skincare Channel",
"youtubeChannel": {
"channelId": "UCxxxxxxxxxxxxxxxxxxxxxx"
},
"channelUrl": "https://www.youtube.com/channel/UCxxxxxxxxxxxxxxxxxxxxxx",
"handle": "@exampleskincare",
"publishDate": "2020-03-15",
"countryLocation": {
"geoTargetConstant": "geoTargetConstants/2840"
},
"dataSharingConsentGiven": true,
"channelMetrics": {
"subscriberCount": "450000",
"viewsCount": "38200000",
"videoCount": "210",
"likesCount": "1950000",
"commentsCount": "84000",
"engagementRate": 0.056,
"averageViewsPerVideo": 62000.0,
"shortsViewsCount": "14500000",
"shortsVideoCount": "95",
"isActiveShortsCreator": true,
"isActiveLiveStreamCreator": false,
"partnershipOpportunities": [
"CREATOR_PARTNERSHIPS",
"PARTNERSHIP_ADS"
]
}
}
]
}
],
"localCreatorInsights": []
}
生成趋势分析洞见
如需生成趋势分析洞见,请向
GenerateTrendingInsights 方法发送请求。此方法的每秒查询次数 (QPS) 上限为 5。它接受两种类型的输入,具体取决于您是需要受众群体趋势还是主题趋势,并且需要目标国家/地区。
受众群体趋势 (
search_audience): 在search_audience的audience_attributes字段中提供受众群体 属性列表(例如年龄、性别和用户兴趣),并可以选择使用audience_combinations将 属性与布尔值AND/OR逻辑组合。该 API 会返回这些受众群体的趋势分析洞见列表,包括趋势值在比较期内的百分比变化等指标。有权访问
ContentCreatorInsightsService的开发者可以 自动访问ListAudienceInsightsAttributes在AudienceInsightsService中(请参阅 受众群体分析洞见 指南)。AudienceInsightsService中的其他端点需要单独的许可清单。主题趋势 (
search_topics): 在search_topics字段中提供内容主题列表。该 API 会返回这些主题的趋势分析洞见,包括趋势值在比较期内的百分比变化。您还可以通过设置supplemental_data来请求本地创作者或品牌情绪分析洞见。KNOWLEDGE_GRAPH返回的属性ListAudienceInsightsAttributes包含 一个或多个InsightsKnowledgeGraphEntityCapabilities标记;标记为CONTENT_TRENDING_INSIGHTS的实体在GenerateTrendingInsights中受支持作为主题。
补充数据和本地创作者
与生成创作者分析洞见类似,您可以通过将重复字段
supplemental_data设置为LOCAL_CREATOR_DATA或
BRAND_SENTIMENT_DATA,在
趋势分析洞见中请求可选功能:
- 本地创作者 (
LOCAL_CREATOR_DATA): 当您的趋势请求使用search_topics(并且该主题是使用CREATOR_TOPIC_INSIGHTS功能标记的知识图谱实体)时,将supplemental_data设置为LOCAL_CREATOR_DATA会在返回的TrendInsight对象中填充related_local_creators字段,其中包含已同意分享其位置数据的相关本地创作者。本地“发现创作者”功能与sub_country_locations不兼容。 - 品牌情绪 (
BRAND_SENTIMENT_DATA): 当您的趋势请求 使用search_topics且请求的知识图谱实体主题具有BRAND功能时,将supplemental_data设置为BRAND_SENTIMENT_DATA会在返回的TrendInsight对象中填充brand_sentiment_insights字段。
衡量品牌情绪时,系统会使用 Gemini AI 模型分析与品牌相关的 YouTube 视频内容,并将情绪归类为正面、负面或中性。系统只会分析视频内容本身,不包括用户评论。
趋势分析洞见元数据
GenerateTrendingInsights 方法会返回一个
列表,每个对象都包含:TrendInsight
trend_attribute:趋势的主要AudienceInsightsAttributeMetadata。trend_metrics:趋势的指标,例如在比较期内的百分比变化。trend:一个InsightsTrend值(EMERGING、RISING、SUSTAINED或DECLINING),表示趋势的方向。如需了解变化的大小,请参阅trend_metrics.trend_change_percent。trend_data_points:趋势的历史数据点。仅针对使用search_topics的趋势填充。related_videos:与趋势主题相关的热门视频的AudienceInsightsAttributeMetadata对象列表(仅针对使用search_topics的趋势填充)。对于这些属性,嵌套的YouTubeVideoAttributeMetadata会填充视频级元数据(网址、缩略图网址、观看次数和点赞次数)和频道级元数据(频道 ID、名称和网址)。related_creators:与趋势主题相关的创作者的YouTubeCreatorInsights对象列表(仅针对使用search_topics的趋势填充)。related_local_creators:与趋势主题相关的本地创作者的YouTubeCreatorInsights对象列表,这些创作者已同意分享其位置数据。仅当请求了LOCAL_CREATOR_DATA时填充 (请参阅 补充数据、本地创作者和品牌 情绪)。brand_sentiment_insights:趋势的BrandSentimentInsight对象列表 (当请求针对具有BRAND功能的实体使用search_topics并请求BRAND_SENTIMENT_DATA时填充)。每个BrandSentimentInsight对象都包含:month:品牌情绪所代表的月份,采用YYYY-MM格式。has_insufficient_data:是否有足够的数据来计算品牌情绪。sentiment_distributions:正面、负面和中性情绪之间的分布,计算方式为具有每种情绪的品牌对应的视频的观看次数比例。sentiment_summaries:AI 生成的与品牌相关的内容中正面和负面主题的摘要,以及每种情绪的示例视频。摘要仅针对正面和负面情绪生成,不针对中性情绪生成。
GenerateTrendingInsights 请求和响应参考
在以下端点对
ContentCreatorInsightsService调用GenerateTrendingInsights:
POST https://googleads.googleapis.com/v26/customers/{customer_id}:generateTrendingInsights
下表总结了
GenerateTrendingInsightsRequest中的字段:
| 字段路径 | 要求 | 格式和限制 |
|---|---|---|
customer_id |
必填 | 10 位数的客户 ID (string),不含连字符。 |
customer_insights_group |
必填 | 用户定义的要规划的客户或品牌的名称 (string)。 |
country_location |
必填 | 单个国家/地区 LocationInfo (geo_target_constant,例如 "geoTargetConstants/2840")。 |
sub_country_locations[] |
可选 | 国家/地区级 LocationInfo 过滤条件;仅支持 search_audience,且与 LOCAL_CREATOR_DATA 不兼容。 |
search_audience |
criteria (oneof) |
SearchAudience 包含以下内容:• audience_attributes[](必填):age_range、gender、parental_status、income_range(如果未使用 audience_combinations,则还包括 user_interest、entity 或 category)。• audience_combinations[](可选):AND-of-ORs 属性组。 |
search_topics |
criteria (oneof) |
SearchTopics 包含 entities[](AudienceInsightsEntity,其中 knowledge_graph_machine_id 使用 CONTENT_TRENDING_INSIGHTS 标记)。 |
supplemental_data[] |
可选 | ContentCreatorInsightsSupplementalData 值:• LOCAL_CREATOR_DATA:针对具有 CREATOR_TOPIC_INSIGHTS 的 search_topics 实体填充 related_local_creators[]。• BRAND_SENTIMENT_DATA:针对具有 BRAND 的 search_topics 实体填充 brand_sentiment_insights[]。 |
insights_application_info |
可选 | AdditionalApplicationInfo 有关发出请求的应用的元数据。 |
GenerateTrendingInsightsResponse 消息会在 trend_insights[] 中返回
TrendInsight 条目:
TrendInsight 字段 |
类型 | 说明 |
|---|---|---|
trend_attribute |
AudienceInsightsAttributeMetadata |
趋势的主要属性(dimension、display_name、attribute)。 |
trend_metrics |
TrendInsightMetrics |
3 个月比较期内的指标(search_topics 的 views_count 和 views_indexed_value;search_audience 的 audience_share;trend_change_percent)。 |
trend |
InsightsTrend |
趋势的方向(EMERGING、RISING、SUSTAINED 或 DECLINING)。 |
trend_data_points[] |
TrendInsightDataPoint |
每月历史数据(YYYY-MM 格式的 month 和 trend_metrics);针对 search_topics 填充。 |
related_videos[] |
AudienceInsightsAttributeMetadata |
具有 YouTubeVideoAttributeMetadata 的热门视频;针对 search_topics 填充。 |
related_creators[] |
YouTubeCreatorInsights |
与主题相关的创作者;针对 search_topics 填充。 |
related_local_creators[] |
YouTubeCreatorInsights |
已同意的本地创作者;当针对具有 CREATOR_TOPIC_INSIGHTS 的实体请求 LOCAL_CREATOR_DATA 时,针对 search_topics 填充。 |
brand_sentiment_insights[] |
BrandSentimentInsight |
每月品牌情绪(month、has_insufficient_data、sentiment_distributions[]、sentiment_summaries[]);当针对具有 BRAND 功能的实体请求 BRAND_SENTIMENT_DATA 时,针对 search_topics 填充。 |
GenerateTrendingInsights REST 请求和响应示例
以下示例针对知识图谱品牌实体(/g/11example_brand,使用
CONTENT_TRENDING_INSIGHTS、CREATOR_TOPIC_INSIGHTS 和 BRAND 标记)使用 searchTopics 调用
GenerateTrendingInsights,并请求
LOCAL_CREATOR_DATA 和 BRAND_SENTIMENT_DATA:
POST https://googleads.googleapis.com/v26/customers/{customer_id}:generateTrendingInsights
{
"customerInsightsGroup": "Spring Skincare Campaign",
"countryLocation": {
"geoTargetConstant": "geoTargetConstants/2840"
},
"supplementalData": [
"LOCAL_CREATOR_DATA",
"BRAND_SENTIMENT_DATA"
],
"searchTopics": {
"entities": [
{
"knowledgeGraphMachineId": "/g/11example_brand"
}
]
}
}
如果 GenerateTrendingInsightsResponse
成功,则会在 trendInsights[] 中返回 TrendInsight 条目:
{
"trendInsights": [
{
"trendAttribute": {
"dimension": "KNOWLEDGE_GRAPH",
"displayName": "Example Skincare Brand",
"attribute": {
"entity": {
"knowledgeGraphMachineId": "/g/11example_brand"
}
}
},
"trendMetrics": {
"viewsCount": "18500000",
"viewsIndexedValue": "82",
"trendChangePercent": 0.24
},
"trend": "RISING",
"trendDataPoints": [
{
"month": "2026-05",
"trendMetrics": {
"viewsCount": "18500000",
"viewsIndexedValue": "82",
"trendChangePercent": 0.08
}
}
],
"brandSentimentInsights": [
{
"month": "2026-05",
"hasInsufficientData": false,
"sentimentDistributions": [
{
"sentiment": "SENTIMENT_POSITIVE",
"sentimentShare": 0.68
},
{
"sentiment": "SENTIMENT_NEUTRAL",
"sentimentShare": 0.25
},
{
"sentiment": "SENTIMENT_NEGATIVE",
"sentimentShare": 0.07
}
]
}
],
"relatedVideos": [],
"relatedCreators": [],
"relatedLocalCreators": []
}
]
}