--- v24/services/benchmarks_service.proto 2026-08-13 23:22:22.000000000 +0000 +++ v25/services/benchmarks_service.proto 2026-08-13 23:22:30.000000000 +0000 @@ -240,13 +241,16 @@ // 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; + + // Information on the Product & Service Category. + CategoryInfo category_info = 3; } } @@ -262,8 +266,20 @@ int64 parent_industry_vertical_id = 3; } +// The information associated with a Product & Service Category. +message CategoryInfo { + // The name of the Product & Service Category. + string category_name = 1; + + // The unique identifier of the Product & Service Category. + int64 category_id = 2; + + // The full path of the Product & Service Category. + string category_path = 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 @@ -273,17 +289,27 @@ // 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]; + // A list of Product & Service Categories for scoping a YouTube benchmarks + // analysis. For example, when category "/Apparel/Clothing" is selected, + // customer metrics represent Ad performance for "/Apparel/Clothing" Ads only + // and the customer is benchmarking against all advertisers’ Ads in the + // "/Apparel/Clothing" category. + // + // This filter can only be used when `all_advertisers` is used as the + // [benchmarks_source][google.ads.googleads.v25.services.GenerateBenchmarksMetricsRequest.benchmarks_source]. + CategoryFilter category_filter = 10; + // 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]; @@ -307,15 +333,31 @@ // 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; + + // Comparison against all advertisers running Ads. This benchmarking option + // must utilize additional filters. Setting the `category_filter` is + // required. One or more categories will scope the metrics of both the + // customer and all advertisers to those selected categories. + bool all_advertisers = 2; } } +// A list of Product & Service Categories for scoping benchmarks. +message CategoryFilter { + // Required. Product & Service Category IDs. The supported list of IDs can be + // retrieved using + // [BenchmarksService.ListBenchmarksSources][google.ads.googleads.v25.services.BenchmarksService.ListBenchmarksSources]. + // The scope of benchmarks analysis will be the union (ORs) of all categories + // supplied. + repeated string category_ids = 1 [(google.api.field_behavior) = REQUIRED]; +} + // The type and list of products to aggregate benchmarks metrics over. message ProductFilter { // The list of products to generate benchmarks metrics for. @@ -359,10 +401,10 @@ } // 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; @@ -376,8 +418,8 @@ // 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; @@ -396,6 +438,23 @@ 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; + + // Metrics calculated by dividing the metric of the customer by that of the + // selected benchmarks source. These metrics are only returned when: + // + // 1. `all_advertisers` is used as the `benchmarks_source`. Note that the + // request `category_filter` must be set when using `all_advertisers`. + ShareMetrics share_metrics = 2; + + // Metrics calculated by aggregating values of a single metric for the + // customer. + AggregateMetrics aggregate_metrics = 3; +} + // Average rate metrics. Metrics that represent monetary values are returned // in USD by default, if unspecified in the request. message RateMetrics { @@ -454,3 +513,61 @@ // Percentage of impressions where the viewer watched all of your video. double video_completion_p100_rate = 15; } + +// Metrics calculated by dividing the metric of the customer by that of the +// selected benchmarks source. +message ShareMetrics { + // Relative impressions. Share of voice is defined by the customer’s total + // number of impressions divided by the aggregated number of impressions of + // all advertisers in the selected benchmarks source including your own. Share + // of voice is represented on a scale of 0 to 1 precise to 4 decimal places. + // For example, 0.0123 which corresponds to 1.23%. + double share_of_voice = 1; + + // Relative spend. Share of spend is defined by the customer’s total cost + // divided by the total aggregated cost of all advertisers in the selected + // benchmarks source including your own. Share of spend is represented on a + // scale of 0 to 1 precise to 4 decimal places. For example, 0.0123 which + // corresponds to 1.23%. + double share_of_spend = 2; +} + +// Metrics calculated by aggregating values of a single metric. +message AggregateMetrics { + // The total cost paid by the customer. Cost is represented in USD by default, + // if unspecified in the request. + double cost = 1; + + // The number of video TrueView views. + // + // See https://support.google.com/google-ads/answer/2375431 for more + // information on TrueView Views. + double video_trueview_views = 2; + + // The number of times the Ad was shown to users. + double impressions = 3; + + // The number of impressions that are considered viewable according to the + // Active View criteria. + // + // See https://support.google.com/google-ads/answer/7029393 for more + // information on Active View. + double viewable_impressions = 4; + + // The number of clicks received. + double clicks = 5; + + // The number of interactions. Interactions include physical clicks, + // engagements, and video views that are logged as clicks. + // + // See https://support.google.com/google-ads/answer/2375431 for more + // information on interactions. + double interactions = 6; + + // The number of engagements. Engagements are ad interactions such as + // expanding a lightbox Ad or clicking on a video teaser. + // + // See https://support.google.com/google-ads/answer/2375431 for more + // information on engagements. + double engagements = 7; +}
/services/benchmarks_service.proto
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 2026-08-16 UTC.