--- 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
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2024-10-17 UTC.