To discuss and provide feedback on our products, join the official Google Ads Discord channel in the Google Advertising and Measurement Community server.
/services/content_creator_insights_service.proto

--- v20/services/content_creator_insights_service.proto 2025-06-04 18:55:28.000000000 +0000
+++ v21/services/content_creator_insights_service.proto 2025-08-05 14:28:35.000000000 +0000
@@ -1,342 +1,365 @@
 // Copyright 2025 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
 // You may obtain a copy of the License at
 //
 //     http://www.apache.org/licenses/LICENSE-2.0
 //
 // Unless required by applicable law or agreed to in writing, software
 // distributed under the License is distributed on an "AS IS" BASIS,
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.

 syntax = "proto3";

-package google.ads.googleads.v20.services;
+package google.ads.googleads.v21.services;

-import "google/ads/googleads/v20/common/additional_application_info.proto";
-import "google/ads/googleads/v20/common/audience_insights_attribute.proto";
-import "google/ads/googleads/v20/common/criteria.proto";
-import "google/ads/googleads/v20/enums/insights_trend.proto";
+import "google/ads/googleads/v21/common/additional_application_info.proto";
+import "google/ads/googleads/v21/common/audience_insights_attribute.proto";
+import "google/ads/googleads/v21/common/criteria.proto";
+import "google/ads/googleads/v21/enums/insights_trend.proto";
 import "google/api/annotations.proto";
 import "google/api/client.proto";
 import "google/api/field_behavior.proto";

-option csharp_namespace = "Google.Ads.GoogleAds.V20.Services";
-option go_package = "google.golang.org/genproto/googleapis/ads/googleads/v20/services;services";
+option csharp_namespace = "Google.Ads.GoogleAds.V21.Services";
+option go_package = "google.golang.org/genproto/googleapis/ads/googleads/v21/services;services";
 option java_multiple_files = true;
 option java_outer_classname = "ContentCreatorInsightsServiceProto";
-option java_package = "com.google.ads.googleads.v20.services";
+option java_package = "com.google.ads.googleads.v21.services";
 option objc_class_prefix = "GAA";
-option php_namespace = "Google\\Ads\\GoogleAds\\V20\\Services";
-option ruby_package = "Google::Ads::GoogleAds::V20::Services";
+option php_namespace = "Google\\Ads\\GoogleAds\\V21\\Services";
+option ruby_package = "Google::Ads::GoogleAds::V21::Services";

 // Proto file describing the content creator insights service.

 // Content Creator Insights Service helps users find information about YouTube
 // Creators and their content and how these creators and their audiences can be
 // reached with Google Ads. Accessible to allowlisted customers only.
 service ContentCreatorInsightsService {
   option (google.api.default_host) = "googleads.googleapis.com";
   option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/adwords";

   // Returns insights for a collection of YouTube Creators and Channels.
   //
   // List of thrown errors:
   //   [AuthenticationError]()
   //   [AuthorizationError]()
   //   [FieldError]()
   //   [HeaderError]()
   //   [InternalError]()
   //   [QuotaError]()
   //   [RangeError]()
   //   [RequestError]()
   rpc GenerateCreatorInsights(GenerateCreatorInsightsRequest)
       returns (GenerateCreatorInsightsResponse) {
     option (google.api.http) = {
-      post: "/v20/customers/{customer_id=*}:generateCreatorInsights"
+      post: "/v21/customers/{customer_id=*}:generateCreatorInsights"
       body: "*"
     };
   }

   // Returns insights for trending content on YouTube.
   //
   // List of thrown errors:
   //   [AuthenticationError]()
   //   [AuthorizationError]()
   //   [FieldError]()
   //   [HeaderError]()
   //   [InternalError]()
   //   [QuotaError]()
   //   [RangeError]()
   //   [RequestError]()
   rpc GenerateTrendingInsights(GenerateTrendingInsightsRequest)
       returns (GenerateTrendingInsightsResponse) {
     option (google.api.http) = {
-      post: "/v20/customers/{customer_id=*}:generateTrendingInsights"
+      post: "/v21/customers/{customer_id=*}:generateTrendingInsights"
       body: "*"
     };
   }
 }

 // Request message for
-// [ContentCreatorInsightsService.GenerateCreatorInsights][google.ads.googleads.v20.services.ContentCreatorInsightsService.GenerateCreatorInsights].
+// [ContentCreatorInsightsService.GenerateCreatorInsights][google.ads.googleads.v21.services.ContentCreatorInsightsService.GenerateCreatorInsights].
 message GenerateCreatorInsightsRequest {
   // The audience attributes (such as Age, Gender, Affinity, and In-Market) and
   // creator attributes (such as creator's content topics) used to search
   // for top creators.
   message SearchAttributes {
     // Optional. Audience attributes that describe an audience of viewers. This
     // is used to search for creators whose own viewers match the input
     // audience. Attributes age_range, gender, user_interest, entity, category,
     // device, parental_status, and income_range are supported. Attribute
     // location is not supported.
-    repeated google.ads.googleads.v20.common.AudienceInsightsAttribute
+    repeated google.ads.googleads.v21.common.AudienceInsightsAttribute
         audience_attributes = 1 [(google.api.field_behavior) = OPTIONAL];

     // Optional. Creator attributes that describe a collection of types of
     // content. This is used to search for creators whose content matches the
-    // input creator attributes. Attribute entity tagged with
-    // [InsightsKnowledgeGraphEntityCapabilities.CREATOR_ATTRIBUTE][] is
-    // supported. Other attributes including location are not supported.
-    repeated google.ads.googleads.v20.common.AudienceInsightsAttribute
+    // input creator attributes. Only Knowledge Graph Entities tagged with
+    // [InsightsKnowledgeGraphEntityCapabilities.CREATOR_ATTRIBUTE][] are
+    // supported. Use
+    // [AudienceInsightsService.ListAudienceInsightsAttributes][google.ads.googleads.v21.services.AudienceInsightsService.ListAudienceInsightsAttributes]
+    // to get the list of supported entities. Other attributes including
+    // location are not supported.
+    repeated google.ads.googleads.v21.common.AudienceInsightsAttribute
         creator_attributes = 2 [(google.api.field_behavior) = OPTIONAL];
   }

   // The brand used to search for top creators.
   message SearchBrand {
     // Optional. One or more Knowledge Graph Entities that represent the brand
     // for which to find insights.
-    repeated google.ads.googleads.v20.common.AudienceInsightsAttribute
+    repeated google.ads.googleads.v21.common.AudienceInsightsAttribute
         brand_entities = 1 [(google.api.field_behavior) = OPTIONAL];

     // Optional. When true, we will expand the search to beyond just the
     // entities specified in [brand_entities] to other related knowledge graph
     // entities similar to the brand. The default value is `false`.
     bool include_related_topics = 2 [(google.api.field_behavior) = OPTIONAL];
   }

   // A collection of YouTube Channels.
   message YouTubeChannels {
     // Optional. The YouTube Channel IDs to fetch creator insights for.
-    repeated google.ads.googleads.v20.common.YouTubeChannelInfo
+    repeated google.ads.googleads.v21.common.YouTubeChannelInfo
         youtube_channels = 1 [(google.api.field_behavior) = OPTIONAL];
   }

   // Required. The ID of the customer.
   string customer_id = 1 [(google.api.field_behavior) = REQUIRED];

   // Required. The name of the customer being planned for.  This is a
   // user-defined value.
   string customer_insights_group = 2 [(google.api.field_behavior) = REQUIRED];

   // Optional. Additional information on the application issuing the request.
-  google.ads.googleads.v20.common.AdditionalApplicationInfo
+  google.ads.googleads.v21.common.AdditionalApplicationInfo
       insights_application_info = 8 [(google.api.field_behavior) = OPTIONAL];

   // Required. The countries to search that apply to the criteria.
-  repeated google.ads.googleads.v20.common.LocationInfo country_locations = 6
+  repeated google.ads.googleads.v21.common.LocationInfo country_locations = 6
       [(google.api.field_behavior) = REQUIRED];

   // The sub-country geographic locations to search that apply to the criteria.
   // Only supported for [SearchAttributes] criteria.
-  repeated google.ads.googleads.v20.common.LocationInfo sub_country_locations =
+  repeated google.ads.googleads.v21.common.LocationInfo sub_country_locations =
       7;

   // A criteria used to search for creators and creator insights.
   oneof criteria {
     // The attributes used to identify top creators. Data fetched is based on
     // the list of countries or sub-country locations specified in
     // [country_locations] or [sub_country_locations].
     SearchAttributes search_attributes = 3;

     // A brand used to search for top creators. Data fetched is based on the
     // list of countries specified in [country_locations].
     SearchBrand search_brand = 5;

     // YouTube Channel IDs for Creator Insights. Data fetched for channels is
     // based on the list of countries specified in [country_locations].
     YouTubeChannels search_channels = 4;
   }
 }

 // Response message for
-// [ContentCreatorInsightsService.GenerateCreatorInsights][google.ads.googleads.v20.services.ContentCreatorInsightsService.GenerateCreatorInsights].
+// [ContentCreatorInsightsService.GenerateCreatorInsights][google.ads.googleads.v21.services.ContentCreatorInsightsService.GenerateCreatorInsights].
 message GenerateCreatorInsightsResponse {
   // A collection of YouTube Creators, each containing a collection of YouTube
   // Channels maintained by the YouTube Creator.
   repeated YouTubeCreatorInsights creator_insights = 1;
 }

 // Request message for [ContentCreatorInsightsService.GenerateTrendingInsights]
 message GenerateTrendingInsightsRequest {
   // Required. The ID of the customer.
   string customer_id = 1 [(google.api.field_behavior) = REQUIRED];

   // Required. The name of the customer being planned for. This is a
   // user-defined value.
   string customer_insights_group = 2 [(google.api.field_behavior) = REQUIRED];

   // Optional. Additional information on the application issuing the request.
-  google.ads.googleads.v20.common.AdditionalApplicationInfo
+  google.ads.googleads.v21.common.AdditionalApplicationInfo
       insights_application_info = 6 [(google.api.field_behavior) = OPTIONAL];

   // Required. The country to find trends in.
-  google.ads.googleads.v20.common.LocationInfo country_location = 3
+  google.ads.googleads.v21.common.LocationInfo country_location = 3
       [(google.api.field_behavior) = REQUIRED];

   // The criteria used to search for trending content.
   oneof criteria {
     // An audience to search for trending content in.
     SearchAudience search_audience = 4;

     // Content topics to return trend information for.
     SearchTopics search_topics = 5;
   }
 }

 // Response message for [ContentCreatorInsightsService.GenerateTrendingInsights]
 message GenerateTrendingInsightsResponse {
   // The list of trending insights for the given criteria.
   repeated TrendInsight trend_insights = 1;
 }

 // A YouTube creator and the insights for this creator.
 message YouTubeCreatorInsights {
   // The name of the creator.
   string creator_name = 1;

   // The list of YouTube Channels
   repeated YouTubeChannelInsights creator_channels = 2;
 }

 // YouTube Channel metrics.
 message YouTubeMetrics {
   // The number of subscribers.
   int64 subscriber_count = 1;

   // The total number of views.
   int64 views_count = 2;

   // The total number of videos.
   int64 video_count = 3;

   // The total number of likes across all videos of this channel.
   int64 likes_count = 5;

   // The total number of shares across all videos of this channel.
   int64 shares_count = 6;

   // The total number of comments across all videos of this channel.
   int64 comments_count = 7;

   // The lifetime engagement rate of this channel. The value is computed as the
   // total number of likes, shares, and comments across all videos divided by
   // the total number of videos.
   double engagement_rate = 8;

   // The average number of views per video in the last 28 days.
   double average_views_per_video = 9;

   // The average number of likes per video in the last 28 days.
   double average_likes_per_video = 10;

   // The average number of shares per video in the last 28 days.
   double average_shares_per_video = 11;

   // The average number of comments per video in the last 28 days.
   double average_comments_per_video = 12;

   // The total number of views across all Shorts videos of this channel.
   int64 shorts_views_count = 13;

   // The total number of Shorts videos.
   int64 shorts_video_count = 14;

   // When true, this channel has published a Shorts video in the last 90 days.
   bool is_active_shorts_creator = 4;

   // When true, this creator can be partnered with to create original branded
   // content using the Google Ads creator partnership platform, BrandConnect.
   //
   // See https://support.google.com/google-ads/answer/13828964 for more
   // information about BrandConnect.
   bool is_brand_connect_creator = 15;
 }

 // YouTube Channel insights, and its metadata (such as channel name and channel
 // ID), returned for a creator insights response.
 message YouTubeChannelInsights {
   // The name of the YouTube Channel.
   string display_name = 1;

   // The YouTube Channel ID.
-  google.ads.googleads.v20.common.YouTubeChannelInfo youtube_channel = 2;
+  google.ads.googleads.v21.common.YouTubeChannelInfo youtube_channel = 2;

   // URL for the channel in the form of
   // https://www.youtube.com/channel/{channel_id}.
   string channel_url = 9;

   // Description of the channel.
   string channel_description = 10;

+  // The unique, short, and user-visible identifier for the channel starting
+  // with an "@" symbol (such as "@youtubecreators"). See
+  // https://support.google.com/youtube/answer/11585688 for more information.
+  string handle = 11;
+
+  // URL for a 240px by 240px thumbnail image of the channel.
+  string thumbnail_url = 12;
+
+  // The date that the channel was created. Formatted as "yyyy-mm-dd".
+  string publish_date = 13;
+
+  // The country with which the channel is associated.
+  google.ads.googleads.v21.common.LocationInfo country_location = 14;
+
   // The metrics for a YouTube Channel.
   YouTubeMetrics channel_metrics = 3;

   // The types of audiences and demographics linked to the channel's main
   // audience. Audiences and demographics have a breakdown of subscriber share
   // across dimensions of the same value, such as Age Range, Gender, and User
   // Interest.
-  repeated google.ads.googleads.v20.common.AudienceInsightsAttributeMetadata
+  repeated google.ads.googleads.v21.common.AudienceInsightsAttributeMetadata
       channel_audience_attributes = 7;

   // The attributes associated with the content made by a channel.
-  repeated google.ads.googleads.v20.common.AudienceInsightsAttributeMetadata
+  repeated google.ads.googleads.v21.common.AudienceInsightsAttributeMetadata
       channel_attributes = 5;

   // The top 10 videos for the channel.
-  repeated google.ads.googleads.v20.common.AudienceInsightsAttributeMetadata
+  repeated google.ads.googleads.v21.common.AudienceInsightsAttributeMetadata
       top_videos = 8;

   // Metadata string associated with the type of channel.
   string channel_type = 6;
 }

 // A collection of audience attributes that describe an audience of viewers.
 // This is used to search for topics trending for the defined audience.
 message SearchAudience {
   // Required. Audience attributes that describe an audience of viewers. This is
   // used to search for topics trending for the defined audience.
-  repeated google.ads.googleads.v20.common.AudienceInsightsAttribute
+  repeated google.ads.googleads.v21.common.AudienceInsightsAttribute
       audience_attributes = 1 [(google.api.field_behavior) = REQUIRED];
 }

 // A collection of content topics to return trend information for.
 message SearchTopics {
   // Required. A list of knowledge graph entities to retrieve trend information
   // for. Supported entities are tagged with
   // [InsightsKnowledgeGraphEntityCapabilities.CONTENT_TRENDING_INSIGHTS][].
-  repeated google.ads.googleads.v20.common.AudienceInsightsEntity entities = 1
+  repeated google.ads.googleads.v21.common.AudienceInsightsEntity entities = 1
       [(google.api.field_behavior) = REQUIRED];
 }

 // A trend insight for a given attribute.
 message TrendInsight {
   // The attribute this trend is for.
-  google.ads.googleads.v20.common.AudienceInsightsAttributeMetadata
+  google.ads.googleads.v21.common.AudienceInsightsAttributeMetadata
       trend_attribute = 1;

   // Metrics associated with this trend.
   TrendInsightMetrics trend_metrics = 2;

   // The direction of trend (such as RISING or DECLINING).
-  google.ads.googleads.v20.enums.InsightsTrendEnum.InsightsTrend trend = 3;
+  google.ads.googleads.v21.enums.InsightsTrendEnum.InsightsTrend trend = 3;
 }

 // Metrics associated with a trend insight.
 message TrendInsightMetrics {
-  // The number of views for this trend.
+  // The number of views for this trend. This is only populated for SearchTopics
+  // requests.
   int64 views_count = 1;
+
+  // The fraction (from 0 to 1 inclusive) of the requested audience that has
+  // has searched or viewed this trend. This is only populated for
+  // SearchAudience requests.
+  double audience_share = 2;
 }
/services/content_creator_insights_service.proto Stay organized with collections Save and categorize content based on your preferences.

/services/content_creator_insights_service.proto
