/services/benchmarks_service.proto

--- v24/services/benchmarks_service.proto   2026-04-22 18:40:52.000000000 +0000
+++ v25/services/benchmarks_service.proto   2026-07-21 21:17:11.000000000 +0000
@@ -1,456 +1,461 @@
 // Copyright 2026 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.v24.services;
+package google.ads.googleads.v25.services;

-import "google/ads/googleads/v24/common/additional_application_info.proto";
-import "google/ads/googleads/v24/common/criteria.proto";
-import "google/ads/googleads/v24/common/dates.proto";
-import "google/ads/googleads/v24/enums/benchmarks_marketing_objective.proto";
-import "google/ads/googleads/v24/enums/benchmarks_source_type.proto";
-import "google/ads/googleads/v24/enums/benchmarks_time_granularity.proto";
+import "google/ads/googleads/v25/common/additional_application_info.proto";
+import "google/ads/googleads/v25/common/criteria.proto";
+import "google/ads/googleads/v25/common/dates.proto";
+import "google/ads/googleads/v25/enums/benchmarks_marketing_objective.proto";
+import "google/ads/googleads/v25/enums/benchmarks_source_type.proto";
+import "google/ads/googleads/v25/enums/benchmarks_time_granularity.proto";
 import "google/api/annotations.proto";
 import "google/api/client.proto";
 import "google/api/field_behavior.proto";

-option csharp_namespace = "Google.Ads.GoogleAds.V24.Services";
-option go_package = "google.golang.org/genproto/googleapis/ads/googleads/v24/services;services";
+option csharp_namespace = "Google.Ads.GoogleAds.V25.Services";
+option go_package = "google.golang.org/genproto/googleapis/ads/googleads/v25/services;services";
 option java_multiple_files = true;
 option java_outer_classname = "BenchmarksServiceProto";
-option java_package = "com.google.ads.googleads.v24.services";
+option java_package = "com.google.ads.googleads.v25.services";
 option objc_class_prefix = "GAA";
-option php_namespace = "Google\\Ads\\GoogleAds\\V24\\Services";
-option ruby_package = "Google::Ads::GoogleAds::V24::Services";
+option php_namespace = "Google\\Ads\\GoogleAds\\V25\\Services";
+option ruby_package = "Google::Ads::GoogleAds::V25::Services";

 // Proto file describing the benchmarks service.

 // BenchmarksService helps users compare YouTube advertisement data against
 // industry benchmarks. Accessible to allowlisted customers only.
 service BenchmarksService {
   option (google.api.default_host) = "googleads.googleapis.com";
   option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/adwords";

   // Returns a date range that supports benchmarks.
   //
   // List of thrown errors:
   //   [AuthenticationError]()
   //   [AuthorizationError]()
   //   [FieldError]()
   //   [HeaderError]()
   //   [InternalError]()
   //   [QuotaError]()
   //   [RequestError]()
   rpc ListBenchmarksAvailableDates(ListBenchmarksAvailableDatesRequest)
       returns (ListBenchmarksAvailableDatesResponse) {
     option (google.api.http) = {
-      post: "/v24:listBenchmarksAvailableDates"
+      post: "/v25:listBenchmarksAvailableDates"
       body: "*"
     };
   }

   // Returns the list of locations that support benchmarks (for example,
   // countries).
   //
   // List of thrown errors:
   //   [AuthenticationError]()
   //   [AuthorizationError]()
   //   [FieldError]()
   //   [HeaderError]()
   //   [InternalError]()
   //   [QuotaError]()
   //   [RequestError]()
   rpc ListBenchmarksLocations(ListBenchmarksLocationsRequest)
       returns (ListBenchmarksLocationsResponse) {
     option (google.api.http) = {
-      post: "/v24:listBenchmarksLocations"
+      post: "/v25:listBenchmarksLocations"
       body: "*"
     };
   }

   // Returns the list of products that supports benchmarks.
   //
   // List of thrown errors:
   //   [AuthenticationError]()
   //   [AuthorizationError]()
   //   [FieldError]()
   //   [HeaderError]()
   //   [InternalError]()
   //   [QuotaError]()
   //   [RequestError]()
   rpc ListBenchmarksProducts(ListBenchmarksProductsRequest)
       returns (ListBenchmarksProductsResponse) {
     option (google.api.http) = {
-      post: "/v24:listBenchmarksProducts"
+      post: "/v25:listBenchmarksProducts"
       body: "*"
     };
   }

   // Returns the list of benchmarks sources (for example, Industry Verticals).
   //
   // List of thrown errors:
   //   [AuthenticationError]()
   //   [AuthorizationError]()
   //   [FieldError]()
   //   [HeaderError]()
   //   [InternalError]()
   //   [QuotaError]()
   //   [RequestError]()
   rpc ListBenchmarksSources(ListBenchmarksSourcesRequest)
       returns (ListBenchmarksSourcesResponse) {
     option (google.api.http) = {
-      post: "/v24:listBenchmarksSources"
+      post: "/v25:listBenchmarksSources"
       body: "*"
     };
     option (google.api.method_signature) = "benchmarks_sources";
   }

   // Returns YouTube advertisement metrics for the given client against industry
   // benchmarks.
   //
   // List of thrown errors:
   //   [AuthenticationError]()
   //   [AuthorizationError]()
   //   [BenchmarksError]()
   //   [FieldError]()
   //   [HeaderError]()
   //   [InternalError]()
   //   [QuotaError]()
   //   [RangeError]()
   //   [RequestError]()
   rpc GenerateBenchmarksMetrics(GenerateBenchmarksMetricsRequest)
       returns (GenerateBenchmarksMetricsResponse) {
     option (google.api.http) = {
-      post: "/v24/customers/{customer_id=*}:generateBenchmarksMetrics"
+      post: "/v25/customers/{customer_id=*}:generateBenchmarksMetrics"
       body: "*"
     };
     option (google.api.method_signature) =
         "customer_id,location,benchmarks_source,product_filter";
   }
 }

 // Request message for
-// [BenchmarksService.ListBenchmarksAvailableDates][google.ads.googleads.v24.services.BenchmarksService.ListBenchmarksAvailableDates].
+// [BenchmarksService.ListBenchmarksAvailableDates][google.ads.googleads.v25.services.BenchmarksService.ListBenchmarksAvailableDates].
 message ListBenchmarksAvailableDatesRequest {
   // Additional information on the application issuing the request.
-  google.ads.googleads.v24.common.AdditionalApplicationInfo application_info =
+  google.ads.googleads.v25.common.AdditionalApplicationInfo application_info =
       1;
 }

 // Response message for
-// [BenchmarksService.ListBenchmarksAvailableDates][google.ads.googleads.v24.services.BenchmarksService.ListBenchmarksAvailableDates].
+// [BenchmarksService.ListBenchmarksAvailableDates][google.ads.googleads.v25.services.BenchmarksService.ListBenchmarksAvailableDates].
 message ListBenchmarksAvailableDatesResponse {
   // The dates that support benchmarks metrics. Data is supported for any dates
   // within this date range inclusive.
-  google.ads.googleads.v24.common.DateRange supported_dates = 1;
+  google.ads.googleads.v25.common.DateRange supported_dates = 1;
 }

 // Request message for
-// [BenchmarksService.ListBenchmarksLocations][google.ads.googleads.v24.services.BenchmarksService.ListBenchmarksLocations].
+// [BenchmarksService.ListBenchmarksLocations][google.ads.googleads.v25.services.BenchmarksService.ListBenchmarksLocations].
 message ListBenchmarksLocationsRequest {
   // Additional information on the application issuing the request.
-  google.ads.googleads.v24.common.AdditionalApplicationInfo application_info =
+  google.ads.googleads.v25.common.AdditionalApplicationInfo application_info =
       1;
 }

 // Response message for
-// [BenchmarksService.ListBenchmarksLocations][google.ads.googleads.v24.services.BenchmarksService.ListBenchmarksLocations].
+// [BenchmarksService.ListBenchmarksLocations][google.ads.googleads.v25.services.BenchmarksService.ListBenchmarksLocations].
 message ListBenchmarksLocationsResponse {
   // The list of locations supported for benchmarks data.
   repeated BenchmarksLocation benchmarks_locations = 1;
 }

 // A location that supports benchmarks data.
 message BenchmarksLocation {
   // The unique location name in English.
   string location_name = 1;

   // The location's type. Location types correspond to target_type returned by
   // searching location type in GoogleAdsService.Search/SearchStream.
   string location_type = 2;

   // Information on the geographic location, including the location ID.
-  google.ads.googleads.v24.common.LocationInfo location_info = 3;
+  google.ads.googleads.v25.common.LocationInfo location_info = 3;
 }

 // Request message for
-// [BenchmarksService.ListBenchmarksProducts][google.ads.googleads.v24.services.BenchmarksService.ListBenchmarksProducts].
+// [BenchmarksService.ListBenchmarksProducts][google.ads.googleads.v25.services.BenchmarksService.ListBenchmarksProducts].
 message ListBenchmarksProductsRequest {
   // Additional information on the application issuing the request.
-  google.ads.googleads.v24.common.AdditionalApplicationInfo application_info =
+  google.ads.googleads.v25.common.AdditionalApplicationInfo application_info =
       1;
 }

 // Response message for
-// [BenchmarksService.ListBenchmarksProducts][google.ads.googleads.v24.services.BenchmarksService.ListBenchmarksProducts].
+// [BenchmarksService.ListBenchmarksProducts][google.ads.googleads.v25.services.BenchmarksService.ListBenchmarksProducts].
 message ListBenchmarksProductsResponse {
   // The list of products available for benchmarks data.
   repeated BenchmarksProductMetadata benchmarks_products = 1;
 }

 // The metadata associated with a product supported for benchmarks data.
 message BenchmarksProductMetadata {
   // The name of the product.
   string product_name = 1;

   // The identifier of the product. The identifier can be used as inputs
   // for
-  // [BenchmarksService.GenerateBenchmarksMetrics][google.ads.googleads.v24.services.BenchmarksService.GenerateBenchmarksMetrics].
+  // [BenchmarksService.GenerateBenchmarksMetrics][google.ads.googleads.v25.services.BenchmarksService.GenerateBenchmarksMetrics].
   string product_code = 2;

   // The marketing objective associated with the product. A marketing objective
   // is a broader classification of products.
-  google.ads.googleads.v24.enums.BenchmarksMarketingObjectiveEnum
+  google.ads.googleads.v25.enums.BenchmarksMarketingObjectiveEnum
       .BenchmarksMarketingObjective marketing_objective = 3;
 }

 // Request message for
-// [BenchmarksService.ListBenchmarksSources][google.ads.googleads.v24.services.BenchmarksService.ListBenchmarksSources].
+// [BenchmarksService.ListBenchmarksSources][google.ads.googleads.v25.services.BenchmarksService.ListBenchmarksSources].
 message ListBenchmarksSourcesRequest {
-  // Required. The types of benchmarks sources to be returned (for example,
-  // INDUSTRY_VERTICAL).
-  repeated google.ads.googleads.v24.enums.BenchmarksSourceTypeEnum
+  // Required. The types of benchmarks sources to be returned
+  repeated google.ads.googleads.v25.enums.BenchmarksSourceTypeEnum
       .BenchmarksSourceType benchmarks_sources = 1
       [(google.api.field_behavior) = REQUIRED];

   // Additional information on the application issuing the request.
-  google.ads.googleads.v24.common.AdditionalApplicationInfo application_info =
+  google.ads.googleads.v25.common.AdditionalApplicationInfo application_info =
       2;
 }

 // Response message for
-// [BenchmarksService.ListBenchmarksSources][google.ads.googleads.v24.services.BenchmarksService.ListBenchmarksSources].
+// [BenchmarksService.ListBenchmarksSources][google.ads.googleads.v25.services.BenchmarksService.ListBenchmarksSources].
 message ListBenchmarksSourcesResponse {
   // The list of available source used to generate benchmarks data for.
   repeated BenchmarksSourceMetadata benchmarks_sources = 1;
 }

 // The metadata associated with a benchmarks source.
 message BenchmarksSourceMetadata {
   // The type of benchmarks source.
-  google.ads.googleads.v24.enums.BenchmarksSourceTypeEnum.BenchmarksSourceType
+  google.ads.googleads.v25.enums.BenchmarksSourceTypeEnum.BenchmarksSourceType
       benchmarks_source_type = 1;

   // Information on benchmarks source.
   oneof benchmarks_source_info {
     // Information on the Industry Vertical.
     IndustryVerticalInfo industry_vertical_info = 2;
   }
 }

 // The information associated with an Industry Vertical.
 message IndustryVerticalInfo {
   // The name of the Industry Vertical.
   string industry_vertical_name = 1;

   // The unique identifier of the Industry Vertical.
   int64 industry_vertical_id = 2;

   // The unique identifier of the parent Industry Vertical, if exists.
   int64 parent_industry_vertical_id = 3;
 }

 // Request message for
-// [BenchmarksService.GenerateBenchmarksMetrics][google.ads.googleads.v24.services.BenchmarksService.GenerateBenchmarksMetrics].
+// [BenchmarksService.GenerateBenchmarksMetrics][google.ads.googleads.v25.services.BenchmarksService.GenerateBenchmarksMetrics].
 message GenerateBenchmarksMetricsRequest {
   // Required. The ID of the customer. Supply a client customer ID to generate
   // metrics for the customer. A manager account customer ID will not return
   // customer metrics since it does not have any associated direct ad campaigns.
   string customer_id = 1 [(google.api.field_behavior) = REQUIRED];

   // The date range to aggregate metrics over. If unset, data will be returned
   // for the most recent quarter for which data is available. Dates can be
   // retrieved using
-  // [BenchmarksService.ListBenchmarksAvailableDates][google.ads.googleads.v24.services.BenchmarksService.ListBenchmarksAvailableDates].
-  google.ads.googleads.v24.common.DateRange date_range = 2;
+  // [BenchmarksService.ListBenchmarksAvailableDates][google.ads.googleads.v25.services.BenchmarksService.ListBenchmarksAvailableDates].
+  google.ads.googleads.v25.common.DateRange date_range = 2;

   // Required. The location to generate benchmarks metrics for.
-  google.ads.googleads.v24.common.LocationInfo location = 3
+  google.ads.googleads.v25.common.LocationInfo location = 3
       [(google.api.field_behavior) = REQUIRED];

   // Required. The source used to generate benchmarks metrics for.
   BenchmarksSource benchmarks_source = 4
       [(google.api.field_behavior) = REQUIRED];

   // Required. The products to aggregate metrics over. Product filter settings
   // support a list of product IDs or a list of marketing objectives.
   ProductFilter product_filter = 5 [(google.api.field_behavior) = REQUIRED];

   // Optional. The set of dimensions to group metrics by. If multiple dimensions
   // are selected, cross-dimension breakdowns are returned.
   BreakdownDefinition breakdown_definition = 9
       [(google.api.field_behavior) = OPTIONAL];

   // Optional. The three-character ISO 4217 currency code. If unspecified, the
   // default currency for monetary values is USD.
   string currency_code = 6 [(google.api.field_behavior) = OPTIONAL];

   // The name of the customer being planned for. This is a user-defined value.
   string customer_benchmarks_group = 7;

   // Additional information on the application issuing the request.
-  google.ads.googleads.v24.common.AdditionalApplicationInfo application_info =
+  google.ads.googleads.v25.common.AdditionalApplicationInfo application_info =
       8;
 }

 // The source used to generate benchmarks metrics for. The ID of the source can
 // be obtained from
-// [BenchmarksService.ListBenchmarksSources][google.ads.googleads.v24.services.BenchmarksService.ListBenchmarksSources].
+// [BenchmarksService.ListBenchmarksSources][google.ads.googleads.v25.services.BenchmarksService.ListBenchmarksSources].
 message BenchmarksSource {
   // The ID of the chosen benchmarks source.
   oneof benchmarks_source_id {
     // The ID of the Industry Vertical.
     int64 industry_vertical_id = 1;
   }
 }

 // The type and list of products to aggregate benchmarks metrics over.
 message ProductFilter {
   // The list of products to generate benchmarks metrics for.
   message ProductList {
     // Required. Products to generate benchmarks metrics for.
     repeated string product_codes = 1 [(google.api.field_behavior) = REQUIRED];
   }

   // The list of marketing objectives to generate benchmarks metrics for.
   message MarketingObjectiveList {
     // Required. Marketing objectives to generate benchmarks metrics for.
-    repeated google.ads.googleads.v24.enums.BenchmarksMarketingObjectiveEnum
+    repeated google.ads.googleads.v25.enums.BenchmarksMarketingObjectiveEnum
         .BenchmarksMarketingObjective marketing_objectives = 1
         [(google.api.field_behavior) = REQUIRED];
   }

   // The products to aggregate benchmarks metrics over.
   oneof filter_settings {
     // The list of products.
     ProductList product_list = 1;

     // The list of marketing goals. Marketing objective is a broader product
     // classification of products.
     MarketingObjectiveList marketing_objective_list = 2;
   }
 }

 // The set of dimensions to group metrics by.
 message BreakdownDefinition {
   // The granularity for segmenting metrics by date. When this field is set,
   // a valid date_range in the GenerateBenchmarksMetricsRequest is required
   // and must precisely align with the boundaries of the selected granularity.
   //
   // For example, a monthly breakdown must start on the first day of a month and
   // end on the last day of a month. A quarterly breakdown must start on the
   // first day of a quarter and end on the last day of a quarter. A weekly
   // breakdown must start on a Sunday and end on a Saturday. This is different
   // from the ISO 8601 standard, where weeks start on Monday.
-  google.ads.googleads.v24.enums.BenchmarksTimeGranularityEnum
+  google.ads.googleads.v25.enums.BenchmarksTimeGranularityEnum
       .BenchmarksTimeGranularity date_breakdown = 1;
 }

 // Response message for
-// [BenchmarksService.GenerateBenchmarksMetrics][google.ads.googleads.v24.services.BenchmarksService.GenerateBenchmarksMetrics].
+// [BenchmarksService.GenerateBenchmarksMetrics][google.ads.googleads.v25.services.BenchmarksService.GenerateBenchmarksMetrics].
 message GenerateBenchmarksMetricsResponse {
-  // Metrics belonging to the customer.
-  Metrics customer_metrics = 1;
+  // Metrics representing the customer's Ad performance.
+  CustomerMetrics customer_metrics = 4;

   // Metrics for the selected benchmarks source.
   Metrics average_benchmarks_metrics = 2;

   // Breakdown metrics grouped by dimensions.
   repeated BreakdownMetrics breakdown_metrics = 3;
 }

 // Metrics for a given breakdown.
 message BreakdownMetrics {
   // Dimensions by which the breakdown metrics are grouped by.
   BreakdownKey breakdown_key = 1;

-  // Metrics belonging to the customer.
-  Metrics customer_metrics = 2;
+  // Metrics representing the customer's Ad performance.
+  CustomerMetrics customer_metrics = 4;

   // Metrics for the selected benchmarks source.
   Metrics average_benchmarks_metrics = 3;
 }

 // Dimensions by which the breakdown metrics are grouped by.
 message BreakdownKey {
   // Dates used for the breakdown. For example, this represents the start and
   // end dates of the week for a weekly breakdown.
-  google.ads.googleads.v24.common.DateRange dates = 1;
+  google.ads.googleads.v25.common.DateRange dates = 1;
 }

 // All metrics returned against a criteria.
 message Metrics {
   // Average rate metrics calculated by dividing one metric by another.
   RateMetrics average_rate_metrics = 1;
 }

+// Metrics representing the customer’s Ad performance.
+message CustomerMetrics {
+  // Average rate metrics calculated by dividing one metric by another.
+  RateMetrics average_rate_metrics = 1;
+}
+
 // Average rate metrics. Metrics that represent monetary values are returned
 // in USD by default, if unspecified in the request.
 message RateMetrics {
   // Average cost-per-thousand impressions (CPM).
   double average_cpm = 1;

   // Average cost-per-thousand viewable impressions.
   double average_active_view_cpm = 2;

   // The average TrueView cost-per-view (CPV) is defined by the total cost of
   // all ad TrueView views divided by the number of TrueView views.
   double trueview_average_cpv = 3;

   // The average cost-per-click (CPC) is defined by the total cost of all
   // clicks divided by the total number of clicks received.
   double average_cpc = 4;

   // The average cost-per-interaction (CPI) is defined by the total cost of
   // all interactions divided by the total number of interactions.
   double average_cpi = 5;

   // The average cost-per-engagement (CPE) is defined by the total cost of all
   // ad engagements divided by the total number of ad engagements.
   double average_cpe = 6;

   // How often people interact with your ad after it is shown to them. This is
   // the number of interactions divided by the number of times your ad is
   // shown.
   double interaction_rate = 7;

   // How often people engage with your ad after it's shown to them. This is
   // the number of ad expansions divided by the number of times your ad is
   // shown.
   double engagement_rate = 8;

   // The percentage of time when your ad appeared on an Active View enabled
   // site (measurable impressions) and was viewable (viewable impressions).
   double active_view_viewability = 9;

   // Number of completed TrueView views divided by the number of impressions.
   double trueview_view_rate = 10;

   // The number of clicks your ad receives (Clicks) divided by the number
   // of times your ad is shown (Impressions).
   double click_through_rate = 11;

   // Percentage of impressions where the viewer watched 25% of your video.
   double video_completion_p25_rate = 12;

   // Percentage of impressions where the viewer watched 50% of your video.
   double video_completion_p50_rate = 13;

   // Percentage of impressions where the viewer watched 75% of your video.
   double video_completion_p75_rate = 14;

   // Percentage of impressions where the viewer watched all of your video.
   double video_completion_p100_rate = 15;
 }