YouTube 创作者数据分析

使用 ContentCreatorInsightsService 中的创作者数据分析功能，发现并获取有关 YouTube 创作者的数据分析。 这项服务可帮助代理机构和广告客户找到与其目标受众群体相关的创作者。

该 API 有四个主要功能：

  1. 创作者可发现性：针对一组给定的主题、受众特征、受众群体或创作者属性，查找相关创作者。
  2. 创作者主题数据分析：获取有关制作指定主题内容的相关创作者的数据分析。
  3. 创作者数据分析：获取有关特定 YouTube 频道的数据分析，例如其订阅人数、观看次数和观众特征。
  4. 趋势分析洞见：根据特定受众群体或主题，获取有关特定趋势的分析洞见。

使用基于主题的“发现创作者”功能或热门趋势数据洞见时，您可以通过请求补充数据来发现本地创作者（即在特定国家/地区生活或发布内容，且在该国家/地区有观众的创作者）。您还可以通过请求补充数据，请求针对基于主题的热门数据分析的品牌情感数据分析。

资格要求

GenerateCreatorInsights 是 Google Ads API 的私有组件，提供非独占、免版税的数据许可。已签约的合作伙伴可以使用标准 Google Ads 客户端库来探索 YouTube 创作者和内容。若要满足参与资格，合作伙伴必须满足以下条件：

  • 拥有集成了 Google Ads API 的规划工具或界面。
  • 使用该 API 探索 YouTube 内容和创作者，寻找潜在的广告机会。
  • 完成预筛查评估，以验证资格。
  • 遵守数据使用要求，并定期接受数据审核。
  • 接受 Google Ads API 服务条款和相关数据使用政策。

如需了解详情，请与您的 Google 代表联系。

生成创作者数据分析

如需生成创作者分析洞见，请向 GenerateCreatorInsights 方法发送请求。此方法的限制为每秒查询次数 (QPS)。它接受不同的条件，具体取决于您是希望创作者曝光度、基于主题搜索创作者，还是获取特定频道的创作者数据分析。您必须在 country_locations 中提供目标国家/地区位置。

  1. 创作者曝光度 (search_attributes)：使用 search_attributes 字段提供受众群体属性列表（例如年龄、性别和用户兴趣 [兴趣相似、有购买意向和人生大事受众群体]），以查找受众群体与这些属性匹配的创作者。您还可以提供创作者属性，以过滤出内容符合特定属性的创作者。

    使用 ListAudienceInsightsAttributes 检索可用的受众群体属性，方法是指定所需的维度，例如 KNOWLEDGE_GRAPH 表示感兴趣的主题。如需使用布尔值 AND 和 OR 组来组合属性，请使用 audience_combinations，如复杂的受众群体组合中所述。

  2. 创作者主题数据分析 (search_topics)：使用 search_topics 字段提供内容主题列表。该 API 会返回制作的内容与指定主题相关的创作者。系统会提取 country_locations 中指定的国家/地区的数据（此选项支持每个请求一个国家/地区）。

    search_topics 中受支持的实体必须标记有 CONTENT_TRENDING_INSIGHTS 或 CREATOR_TOPIC_INSIGHTS 功能。使用 ListAudienceInsightsAttributes 检索支持的实体功能。

  3. 创作者数据分析 (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. 第 1 组包含 "Skin care" 和 "Hair care" 的知识图谱实体属性。
  2. 包含 "Cosmetics" 的知识图谱实体属性（例如 /m/014trl）的组 2。

补充数据和本地创作者

默认情况下，系统仅返回核心数据分析数据。您可以通过设置重复字段 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) 会在 creator_channels 中的每个 YouTubeChannelInsights 对象内返回。

YouTubeMetrics 对象包含：

  • 订阅人数、观看次数和视频数量
  • 频道所有视频获得的点赞、分享和评论总数
  • 生命周期内的互动率（总互动次数除以总观看次数）
  • 过去 28 天内每个视频的平均观看次数、点赞次数、分享次数和评论次数
  • 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) 包含 entities[] 的 SearchTopics（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[]（如果请求了 LOCAL_CREATOR_DATA，还会返回 localCreatorInsights[]）：

{
  "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)。它接受两种类型的输入，具体取决于您想要受众群体趋势还是主题趋势，并且需要目标国家/地区位置。

  1. 受众群体趋势 (search_audience)：在 search_audience 的 audience_attributes 字段中提供受众群体属性（例如年龄、性别和用户兴趣）列表，并可选择使用 audience_combinations 将属性与布尔值 AND/OR 逻辑结合使用。API 会返回这些受众群体的趋势分析数据列表，包括趋势值在比较期内的百分比变化等指标。

    有权访问 ContentCreatorInsightsService 的开发者会自动获得对 AudienceInsightsService 中 ListAudienceInsightsAttributes 的访问权限（请参阅受众群体分析指南）。AudienceInsightsService 中的其他端点需要单独的许可清单。

  2. 主题趋势 (search_topics)：在 search_topics 字段中提供内容主题列表。该 API 会返回这些主题的趋势数据分析，包括趋势值在比较期内的变化百分比。您还可以通过设置 supplemental_data 来请求本地创作者或品牌情感分析。

    ListAudienceInsightsAttributes 返回的 KNOWLEDGE_GRAPH 属性包含一个或多个 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 生成的与品牌相关内容中正面和负面主题的摘要，以及每种情感的示例视频。系统只会针对正面和负面观感生成摘要，不会针对中立观感生成摘要。

在以下端点对 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 每月历史数据（month，采用 YYYY-MM 格式和 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 填充。

以下示例使用 searchTopics 为知识图谱品牌实体（/g/11example_brand，标记有 CONTENT_TRENDING_INSIGHTS、CREATOR_TOPIC_INSIGHTS 和 BRAND）调用 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": []
    }
  ]
}
上一页
受众群体分析
下一页
YouTube 基准分析