--- v19/services/content_creator_insights_service.proto 2025-04-16 17:10:13.000000000 +0000 +++ v20/services/content_creator_insights_service.proto 2025-06-04 18:55:28.000000000 +0000 @@ -1,288 +1,342 @@ // 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.v19.services; +package google.ads.googleads.v20.services; -import "google/ads/googleads/v19/common/audience_insights_attribute.proto"; -import "google/ads/googleads/v19/common/criteria.proto"; -import "google/ads/googleads/v19/enums/insights_trend.proto"; +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/api/annotations.proto"; import "google/api/client.proto"; import "google/api/field_behavior.proto"; -option csharp_namespace = "Google.Ads.GoogleAds.V19.Services"; -option go_package = "google.golang.org/genproto/googleapis/ads/googleads/v19/services;services"; +option csharp_namespace = "Google.Ads.GoogleAds.V20.Services"; +option go_package = "google.golang.org/genproto/googleapis/ads/googleads/v20/services;services"; option java_multiple_files = true; option java_outer_classname = "ContentCreatorInsightsServiceProto"; -option java_package = "com.google.ads.googleads.v19.services"; +option java_package = "com.google.ads.googleads.v20.services"; option objc_class_prefix = "GAA"; -option php_namespace = "Google\\Ads\\GoogleAds\\V19\\Services"; -option ruby_package = "Google::Ads::GoogleAds::V19::Services"; +option php_namespace = "Google\\Ads\\GoogleAds\\V20\\Services"; +option ruby_package = "Google::Ads::GoogleAds::V20::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: "/v19/customers/{customer_id=*}:generateCreatorInsights" + post: "/v20/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" + post: "/v20/customers/{customer_id=*}:generateTrendingInsights" body: "*" }; } } // Request message for -// [ContentCreatorInsightsService.GenerateCreatorInsights][google.ads.googleads.v19.services.ContentCreatorInsightsService.GenerateCreatorInsights]. +// [ContentCreatorInsightsService.GenerateCreatorInsights][google.ads.googleads.v20.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, - // parental_status, and income_range are supported. Attribute location is - // not supported. - repeated google.ads.googleads.v19.common.AudienceInsightsAttribute + // device, parental_status, and income_range are supported. Attribute + // location is not supported. + repeated google.ads.googleads.v20.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.v19.common.AudienceInsightsAttribute + repeated google.ads.googleads.v20.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 + repeated google.ads.googleads.v20.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.v19.common.YouTubeChannelInfo + repeated google.ads.googleads.v20.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 + insights_application_info = 8 [(google.api.field_behavior) = OPTIONAL]; + // Required. The countries to search that apply to the criteria. - repeated google.ads.googleads.v19.common.LocationInfo country_locations = 6 + repeated google.ads.googleads.v20.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 = + 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 specified in [country_locations]. + // 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.v19.services.ContentCreatorInsightsService.GenerateCreatorInsights]. +// [ContentCreatorInsightsService.GenerateCreatorInsights][google.ads.googleads.v20.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 + insights_application_info = 6 [(google.api.field_behavior) = OPTIONAL]; + // Required. The country to find trends in. - google.ads.googleads.v19.common.LocationInfo country_location = 3 + google.ads.googleads.v20.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; - // When true, this channel has published a shorts video in the last 90 days. + // 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.v19.common.YouTubeChannelInfo youtube_channel = 2; + google.ads.googleads.v20.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 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 + repeated google.ads.googleads.v20.common.AudienceInsightsAttributeMetadata channel_audience_attributes = 7; // The attributes associated with the content made by a channel. - repeated google.ads.googleads.v19.common.AudienceInsightsAttributeMetadata + repeated google.ads.googleads.v20.common.AudienceInsightsAttributeMetadata channel_attributes = 5; // The top 10 videos for the channel. - repeated google.ads.googleads.v19.common.AudienceInsightsAttributeMetadata + repeated google.ads.googleads.v20.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 + repeated google.ads.googleads.v20.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 + repeated google.ads.googleads.v20.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 + google.ads.googleads.v20.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; + google.ads.googleads.v20.enums.InsightsTrendEnum.InsightsTrend trend = 3; } // Metrics associated with a trend insight. message TrendInsightMetrics { // The number of views for this trend. int64 views_count = 1; }
/services/content_creator_insights_service.proto
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-08-20 UTC.