--- 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.
