--- v18/services/content_creator_insights_service.proto 2025-02-24 15:48:55.000000000 +0000 +++ v19/services/content_creator_insights_service.proto 2025-02-24 15:49:00.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; +}
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-02-24 UTC.