// Copyright 2026 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.v24.services;

import "google/ads/googleads/v24/common/additional_application_info.proto";
import "google/ads/googleads/v24/common/audience_insights_attribute.proto";
import "google/ads/googleads/v24/common/criteria.proto";
import "google/ads/googleads/v24/enums/insights_trend.proto";
import "google/ads/googleads/v24/enums/partnership_opportunity.proto";
import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";

option csharp_namespace = "Google.Ads.GoogleAds.V24.Services";
option go_package = "google.golang.org/genproto/googleapis/ads/googleads/v24/services;services";
option java_multiple_files = true;
option java_outer_classname = "ContentCreatorInsightsServiceProto";
option java_package = "com.google.ads.googleads.v24.services";
option objc_class_prefix = "GAA";
option php_namespace = "Google\\Ads\\GoogleAds\\V24\\Services";
option ruby_package = "Google::Ads::GoogleAds::V24::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: "/v24/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: "/v24/customers/{customer_id=*}:generateTrendingInsights"
      body: "*"
    };
  }
}

// Request message for
// [ContentCreatorInsightsService.GenerateCreatorInsights][google.ads.googleads.v24.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. The returned creators are sorted based on likelihood that
  // your audience watches the creator, relative to the general population (most
  // likely is returned first).
  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. Attributes user_interest, entity, and category
    // can only be set in audience_attributes when audience_combinations is
    // unused.
    repeated google.ads.googleads.v24.common.AudienceInsightsAttribute
        audience_attributes = 1 [(google.api.field_behavior) = OPTIONAL];

    // Optional. A list of audience attribute groups consisting of one or more
    // Knowledge Graph entities, Product & Service Categories and user interests
    // that describes an audience. The groups have a logical AND-of-ORs
    // structure:
    //
    // 1. Attributes within each InsightsAudienceAttributeGroup are combined
    // with OR.
    //
    // 2. The groups themselves are combined together with AND.
    //
    // For example, an audience (Interest A OR Interest B) AND (Entity C) is
    // represented using two groups. The first group contains the two interests
    // and the second group contains the entity.
    //
    // This field cannot be set if any Knowledge Graph entities, Product &
    // Service Categories, or user interests are specified in
    // audience_attributes.
    repeated google.ads.googleads.v24.common.InsightsAudienceAttributeGroup
        audience_combinations = 3 [(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. Only Knowledge Graph Entities tagged with
    // [CREATOR_ATTRIBUTE][google.ads.googleads.v24.enums.InsightsKnowledgeGraphEntityCapabilitiesEnum.InsightsKnowledgeGraphEntityCapabilities.CREATOR_ATTRIBUTE]
    // are supported. Use
    // [AudienceInsightsService.ListAudienceInsightsAttributes][google.ads.googleads.v24.services.AudienceInsightsService.ListAudienceInsightsAttributes]
    // to get the list of supported entities. Other attributes including
    // location are not supported.
    repeated google.ads.googleads.v24.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.v24.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][google.ads.googleads.v24.services.GenerateCreatorInsightsRequest.SearchBrand.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.v24.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.v24.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.v24.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][google.ads.googleads.v24.services.GenerateCreatorInsightsRequest.SearchAttributes]
  // criteria.
  repeated google.ads.googleads.v24.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][google.ads.googleads.v24.services.GenerateCreatorInsightsRequest.country_locations]
    // or
    // [sub_country_locations][google.ads.googleads.v24.services.GenerateCreatorInsightsRequest.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][google.ads.googleads.v24.services.GenerateCreatorInsightsRequest.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][google.ads.googleads.v24.services.GenerateCreatorInsightsRequest.country_locations].
    YouTubeChannels search_channels = 4;
  }
}

// Response message for
// [ContentCreatorInsightsService.GenerateCreatorInsights][google.ads.googleads.v24.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][google.ads.googleads.v24.services.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.v24.common.AdditionalApplicationInfo
      insights_application_info = 6 [(google.api.field_behavior) = OPTIONAL];

  // Required. The country to find trends in.
  google.ads.googleads.v24.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][google.ads.googleads.v24.services.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 video views.
  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 channel has published a live stream in the last 90 days.
  bool is_active_live_stream_creator = 16;

  // Partnership opportunities available for this creator.
  repeated google.ads.googleads.v24.enums.PartnershipOpportunityEnum
      .PartnershipOpportunity partnership_opportunities = 17;
}

// 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.v24.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.v24.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.v24.common.AudienceInsightsAttributeMetadata
      channel_audience_attributes = 7;

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

  // The top 10 videos for the channel.
  repeated google.ads.googleads.v24.common.AudienceInsightsAttributeMetadata
      top_videos = 8;

  // The languages associated with the content made by a channel.
  repeated LanguageDistribution language_distributions = 15;

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

  // The relevance score of the channel to the topic being searched for weighted
  // by views. The value is between 0 and 1, with 1 being the most relevant.
  // Only populated for trends using search_topics.
  double relevance_score = 16;
}

// 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. Attributes
  // age_range, gender, user_interest, entity, category, parental_status, and
  // income_range are supported. Attributes user_interest, entity, and category
  // can only be set in audience_attributes when audience_combinations is
  // unused.
  repeated google.ads.googleads.v24.common.AudienceInsightsAttribute
      audience_attributes = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. A list of audience attribute groups consisting of one or more
  // Knowledge Graph entities, Product & Service Categories and user interests
  // that describes an audience. The groups have a logical AND-of-ORs structure:
  //
  // 1. Attributes within each InsightsAudienceAttributeGroup are combined
  // with OR.
  //
  // 2. The groups themselves are combined together with AND.
  //
  // For example, an audience (Interest A OR Interest B) AND (Entity C) is
  // represented using two groups. The first group contains the two interests
  // and the second group contains the entity.
  //
  // This field cannot be set if any Knowledge Graph entities, Product &
  // Service Categories, or user interests are specified in
  // audience_attributes.
  repeated google.ads.googleads.v24.common.InsightsAudienceAttributeGroup
      audience_combinations = 2 [(google.api.field_behavior) = OPTIONAL];
}

// 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
  // [CONTENT_TRENDING_INSIGHTS][google.ads.googleads.v24.enums.InsightsKnowledgeGraphEntityCapabilitiesEnum.InsightsKnowledgeGraphEntityCapabilities.CONTENT_TRENDING_INSIGHTS].
  // Use
  // [AudienceInsightsService.ListAudienceInsightsAttributes][google.ads.googleads.v24.services.AudienceInsightsService.ListAudienceInsightsAttributes]
  // to get the list of supported entities.
  repeated google.ads.googleads.v24.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.v24.common.AudienceInsightsAttributeMetadata
      trend_attribute = 1;

  // Metrics associated with this trend. These metrics are for the latest
  // available month and the comparison period is 3 months.
  TrendInsightMetrics trend_metrics = 2;

  // Indicate if a trend is sustained or emerging. Use
  // trend_metrics.trend_change_percent to determine the direction of the
  // trend.
  google.ads.googleads.v24.enums.InsightsTrendEnum.InsightsTrend trend = 3;

  // 3 years of historical data for the trend, including the most recent month
  // the TrendInsight represents. Each data point represents 1 month of data and
  // the comparison period is 1 month. The data points are ordered from most
  // recent month to least recent month. Only populated for trends using
  // search_topics.
  repeated TrendInsightDataPoint trend_data_points = 6;

  // Related videos for this topic. Only populated for trends using
  // search_topics.
  repeated google.ads.googleads.v24.common.AudienceInsightsAttributeMetadata
      related_videos = 4;

  // Related creators for this topic. Only populated for trends using
  // search_topics.
  repeated YouTubeCreatorInsights related_creators = 5;
}

// Metrics associated with a trend insight.
message TrendInsightMetrics {
  // The number of views for this trend. This is only populated for the latest
  // month of data for SearchTopics requests.
  int64 views_count = 1;

  // Views value normalized to be in the range 0-100. This is only populated for
  // SearchTopics requests.
  int64 views_indexed_value = 4;

  // 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;

  // The percentage of the change in the trend's value over the comparison
  // period, where 1.0 represents 100%. If this is 0, it means that the trend is
  // emerging (new) or sustained (existing but unchanged).
  double trend_change_percent = 3;
}

// Trend data for a specific month.
message TrendInsightDataPoint {
  // The month that the trend data point represents in the string format
  // "YYYY-MM".
  string month = 1;

  // Metrics associated with this trend and month. The comparison period for
  // these metrics is 1 month.
  TrendInsightMetrics trend_metrics = 2;
}

// Languages that pertain to a YouTube channel based on the channel content.
// Only languages above a certain proportion threshold are included.
message LanguageDistribution {
  // [Language
  // code](https://developers.google.com/google-ads/api/reference/data/codes-formats#languages)
  // of the language for the YouTube channel.
  string language_code = 1;

  // The proportion (between 0 and 1)  of the channel's videos in the language.
  double proportion = 2;
}