/common/audience_insights_attribute.proto

--- v20/common/audience_insights_attribute.proto    2025-06-04 18:55:28.000000000 +0000
+++ v21/common/audience_insights_attribute.proto    2025-08-05 14:28:35.000000000 +0000
@@ -1,233 +1,267 @@
 // 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.v20.common;
+package google.ads.googleads.v21.common;

-import "google/ads/googleads/v20/common/criteria.proto";
-import "google/ads/googleads/v20/enums/audience_insights_dimension.proto";
-import "google/ads/googleads/v20/enums/insights_knowledge_graph_entity_capabilities.proto";
+import "google/ads/googleads/v21/common/criteria.proto";
+import "google/ads/googleads/v21/enums/audience_insights_dimension.proto";
+import "google/ads/googleads/v21/enums/insights_knowledge_graph_entity_capabilities.proto";
+import "google/ads/googleads/v21/enums/user_list_type.proto";
 import "google/api/field_behavior.proto";

-option csharp_namespace = "Google.Ads.GoogleAds.V20.Common";
-option go_package = "google.golang.org/genproto/googleapis/ads/googleads/v20/common;common";
+option csharp_namespace = "Google.Ads.GoogleAds.V21.Common";
+option go_package = "google.golang.org/genproto/googleapis/ads/googleads/v21/common;common";
 option java_multiple_files = true;
 option java_outer_classname = "AudienceInsightsAttributeProto";
-option java_package = "com.google.ads.googleads.v20.common";
+option java_package = "com.google.ads.googleads.v21.common";
 option objc_class_prefix = "GAA";
-option php_namespace = "Google\\Ads\\GoogleAds\\V20\\Common";
-option ruby_package = "Google::Ads::GoogleAds::V20::Common";
+option php_namespace = "Google\\Ads\\GoogleAds\\V21\\Common";
+option ruby_package = "Google::Ads::GoogleAds::V21::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.v20.enums.AudienceInsightsDimensionEnum
+  google.ads.googleads.v21.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.
+// audience. Valid inputs for these fields are available from
+// [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;
   }
 }

 // An entity or category representing a topic that defines an audience.
 message AudienceInsightsTopic {
   // An entity or category attribute.
   oneof topic {
     // A Knowledge Graph entity
     AudienceInsightsEntity entity = 1;

     // A Product & Service category
     AudienceInsightsCategory category = 2;
   }
 }

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

 // 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][].
-  repeated google.ads.googleads.v20.enums
+  repeated google.ads.googleads.v21.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.v21.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;
 }