--- v18/services/content_creator_insights_service.proto 2024-10-16 17:56:30.000000000 +0000 +++ v19/services/content_creator_insights_service.proto 2025-02-24 15:30:13.000000000 +0000 @@ -1,155 +1,288 @@ // Copyright 2024 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.v18.services; +package google.ads.googleads.v19.services; -import "google/ads/googleads/v18/common/audience_insights_attribute.proto"; -import "google/ads/googleads/v18/common/criteria.proto"; +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/api/annotations.proto"; import "google/api/client.proto"; import "google/api/field_behavior.proto"; -option csharp_namespace = "Google.Ads.GoogleAds.V18.Services"; -option go_package = "google.golang.org/genproto/googleapis/ads/googleads/v18/services;services"; +option csharp_namespace = "Google.Ads.GoogleAds.V19.Services"; +option go_package = "google.golang.org/genproto/googleapis/ads/googleads/v19/services;services"; option java_multiple_files = true; option java_outer_classname = "ContentCreatorInsightsServiceProto"; -option java_package = "com.google.ads.googleads.v18.services"; +option java_package = "com.google.ads.googleads.v19.services"; option objc_class_prefix = "GAA"; -option php_namespace = "Google\\Ads\\GoogleAds\\V18\\Services"; -option ruby_package = "Google::Ads::GoogleAds::V18::Services"; +option php_namespace = "Google\\Ads\\GoogleAds\\V19\\Services"; +option ruby_package = "Google::Ads::GoogleAds::V19::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: "/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: "*" }; } } -// Request message for [ContentCreatorInsightsService.GenerateCreatorInsights] +// Request message for +// [ContentCreatorInsightsService.GenerateCreatorInsights][google.ads.googleads.v19.services.ContentCreatorInsightsService.GenerateCreatorInsights]. message GenerateCreatorInsightsRequest { // The audience attributes (such as Age, Gender, Affinity, and In-Market) and - // creator attributes (such as creator location and creator's content topics) - // used to search for top creators. + // 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. - repeated google.ads.googleads.v18.common.AudienceInsightsAttribute + // 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 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. - 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. - repeated google.ads.googleads.v18.common.YouTubeChannelInfo + repeated google.ads.googleads.v19.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]; + // 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; } } -// 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. 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. + bool is_active_shorts_creator = 4; } // 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.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.