/services/content_creator_insights_service.proto

--- v18/services/content_creator_insights_service.proto 2025-08-05 14:36:13.000000000 +0000
+++ v19/services/content_creator_insights_service.proto 2025-08-05 14:36:21.000000000 +0000
@@ -54,7 +55,26 @@
   rpc GenerateCreatorInsights(GenerateCreatorInsightsRequest)
       returns (GenerateCreatorInsightsResponse) {
     option (google.api.http) = {
-      post: "/v18/customers/{customer_id=*}:generateCreatorInsights"
+      post: "/v19/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: "/v19/customers/{customer_id=*}:generateTrendingInsights"
       body: "*"
     };
   }
@@ -74,11 +97,26 @@

     // 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.
-    repeated google.ads.googleads.v18.common.AudienceInsightsAttribute
+    // input creator attributes. Attribute entity tagged with
+    // [InsightsKnowledgeGraphEntityCapabilities.CREATOR_ATTRIBUTE][] is
+    // supported. Other attributes including location are not supported.
+    repeated google.ads.googleads.v19.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.v19.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.
@@ -93,12 +131,22 @@
   // user-defined value.
   string customer_insights_group = 2 [(google.api.field_behavior) = REQUIRED];

+  // Required. The countries to search that apply to the criteria.
+  repeated google.ads.googleads.v19.common.LocationInfo country_locations = 6
+      [(google.api.field_behavior) = REQUIRED];
+
   // A criteria used to search for creators and creator insights.
   oneof criteria {
-    // The list of attributes to search for top creators in.
+    // The attributes used to identify top creators. Data fetched is based on
+    // the list of countries specified in [country_locations].
     SearchAttributes search_attributes = 3;

-    // The list of YouTube Channel IDs to fetch creator insights for.
+    // 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;
   }
 }
@@ -103,13 +151,43 @@
   }
 }

-// Response message for [ContentCreatorInsightsService.GenerateCreatorInsights]
+// Response message for
+// [ContentCreatorInsightsService.GenerateCreatorInsights][google.ads.googleads.v19.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];
+
+  // Required. The country to find trends in.
+  google.ads.googleads.v19.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.
@@ -126,6 +204,12 @@

   // The total number of views.
   int64 views_count = 2;
+
+  // The total number of videos.
+  int64 video_count = 3;
+
+  // When true, this channel has published a shorts video in the last 90 days.
+  bool is_active_shorts_creator = 4;
 }

 // YouTube Channel insights, and its metadata (such as channel name and channel
@@ -135,21 +219,70 @@
   string display_name = 1;

   // The YouTube Channel ID.
-  google.ads.googleads.v18.common.YouTubeChannelInfo youtube_channel = 2;
+  google.ads.googleads.v19.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 metrics for a YouTube Channel.
   YouTubeMetrics channel_metrics = 3;

-  // The types of audiences and demographics associated with a channel's main
-  // audience. Audiences and demographics will have a breakdown of subscriber
-  // share across dimensions of the same value.
-  repeated google.ads.googleads.v18.common.AudienceInsightsAttributeMetadata
-      channel_audience_demographics = 4;
+  // 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.v19.common.AudienceInsightsAttributeMetadata
+      channel_audience_attributes = 7;

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

+  // The top 10 videos for the channel.
+  repeated google.ads.googleads.v19.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.v19.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.v19.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.v19.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.v19.enums.InsightsTrendEnum.InsightsTrend trend = 3;
+}
+
+// Metrics associated with a trend insight.
+message TrendInsightMetrics {
+  // The number of views for this trend.
+  int64 views_count = 1;
+}