/services/audience_insights_service.proto

--- v17/services/audience_insights_service.proto    2024-08-06 12:42:08.000000000 +0000
+++ v17-1/services/audience_insights_service.proto  2024-08-06 12:42:18.000000000 +0000
@@ -147,6 +147,30 @@
     };
     option (google.api.method_signature) = "customer_id,audience";
   }
+
+  // Returns a collection of audience attributes along with estimates of the
+  // overlap between their potential YouTube reach and that of a given input
+  // attribute.
+  //
+  // List of thrown errors:
+  //   [AudienceInsightsError]()
+  //   [AuthenticationError]()
+  //   [AuthorizationError]()
+  //   [FieldError]()
+  //   [HeaderError]()
+  //   [InternalError]()
+  //   [QuotaError]()
+  //   [RangeError]()
+  //   [RequestError]()
+  rpc GenerateAudienceOverlapInsights(GenerateAudienceOverlapInsightsRequest)
+      returns (GenerateAudienceOverlapInsightsResponse) {
+    option (google.api.http) = {
+      post: "/v17/customers/{customer_id=*}:generateAudienceOverlapInsights"
+      body: "*"
+    };
+    option (google.api.method_signature) =
+        "customer_id,country_location,primary_attribute,dimensions";
+  }
 }

 // Request message for
@@ -332,6 +363,69 @@
   google.ads.googleads.v17.common.DateRange last_thirty_days = 2;
 }

+// Request message for
+// [AudienceInsightsService.GenerateAudienceOverlapInsights][google.ads.googleads.v17.services.AudienceInsightsService.GenerateAudienceOverlapInsights].
+message GenerateAudienceOverlapInsightsRequest {
+  // Required. The ID of the customer.
+  string customer_id = 1 [(google.api.field_behavior) = REQUIRED];
+
+  // Required. The country in which to calculate the sizes and overlaps of
+  // audiences.
+  google.ads.googleads.v17.common.LocationInfo country_location = 2
+      [(google.api.field_behavior) = REQUIRED];
+
+  // Required. The audience attribute that should be intersected with all other
+  // eligible audiences.  This must be an Affinity or In-Market UserInterest, an
+  // AgeRange or a Gender.
+  AudienceInsightsAttribute primary_attribute = 3
+      [(google.api.field_behavior) = REQUIRED];
+
+  // Required. The types of attributes of which to calculate the overlap with
+  // the primary_attribute. The values must be a subset of
+  // AFFINITY_USER_INTEREST, IN_MARKET_USER_INTEREST, AGE_RANGE and GENDER.
+  repeated google.ads.googleads.v17.enums.AudienceInsightsDimensionEnum
+      .AudienceInsightsDimension dimensions = 4
+      [(google.api.field_behavior) = REQUIRED];
+
+  // The name of the customer being planned for.  This is a user-defined value.
+  string customer_insights_group = 5;
+}
+
+// Response message for
+// [AudienceInsightsService.GenerateAudienceOverlapInsights][google.ads.googleads.v17.services.AudienceInsightsService.GenerateAudienceOverlapInsights].
+message GenerateAudienceOverlapInsightsResponse {
+  // Metadata for the primary attribute, including potential YouTube reach.
+  AudienceInsightsAttributeMetadata primary_attribute_metadata = 1;
+
+  // Lists of attributes and their overlap with the primary attribute, one list
+  // per requested dimension.
+  repeated DimensionOverlapResult dimension_results = 2;
+}
+
+// A list of audience attributes of a single dimension, including their overlap
+// with a primary attribute, returned as part of a
+// [GenerateAudienceOverlapInsightsResponse][google.ads.googleads.v17.services.GenerateAudienceOverlapInsightsResponse].
+message DimensionOverlapResult {
+  // The dimension of all the attributes in this section.
+  google.ads.googleads.v17.enums.AudienceInsightsDimensionEnum
+      .AudienceInsightsDimension dimension = 1;
+
+  // The attributes and their overlap with the primary attribute.
+  repeated AudienceOverlapItem items = 2;
+}
+
+// An audience attribute, with metadata including the overlap between this
+// attribute's potential YouTube reach and that of a primary attribute.
+message AudienceOverlapItem {
+  // The attribute and its metadata, including potential YouTube reach.
+  AudienceInsightsAttributeMetadata attribute_metadata = 1;
+
+  // The estimated size of the intersection of this audience attribute with the
+  // primary attribute, that is, the number of reachable YouTube users who match
+  // BOTH the primary attribute and this one.
+  int64 potential_youtube_reach_intersection = 2;
+}
+
 // An audience attribute that can be used to request insights about the
 // audience.
 message AudienceInsightsAttribute {
@@ -451,6 +545,14 @@
   // "/Apparel/Clothing/Outerwear".
   string display_info = 5;

+  // 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.  Only populated in
+  // GenerateAudienceOverlapInsightsResponses and in
+  // ListAudienceInsightsAttributesResponses when youtube_reach_location is
+  // present in the request.
+  int64 potential_youtube_reach = 9;
+
   // Metadata specific to the dimension of this attribute.
   oneof dimension_metadata {
     // Special metadata for a YouTube channel.