// 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.v22.common;

import "google/ads/googleads/v22/common/criteria.proto";
import "google/ads/googleads/v22/enums/audience_insights_dimension.proto";
import "google/ads/googleads/v22/enums/insights_knowledge_graph_entity_capabilities.proto";
import "google/ads/googleads/v22/enums/user_list_type.proto";
import "google/ads/googleads/v22/enums/youtube_video_property.proto";
import "google/api/field_behavior.proto";

option csharp_namespace = "Google.Ads.GoogleAds.V22.Common";
option go_package = "google.golang.org/genproto/googleapis/ads/googleads/v22/common;common";
option java_multiple_files = true;
option java_outer_classname = "AudienceInsightsAttributeProto";
option java_package = "com.google.ads.googleads.v22.common";
option objc_class_prefix = "GAA";
option php_namespace = "Google\\Ads\\GoogleAds\\V22\\Common";
option ruby_package = "Google::Ads::GoogleAds::V22::Common";

// Proto file describing audience insights attributes.

// An audience attribute, with metadata about it, returned in response to a
// search.
message AudienceInsightsAttributeMetadata {
  // The type of the attribute.
  google.ads.googleads.v22.enums.AudienceInsightsDimensionEnum
      .AudienceInsightsDimension dimension = 1;

  // The attribute itself.
  AudienceInsightsAttribute attribute = 2;

  // The human-readable name of the attribute.
  string display_name = 3;

  // A string that supplements the display_name to identify the attribute.
  // If the dimension is TOPIC, this is a brief description of the
  // Knowledge Graph entity, such as "American singer-songwriter".
  // If the dimension is CATEGORY, this is the complete path to the category in
  // The Product & Service taxonomy, for example
  // "/Apparel/Clothing/Outerwear".
  string display_info = 4;

  // An estimate of the number of reachable YouTube users matching this
  // attribute in the requested location, or zero if that information is not
  // available for this attribute. This field is not populated in every
  // response.
  int64 potential_youtube_reach = 8;

  // The share of subscribers within this attribute, between and including 0 and
  // 1. This field is not populated in every response.
  double subscriber_share = 9;

  // The share of viewers within this attribute, between and including 0 and
  // 1. This field is not populated in every response.
  double viewer_share = 13;

  // Metadata specific to the dimension of this attribute.
  oneof dimension_metadata {
    // Special metadata for a YouTube channel.
    YouTubeChannelAttributeMetadata youtube_channel_metadata = 5;

    // Special metadata for a YouTube video.
    YouTubeVideoAttributeMetadata youtube_video_metadata = 10;

    // Special metadata for a YouTube Lineup.
    LineupAttributeMetadata lineup_attribute_metadata = 14;

    // Special metadata for a Location.
    LocationAttributeMetadata location_attribute_metadata = 7;

    // Special metadata for a User Interest.
    UserInterestAttributeMetadata user_interest_attribute_metadata = 11;

    // Special metadata for a Knowledge Graph Entity.
    KnowledgeGraphAttributeMetadata knowledge_graph_attribute_metadata = 12;

    // Special metadata for a User List.
    UserListAttributeMetadata user_list_attribute_metadata = 15;
  }
}

// An audience attribute that can be used to request insights about the
// audience. Valid inputs for these fields are available from
// [AudienceInsightsService.ListAudienceInsightsAttributes][google.ads.googleads.v22.services.AudienceInsightsService.ListAudienceInsightsAttributes].
message AudienceInsightsAttribute {
  // An audience attribute.
  oneof attribute {
    // An audience attribute defined by an age range.
    AgeRangeInfo age_range = 1;

    // An audience attribute defined by a gender.
    GenderInfo gender = 2;

    // An audience attribute defined by a geographic location.
    LocationInfo location = 3;

    // An Affinity or In-Market audience.
    UserInterestInfo user_interest = 4;

    // An audience attribute defined by interest in a topic represented by a
    // Knowledge Graph entity.
    AudienceInsightsEntity entity = 5;

    // An audience attribute defined by interest in a Product & Service
    // category.
    AudienceInsightsCategory category = 6;

    // A YouTube Lineup.
    AudienceInsightsLineup lineup = 13;

    // A Parental Status value (parent, or not a parent).
    ParentalStatusInfo parental_status = 8;

    // A household income percentile range.
    IncomeRangeInfo income_range = 9;

    // A YouTube channel.
    YouTubeChannelInfo youtube_channel = 10;

    // A YouTube video.
    YouTubeVideoInfo youtube_video = 11;

    // A device type. (Mobile, Desktop, Tablet)
    DeviceInfo device = 12;

    // A User List.
    UserListInfo user_list = 14;
  }
}

// A Knowledge Graph entity, represented by its machine id.
message AudienceInsightsEntity {
  // Required. The machine ID (mid) of the Knowledge Graph entity.
  string knowledge_graph_machine_id = 1
      [(google.api.field_behavior) = REQUIRED];
}

// A Product and Service category.
message AudienceInsightsCategory {
  // Required. The criterion ID of the category.
  string category_id = 1 [(google.api.field_behavior) = REQUIRED];
}

// A YouTube Lineup.
message AudienceInsightsLineup {
  // Required. The numeric ID of the lineup.
  string lineup_id = 1 [(google.api.field_behavior) = REQUIRED];
}

// Metadata associated with a YouTube channel attribute.
message YouTubeChannelAttributeMetadata {
  // The approximate number of subscribers to the YouTube channel.
  int64 subscriber_count = 1;
}

// Metadata for a YouTube video attribute.
message YouTubeVideoAttributeMetadata {
  // The URL of the video thumbnail, prefixed by "https://img.youtube.com/".
  string thumbnail_url = 1;

  // The URL of the video, prefixed by "https://www.youtube.com/".
  string video_url = 2;

  // The total number of views.
  int64 views_count = 3;

  // The total number of likes.
  int64 likes_count = 4;

  // The total number of comments.
  int64 comments_count = 5;

  // The properties of this video (such as shorts, live stream).
  repeated google.ads.googleads.v22.enums.YouTubeVideoPropertyEnum
      .YouTubeVideoProperty video_properties = 6;

  // The date that the video was created. Formatted as "yyyy-mm-dd".
  string publish_date = 7;
}

// Metadata associated with a Lineup attribute.
message LineupAttributeMetadata {
  // A YouTube channel returned as an example of the content in a lineup.
  message SampleChannel {
    // A YouTube channel.
    YouTubeChannelInfo youtube_channel = 1;

    // The name of the sample channel.
    string display_name = 2;

    // Metadata for the sample channel.
    YouTubeChannelAttributeMetadata youtube_channel_metadata = 3;
  }

  // The national market associated with the lineup.
  LocationInfo inventory_country = 1;

  // The median number of impressions per month on this lineup.
  optional int64 median_monthly_inventory = 2;

  // The lower end of a range containing the number of channels in the lineup.
  optional int64 channel_count_lower_bound = 3;

  // The upper end of a range containing the number of channels in the lineup.
  optional int64 channel_count_upper_bound = 4;

  // Examples of channels that are included in the lineup.
  repeated SampleChannel sample_channels = 5;
}

// Metadata associated with a Location attribute.
message LocationAttributeMetadata {
  // The country location that this attribute’s sub country location is located
  // in.
  LocationInfo country_location = 1;
}

// Metadata associated with a User Interest attribute.
message UserInterestAttributeMetadata {
  // English language text description of the user interest category (200
  // characters max).
  string user_interest_description = 1;
}

// Metadata associated with a Knowledge Graph Entity attribute.
message KnowledgeGraphAttributeMetadata {
  // The capabilities of the entity used in
  // [ContentCreatorInsightsService][google.ads.googleads.v22.services.ContentCreatorInsightsService].
  repeated google.ads.googleads.v22.enums
      .InsightsKnowledgeGraphEntityCapabilitiesEnum
      .InsightsKnowledgeGraphEntityCapabilities entity_capabilities = 1;

  // A list of CATEGORY attributes related to this entity.
  repeated AudienceInsightsAttributeMetadata related_categories = 2;
}

// Metadata associated with a User List attribute.
message UserListAttributeMetadata {
  // The user list type.
  google.ads.googleads.v22.enums.UserListTypeEnum.UserListType user_list_type =
      1;
}

// A group of audience attributes with metadata, returned in response to a
// search.
message AudienceInsightsAttributeMetadataGroup {
  // Attributes with metadata returned in response to a search.
  repeated AudienceInsightsAttributeMetadata attributes = 1;
}