/services/audience_insights_service.proto

--- v17/services/audience_insights_service.proto    2024-10-17 03:48:53.000000000 +0000
+++ v18/services/audience_insights_service.proto    2024-10-17 03:48:59.000000000 +0000
@@ -142,10 +143,9 @@
       GenerateSuggestedTargetingInsightsRequest)
       returns (GenerateSuggestedTargetingInsightsResponse) {
     option (google.api.http) = {
-      post: "/v17/customers/{customer_id=*}:generateSuggestedTargetingInsights"
+      post: "/v18/customers/{customer_id=*}:generateSuggestedTargetingInsights"
       body: "*"
     };
-    option (google.api.method_signature) = "customer_id,audience";
   }

   // Returns a collection of audience attributes along with estimates of the
@@ -165,12 +165,37 @@
   rpc GenerateAudienceOverlapInsights(GenerateAudienceOverlapInsightsRequest)
       returns (GenerateAudienceOverlapInsightsResponse) {
     option (google.api.http) = {
-      post: "/v17/customers/{customer_id=*}:generateAudienceOverlapInsights"
+      post: "/v18/customers/{customer_id=*}:generateAudienceOverlapInsights"
       body: "*"
     };
     option (google.api.method_signature) =
         "customer_id,country_location,primary_attribute,dimensions";
   }
+
+  // Returns potential reach metrics for targetable audiences.
+  //
+  // This method helps answer questions like "How many Men aged 18+ interested
+  // in Camping can be reached on YouTube?"
+  //
+  // List of thrown errors:
+  //   [AudienceInsightsError]()
+  //   [AuthenticationError]()
+  //   [AuthorizationError]()
+  //   [FieldError]()
+  //   [HeaderError]()
+  //   [InternalError]()
+  //   [QuotaError]()
+  //   [RangeError]()
+  //   [RequestError]()
+  rpc GenerateTargetingSuggestionMetrics(
+      GenerateTargetingSuggestionMetricsRequest)
+      returns (GenerateTargetingSuggestionMetricsResponse) {
+    option (google.api.http) = {
+      post: "/v18/customers/{customer_id=*}:generateTargetingSuggestionMetrics"
+      body: "*"
+    };
+    option (google.api.method_signature) = "customer_id,audiences";
+  }
 }

 // Request message for
@@ -241,27 +266,24 @@
 }

 // Request message for
-// [AudienceInsightsService.GenerateSuggestedTargetingInsights][google.ads.googleads.v17.services.AudienceInsightsService.GenerateSuggestedTargetingInsights].
+// [AudienceInsightsService.GenerateSuggestedTargetingInsights][google.ads.googleads.v18.services.AudienceInsightsService.GenerateSuggestedTargetingInsights].
 message GenerateSuggestedTargetingInsightsRequest {
   // Required. The ID of the customer.
   string customer_id = 1 [(google.api.field_behavior) = REQUIRED];

-  // Required. The audience of interest for which insights are being requested.
-  InsightsAudience audience = 2 [(google.api.field_behavior) = REQUIRED];
-
-  // Optional. The baseline audience.  The default, if unspecified, is all
-  // people in the same country as the audience of interest.
-  InsightsAudience baseline_audience = 3
-      [(google.api.field_behavior) = OPTIONAL];
-
-  // Optional. The one-month range of historical data to use for insights, in
-  // the format "yyyy-mm". If unset, insights will be returned for the last
-  // thirty days of data.
-  string data_month = 4 [(google.api.field_behavior) = OPTIONAL];
-
   // Optional. The name of the customer being planned for.  This is a
   // user-defined value.
   string customer_insights_group = 5 [(google.api.field_behavior) = OPTIONAL];
+
+  // Required. The audience to get suggestions for.
+  oneof audience_input {
+    // Provide a seed audience to get suggestions for.
+    InsightsAudienceDefinition audience_definition = 6;
+
+    // Provide a text description of an audience to get AI-generated targeting
+    // suggestions. This can take around 5 or more seconds to complete.
+    InsightsAudienceDescription audience_description = 7;
+  }
 }

 // Response message for
@@ -426,6 +451,30 @@
   int64 potential_youtube_reach_intersection = 2;
 }

+// Request message for
+// [AudienceInsightsService.GenerateTargetingSuggestionMetrics].
+message GenerateTargetingSuggestionMetricsRequest {
+  // Required. The ID of the customer.
+  string customer_id = 1 [(google.api.field_behavior) = REQUIRED];
+
+  // Required. Audiences to request metrics for.
+  repeated BasicInsightsAudience audiences = 2
+      [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. The name of the customer being planned for.  This is a
+  // user-defined value.
+  string customer_insights_group = 3 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Response message for
+// [AudienceInsightsService.GenerateTargetingSuggestionMetrics][google.ads.googleads.v18.services.AudienceInsightsService.GenerateTargetingSuggestionMetrics].
+message GenerateTargetingSuggestionMetricsResponse {
+  // Suggested targetable audiences. There will be one suggestion for each
+  // [GenerateTargetingSuggestionMetricsRequest.audiences] requested, matching
+  // the order requested.
+  repeated TargetingSuggestionMetrics suggestions = 1;
+}
+
 // An audience attribute that can be used to request insights about the
 // audience.
 message AudienceInsightsAttribute {
@@ -563,6 +612,9 @@

     // Special metadata for a Location.
     LocationAttributeMetadata location_attribute_metadata = 8;
+
+    // Special metadata for a User Interest.
+    UserInterestAttributeMetadata user_interest_attribute_metadata = 10;
   }
 }

@@ -605,7 +657,52 @@
 // Metadata associated with a Location attribute.
 message LocationAttributeMetadata {
   // The country location of the sub country location.
-  google.ads.googleads.v17.common.LocationInfo country_location = 1;
+  google.ads.googleads.v18.common.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;
+}
+
+// A structured definition of the audience of interest for which insights are
+// being requested in AudienceInsightsService.
+message InsightsAudienceDefinition {
+  // Required. The audience of interest for which insights are being requested.
+  InsightsAudience audience = 1 [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. The baseline audience. The default, if unspecified, is all people
+  // in the same country as the audience of interest.
+  InsightsAudience baseline_audience = 2
+      [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. The one-month range of historical data to use for insights, in
+  // the format "yyyy-mm". If unset, insights will be returned for the last
+  // thirty days of data.
+  string data_month = 3 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// A text description of the audience of interest for which insights are being
+// requested in AudienceInsightsService.
+message InsightsAudienceDescription {
+  // Required. The countries for the audience.
+  repeated google.ads.googleads.v18.common.LocationInfo country_locations = 1
+      [(google.api.field_behavior) = REQUIRED];
+
+  // Required. An English language text description of an audience to get
+  // suggestions for. Maximum length is 2000 characters. For example, "Women in
+  // their 30s who love to travel".
+  string audience_description = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. An optional marketing objective which will influence the type of
+  // suggestions produced. AWARENESS will provide affinity audience segments,
+  // while CONSIDERATION will provide in-market audience segments. Leaving it
+  // unset will provide both.
+  google.ads.googleads.v18.enums.AudienceInsightsMarketingObjectiveEnum
+      .AudienceInsightsMarketingObjective marketing_objective = 3
+      [(google.api.field_behavior) = OPTIONAL];
 }

 // A set of users, defined by various characteristics, for which insights can