YouTube creator insights

  • The creator insights feature, currently in beta and available only to developers on an allowlist, helps agencies and advertisers find relevant YouTube creators.

  • The API offers four main functions: Creator Discoverability, Creator Brand Insights, Creator Insights, and Trending Insights.

  • To use the API, partners must meet eligibility requirements including having a planning tool, using the API for advertising opportunities, completing an assessment, following data usage requirements, and signing agreements.

  • You can generate creator insights by sending a request to the ContentCreatorInsightsService.GenerateCreatorInsights method with inputs based on whether you need creator discoverability, creator brand insights, or specific channel insights.

  • Trending insights can be generated using the ContentCreatorInsightsService.GenerateTrendingInsights method by providing audience attributes or content topics for a specific country.

Discover and fetch insights about YouTube creators with the creator insights feature. This can be useful for agencies and advertisers who want to find creators who are relevant to their target audience.

The API has four main functions:

  1. Creator discoverability: Find relevant creators for a given set of topics, demographics, audiences, or creator attributes.
  2. Creator topic insights: Fetch insights about relevant creators who make content about specified topics.
  3. Creator insights: Fetch insights about specific YouTube channels, such as their subscriber count, view count, and audience demographics.
  4. Trending insights: Fetch insights about specific trends, based on specific audiences or topics.

Local creator discovery (finding creators who are based in or post from a given country and are viewed in that country) is supported when using topic-based creator discovery or trending insights by requesting supplemental data.

Eligibility requirements

GenerateCreatorInsights is a private component of the Google Ads API offered with a non-exclusive, royalty-free data license. Signed partners can use the standard Google Ads client libraries to explore YouTube creators and content. To be eligible, partners must satisfy the following conditions:

  • Have a planning tool or user interface that will integrate the Google Ads API.
  • Use the API to explore YouTube content and creators for potential advertising opportunities.
  • Complete a pre-screen assessment to ensure eligibility.
  • Follow data usage requirements and be willing to undergo periodic data audits.
  • Sign a data-licensing agreement that legally enforces data usage requirements.
  • Accept the Google Ads API terms of service.

Contact your Google representative for more information.

Generate creator insights

To generate creator insights, send a request to the GenerateCreatorInsights method. This method has a limit of 5 queries per second (QPS). It takes different types of input depending on if you want to do creator discoverability, search relevant creators by topics, or get creator insights. You must provide the country locations where you want to get data from.

  1. Creator discoverability: You can provide a list of audience attributes, such as age, gender, and user interests (including affinity, in-market, and life event audiences). The API returns a list of creators whose audiences match those attributes. You can also provide creator attributes to filter for creators whose content specifically matches your inputted creator attributes.

    You can retrieve available audience attributes using ListAudienceInsightsAttributes, by providing the dimensions for which you want attributes, such as KNOWLEDGE_GRAPH for topics of interest.

    As of Google Ads API v23, you can specify complex audience attribute relationships using audience_combinations. This field lets you define audiences with boolean logic (AND/OR) that is not possible with audience_attributes.

    While audience_attributes is suitable for targeting based on a list of unioned (combined with OR) attributes (e.g., users interested in "sports" OR "travel" OR ...), audience_combinations offers more granular control. Each InsightsAudienceAttributeGroup within audience_combinations combines attributes with a logical OR. These groups are then combined with a logical AND.

    For example, to target an audience interested in ("Skin care" OR "Hair care") AND also in "Cosmetics", you would use two InsightsAudienceAttributeGroup items in audience_combinations. "Skin care", "Hair care", and "Cosmetics" are topics of interest, represented by Knowledge Graph entities (for example, /m/014trl for Cosmetics). The first group would contain Knowledge Graph entity attributes for "Skin care" and "Hair care", and the second group would contain the Knowledge Graph entity attribute for "Cosmetics".

    Note that if you specify Knowledge Graph entities, Product & Service Categories, or user interests in audience_attributes, you cannot use audience_combinations. If you use audience_combinations, you must specify these attributes within audience_combinations and not in audience_attributes; however, you can still use audience_attributes for other attribute types such as demographics in conjunction with audience_combinations.

  2. Creator topic insights: Provide a list of content topics using the search_topics field. The API returns relevant creators who make content about the specified topics. Data fetched is based on the country specified in country_locations. Note that this option allows searching for only one country.

    Supported entities in the SearchTopics field must be tagged with either the CONTENT_TRENDING_INSIGHTS or CREATOR_TOPIC_INSIGHTS capability. Use the ListAudienceInsightsAttributes method to retrieve supported entity capabilities.

    Note: The search_brand option is deprecated starting in v24.2 and is fully removed in the v25 release. Users should transition to using search_topics instead.

  3. Creator insights: Provide a list of YouTube channel IDs using the search_channels field. The API returns insights about those specific channels.

Supplemental data and local creators

By default, only core insight data is returned. You can request optional features and additional data in your response by setting the repeated field supplemental_data.

For example, you can request local creator data by adding the LOCAL_CREATOR_DATA enum value to the supplemental_data field. If you are searching for creators using search_topics (and the topic is a Knowledge Graph entity tagged with the CREATOR_TOPIC_INSIGHTS capability), the API will populate the local_creator_insights field in the response with local creators who have consented to share their location data.

Note the following specifications for local creator discovery:

  • Definition: "Local creators" are creators that are based in or post from the selected country and are viewed in that country.
  • Constraint: Local creator discovery is not supported when sub_country_locations is set in the request.
  • Capabilities: You can retrieve the list of supported Knowledge Graph entities and their capabilities using ListAudienceInsightsAttributes.

The generateCreatorInsights method returns a GenerateCreatorInsightsResponse object. This object contains the following fields:

  • creator_insights: A list of YouTubeCreatorInsights objects matching your core criteria.
  • local_creator_insights: A list of YouTubeCreatorInsights objects for local creators. This is only populated if LOCAL_CREATOR_DATA was requested and the criteria used was search_topics.

Each YouTubeCreatorInsights object contains the following information about a creator:

  • Creator name
  • YouTube channel
  • Total creator metrics
  • List of YouTube channel insights

The [YouTubeMetrics][YouTubeMetrics] object contains the following metrics:

To identify if a creator is eligible for original branded content partnerships, check partnership_opportunities; a creator is eligible if the list contains the CREATOR_PARTNERSHIPS value.

The YouTubeChannelInsights object contains the following information about a YouTube channel:

  • Channel name
  • Channel ID
  • Channel URL
  • Channel description
  • Channel metrics
  • Channel audience attributes (such as age, gender, and user interest breakdown)
  • Top videos
  • Channel type
  • Languages associated with the channel content
  • Relevance score (for topic trend searches only)

To generate trending insights, send a request to the GenerateTrendingInsights method. This method has a limit of 5 queries per second (QPS). It takes two types of input depending on if you want to get audience trends or topic trends. You must provide the specific country location where you want to get trends from.

  1. Audience trends: You can provide a list of audience attributes, such as age, gender, and user interests (including affinity, in-market, and life event audiences). The API returns a list of trending insights for those audiences, including metrics such as the percentage change in the trend's value over the comparison period.

    You can retrieve available audience attributes using ListAudienceInsightsAttributes, by providing the dimensions for which you want attributes, such as KNOWLEDGE_GRAPH for topics of interest.

    KNOWLEDGE_GRAPH attributes will have one or more InsightsKnowledgeGraphEntityCapabilities tags. Attributes supported for Trending Insights will have relevant tags in their response metadata.

    Note that developers with access to ContentCreatorInsightsService will also have automatic access to AudienceInsightsService.ListAudienceInsightsAttributes. Other endpoints in AudienceInsightsService require an independent allowlist process.

    Additional documentation on ListAudienceInsightsAttributes can be found in the Audience Insights guide.

  2. Audience trends: You can provide a list of audience attributes, such as age, gender, and user interests (including affinity, in-market, and life event audiences). The API returns a list of trending insights for those audiences, including metrics such as the percentage change in the trend's value over the comparison period.

    You can retrieve available audience attributes using the ListAudienceInsightsAttributes method, by providing the dimensions for which you want attributes, such as KNOWLEDGE_GRAPH for topics of interest.

    As of Google Ads API v23, you can specify complex audience attribute relationships using audience_combinations. This field lets you define audiences with boolean logic (AND/OR) that is not possible with audience_attributes.

    While audience_attributes is suitable for targeting based on a list of unioned (combined with OR) attributes (e.g., users interested in "sports" OR "travel" OR ...), audience_combinations offers more granular control. Each InsightsAudienceAttributeGroup within audience_combinations combines attributes with a logical OR. These groups are then combined with a logical AND.

    For example, to target an audience interested in ("Skin care" OR "Hair care") AND also in "Cosmetics", you would use two InsightsAudienceAttributeGroup items in audience_combinations. "Skin care", "Hair care", and "Cosmetics" are topics of interest, represented by Knowledge Graph entities (for example, /m/014trl for Cosmetics). The first group would contain Knowledge Graph entity attributes for "Skin care" and "Hair care", and the second group would contain the Knowledge Graph entity attribute for "Cosmetics".

    Note that if you specify Knowledge Graph entities, Product & Service Categories, or user interests in audience_attributes, you cannot use audience_combinations. If you use audience_combinations, you must specify these attributes within audience_combinations and not in audience_attributes; however, you can still use audience_attributes for other attribute types such as demographics in conjunction with audience_combinations.

  3. Topic trends: Provide a list of content topics. The API returns a list of trending insights for those topics, including metrics such as the percentage change in the trend's value over the comparison period.

Similar to generating creator insights, you can request optional features in trending insights by setting the repeated field supplemental_data to LOCAL_CREATOR_DATA.

If your trending request uses search_topics, this will populate the related_local_creators field on the returned TrendInsight objects with related local creators for the requested topic who have consented to share their location data. Local creator discovery is subject to the same definition and constraints (such as being incompatible with sub_country_locations).

Previous
Audience insights