> [!IMPORTANT] > **Important:** This feature is only available to accounts on an allowlist. Contact your Google representative if you need access to this feature. The [`BenchmarksService`](https://developers.google.com/google-ads/api/reference/rpc/v26/BenchmarksService.md.txt) enables advertisers and agencies to compare their YouTube ad performance against industry benchmarks. Using this service, you can evaluate how your campaigns perform relative to industry verticals or across all advertisers in specific product and service categories. ## Key capabilities With the `BenchmarksService`, you can: - **Compare performance**: Evaluate a customer's average rate metrics (such as CPM, CPV, CTR, and viewability) against aggregated industry averages. - **Analyze market share**: Understand a customer's relative market presence through share of voice (relative impressions) and share of spend. - **Evaluate competitive standing** : Measure a customer's competitive position using percentile metrics that classify performance across key dimensions into competitive tiers (such as *Market Leader* or *Competitor*). - **Segment by time**: Group benchmark metrics by weekly, monthly, or quarterly time granularities. - **Discover supported benchmark dimensions**: Query available date ranges, geographic locations, advertising products, and benchmark sources (industry verticals or product and service categories). > [!NOTE] > **Note:** You must supply a **client customer ID** in your requests. A manager account customer ID won't return customer metrics because manager accounts don't directly run ad campaigns. ## Discovery methods Before generating benchmark metrics, use the discovery methods to retrieve the valid parameters and scoping criteria for your requests. ### List available dates The [`ListBenchmarksAvailableDates`](https://developers.google.com/google-ads/api/reference/rpc/v26/BenchmarksService/ListBenchmarksAvailableDates.md.txt) method returns the historical date ranges that support benchmark data in a [`ListBenchmarksAvailableDatesResponse`](https://developers.google.com/google-ads/api/reference/rpc/v26/ListBenchmarksAvailableDatesResponse.md.txt). The response provides two distinct date ranges: - [`supported_dates`](https://developers.google.com/google-ads/api/reference/rpc/v26/ListBenchmarksAvailableDatesResponse.md.txt#supported_dates): The overall date range where benchmark metrics are supported (inclusive). Benchmark requests can query dates within this range. - [`supported_dates_for_all_metrics`](https://developers.google.com/google-ads/api/reference/rpc/v26/ListBenchmarksAvailableDatesResponse.md.txt#supported_dates_for_all_metrics) (in v25 and later): A subset of `supported_dates` that supports the full set of benchmark metrics. Certain metrics---specifically customer share metrics ([`share_of_voice`](https://developers.google.com/google-ads/api/reference/rpc/v26/ShareMetrics.md.txt#share_of_voice) and [`share_of_spend`](https://developers.google.com/google-ads/api/reference/rpc/v26/ShareMetrics.md.txt#share_of_spend)) and average rate metrics of the benchmark source---are only available within this date range due to limited data availability. These metrics are omitted from the response if the requested `date_range` does not fall completely within `supported_dates_for_all_metrics`. ### List locations The [`ListBenchmarksLocations`](https://developers.google.com/google-ads/api/reference/rpc/v26/BenchmarksService/ListBenchmarksLocations.md.txt) method returns the list of geographic locations (such as countries) that support benchmark data. Each [`BenchmarksLocation`](https://developers.google.com/google-ads/api/reference/rpc/v26/BenchmarksLocation.md.txt) in the response includes: - `location_name`: The unique location name in English (for example, `"United States"`). - `location_type`: The location type corresponding to the `target_type` in the Google Ads API (for example, `"Country"`). - `location_info`: A [`LocationInfo`](https://developers.google.com/google-ads/api/reference/rpc/v26/LocationInfo.md.txt) object containing the geographic target constant (such as `geo_target_constant: "geoTargetConstants/2840"`). ### List products The [`ListBenchmarksProducts`](https://developers.google.com/google-ads/api/reference/rpc/v26/BenchmarksService/ListBenchmarksProducts.md.txt) method returns the list of products and marketing objectives available for benchmarking. Each [`BenchmarksProductMetadata`](https://developers.google.com/google-ads/api/reference/rpc/v26/BenchmarksProductMetadata.md.txt) entry includes: - `product_name`: The user-friendly product name. - `product_code`: The unique identifier string for the product, used when constructing a [`ProductFilter`](https://developers.google.com/google-ads/api/reference/rpc/v26/ProductFilter.md.txt). - `marketing_objective`: The associated marketing objective ([`BenchmarksMarketingObjective`](https://developers.google.com/google-ads/api/reference/rpc/v26/BenchmarksMarketingObjectiveEnum.BenchmarksMarketingObjective.md.txt)): - `AWARENESS`: Campaigns designed to increase brand or product awareness. - `CONSIDERATION`: Campaigns designed to encourage potential customers to consider the brand or products. - `ACTION`: Campaigns designed to drive a specific conversion action. ### List benchmarks sources The [`ListBenchmarksSources`](https://developers.google.com/google-ads/api/reference/rpc/v26/BenchmarksService/ListBenchmarksSources.md.txt) method retrieves available benchmark sources. Specify the source types to retrieve using [`BenchmarksSourceType`](https://developers.google.com/google-ads/api/reference/rpc/v26/BenchmarksSourceTypeEnum.BenchmarksSourceType.md.txt): - `INDUSTRY_VERTICAL`: Classifications of industry segments (for example, `"Technology"` or `"Finance"`). - `CATEGORY` (in v25 and later): Product \& Service Categories (for example, `"/Apparel/Clothing"`). Categories can be used as filters to scope benchmarking when comparing against all advertisers. The response returns a list of [`BenchmarksSourceMetadata`](https://developers.google.com/google-ads/api/reference/rpc/v26/BenchmarksSourceMetadata.md.txt) objects containing either: - [`IndustryVerticalInfo`](https://developers.google.com/google-ads/api/reference/rpc/v26/IndustryVerticalInfo.md.txt): Contains `industry_vertical_name`, `industry_vertical_id`, and `parent_industry_vertical_id` (if applicable). - [`CategoryInfo`](https://developers.google.com/google-ads/api/reference/rpc/v26/CategoryInfo.md.txt) (in v25 and later): Contains `category_name`, `category_id`, and `category_path` (the full category hierarchy). ## Generate benchmark metrics Call [`GenerateBenchmarksMetrics`](https://developers.google.com/google-ads/api/reference/rpc/v26/BenchmarksService/GenerateBenchmarksMetrics.md.txt) to compare a customer's YouTube ad metrics against industry benchmarks. ### Request parameters A [`GenerateBenchmarksMetricsRequest`](https://developers.google.com/google-ads/api/reference/rpc/v26/GenerateBenchmarksMetricsRequest.md.txt) scopes the analysis. At a minimum, you must specify a client `customer_id`, geographic `location` ([`LocationInfo`](https://developers.google.com/google-ads/api/reference/rpc/v26/LocationInfo.md.txt)), a [`benchmarks_source`](https://developers.google.com/google-ads/api/reference/rpc/v26/BenchmarksSource.md.txt) (either an `industry_vertical_id` or, in v25 and later, `all_advertisers` scoped by [`category_filter`](https://developers.google.com/google-ads/api/reference/rpc/v26/CategoryFilter.md.txt)), and a [`product_filter`](https://developers.google.com/google-ads/api/reference/rpc/v26/ProductFilter.md.txt). You can optionally: - Provide a [`date_range`](https://developers.google.com/google-ads/api/reference/rpc/v26/DateRange.md.txt) (if omitted, data is returned for the most recent quarter with available data). - Group metrics with a [`breakdown_definition`](https://developers.google.com/google-ads/api/reference/rpc/v26/BreakdownDefinition.md.txt). - Specify a three-character ISO 4217 `currency_code` (if omitted, monetary metrics such as CPM and cost default to `USD`). - Specify a user-defined `customer_benchmarks_group` name for the customer being planned for. - Request additional features such as [`PERCENTILE_DATA`](https://developers.google.com/google-ads/api/reference/rpc/v26/BenchmarksSupplementalDataEnum.BenchmarksSupplementalData.md.txt#percentile_data) through `supplemental_data` (in v25 and later). For full parameter definitions and requirements, refer to the [`GenerateBenchmarksMetricsRequest`](https://developers.google.com/google-ads/api/reference/rpc/v26/GenerateBenchmarksMetricsRequest.md.txt) reference documentation. ### Date breakdowns You can group metrics by setting `breakdown_definition.date_breakdown` using [`BenchmarksTimeGranularity`](https://developers.google.com/google-ads/api/reference/rpc/v26/BenchmarksTimeGranularityEnum.BenchmarksTimeGranularity.md.txt). When `date_breakdown` is set, `date_range` in [`GenerateBenchmarksMetricsRequest`](https://developers.google.com/google-ads/api/reference/rpc/v26/GenerateBenchmarksMetricsRequest.md.txt) is required and must align with the boundaries of the selected granularity: - `WEEK`: Aggregates metrics by week. The `date_range` must start on a **Sunday** and end on a **Saturday** (note that this differs from ISO 8601). - `MONTH`: Aggregates metrics by month. The `date_range` must start on the first day of the month and end on the last day of the month. - `QUARTER`: Aggregates metrics by calendar quarter. The `date_range` must start on the first day of the quarter and end on the last day of the quarter. ### Response metrics The [`GenerateBenchmarksMetricsResponse`](https://developers.google.com/google-ads/api/reference/rpc/v26/GenerateBenchmarksMetricsResponse.md.txt) returns: - [`customer_metrics`](https://developers.google.com/google-ads/api/reference/rpc/v26/CustomerMetrics.md.txt) (of type [`CustomerMetrics`](https://developers.google.com/google-ads/api/reference/rpc/v26/CustomerMetrics.md.txt) in v25 and later; of type [`Metrics`](https://developers.google.com/google-ads/api/reference/rpc/v26/services.Metrics.md.txt) containing only `average_rate_metrics` in v24 and earlier): Metrics representing a customer's YouTube ad performance, including: - [`average_rate_metrics`](https://developers.google.com/google-ads/api/reference/rpc/v26/RateMetrics.md.txt): Average rate metrics for the customer. - [`share_metrics`](https://developers.google.com/google-ads/api/reference/rpc/v26/ShareMetrics.md.txt) (in v25 and later): Relative market presence metrics (`share_of_voice` and `share_of_spend`). Populated only when `benchmarks_source` selects `all_advertisers = true` (with `category_filter` set) and `date_range` falls within `supported_dates_for_all_metrics`. - [`aggregate_metrics`](https://developers.google.com/google-ads/api/reference/rpc/v26/AggregateMetrics.md.txt) (in v25 and later): Aggregated totals for the customer (such as `cost`, `impressions`, `clicks`, and `video_trueview_views`). - [`percentile_metrics`](https://developers.google.com/google-ads/api/reference/rpc/v26/PercentileMetrics.md.txt) (in v25 and later): Competitive standing percentile tiers across key dimensions. - [`average_benchmarks_metrics`](https://developers.google.com/google-ads/api/reference/rpc/v26/services.Metrics.md.txt): Aggregated rate metrics ([`RateMetrics`](https://developers.google.com/google-ads/api/reference/rpc/v26/RateMetrics.md.txt)) across the selected benchmark source. - [`breakdown_metrics`](https://developers.google.com/google-ads/api/reference/rpc/v26/BreakdownMetrics.md.txt): A list of metrics segmented by the breakdowns defined in `breakdown_definition`. For complete field specifications, refer to the [`GenerateBenchmarksMetricsResponse`](https://developers.google.com/google-ads/api/reference/rpc/v26/GenerateBenchmarksMetricsResponse.md.txt) reference documentation. ### Percentile metrics > [!NOTE] > **Note:** `supplemental_data` ([`BenchmarksSupplementalData`](https://developers.google.com/google-ads/api/reference/rpc/v26/BenchmarksSupplementalDataEnum.BenchmarksSupplementalData.md.txt#percentile_data)) and [`percentile_metrics`](https://developers.google.com/google-ads/api/reference/rpc/v26/PercentileMetrics.md.txt) are available in v25 and later. Percentile metrics represent a customer's competitive standing as percentile tiers among other advertisers within the scoped analysis. #### Prerequisites To retrieve percentile metrics, your request must meet the following requirements: 1. **Benchmarks source** : `benchmarks_source` must select `all_advertisers = true`. 2. **Category filter** : `category_filter` must be provided, containing one or more valid `category_ids` retrieved from `ListBenchmarksSources`. 3. **Supplemental data** : You must add [`PERCENTILE_DATA`](https://developers.google.com/google-ads/api/reference/rpc/v26/BenchmarksSupplementalDataEnum.BenchmarksSupplementalData.md.txt#percentile_data) to the `supplemental_data` field in [`GenerateBenchmarksMetricsRequest`](https://developers.google.com/google-ads/api/reference/rpc/v26/GenerateBenchmarksMetricsRequest.md.txt). #### Percentile tiers A customer's performance is classified into one of the following [`BenchmarksCustomerPercentileTier`](https://developers.google.com/google-ads/api/reference/rpc/v26/BenchmarksCustomerPercentileTierEnum.BenchmarksCustomerPercentileTier.md.txt) enum values: - `DEVELOPING`: Below the 10th percentile (`[0%, 10%)`). - `ENTRY_LEVEL`: 10th to 25th percentile (`[10%, 25%)`). - `EMERGING_PLAYER`: 25th to 50th percentile (`[25%, 50%)`). - `COMPETITOR`: 50th to 75th percentile (`[50%, 75%)`). - `STRONG_COMPETITOR`: 75th to 90th percentile (`[75%, 90%)`). - `MARKET_LEADER`: At or above the 90th percentile (`[90%, 100%]`). #### Example request The following example illustrates a REST JSON request payload to generate benchmark metrics with percentile tiers for a user comparing their customer's YouTube ads performance against other advertisers running ads in the `/Apparel/Clothing` category: ```json { "customerId": "1234567890", "location": { "geoTargetConstant": "geoTargetConstants/2840" }, "benchmarksSource": { "allAdvertisers": true }, "categoryFilter": { "categoryIds": ["10176"] }, "productFilter": { "marketingObjectiveList": { "marketingObjectives": ["AWARENESS", "CONSIDERATION"] } }, "supplementalData": [ "PERCENTILE_DATA" ] } ``` The response including the additional percentile data requested: ```json { "customerMetrics": { "averageRateMetrics": { "averageCpm": 5.42, "clickThroughRate": 0.0185 }, "shareMetrics": { "shareOfVoice": 0.0345, "shareOfSpend": 0.0410 }, "aggregateMetrics": { "cost": 15200.0, "impressions": 2800000.0, "clicks": 51800.0 }, "percentileMetrics": { "costPercentileTier": "STRONG_COMPETITOR", "impressionsPercentileTier": "STRONG_COMPETITOR", "clicksPercentileTier": "MARKET_LEADER", "videoTrueviewViewsPercentileTier": "COMPETITOR", "viewableImpressionsPercentileTier": "STRONG_COMPETITOR", "interactionsPercentileTier": "MARKET_LEADER", "engagementsPercentileTier": "COMPETITOR" } }, "averageBenchmarksMetrics": { "averageRateMetrics": { "averageCpm": 6.15, "clickThroughRate": 0.0142 } } } ``` ## Error handling When calling the `BenchmarksService`, you may encounter errors specific to benchmarks queries in [`BenchmarksError`](https://developers.google.com/google-ads/api/reference/rpc/v26/BenchmarksErrorEnum.BenchmarksError.md.txt): - [`MAX_QUERY_COMPLEXITY_EXCEEDED`](https://developers.google.com/google-ads/api/reference/rpc/v26/BenchmarksErrorEnum.BenchmarksError.md.txt#max_query_complexity_exceeded): The combination of requested inputs is too complex to process. To reduce query complexity: - Select a more specific or granular benchmark source or category filter. - Shorten the requested `date_range`. - Reduce the number of products in `product_filter`. - [`NO_METRICS_FOUND`](https://developers.google.com/google-ads/api/reference/rpc/v26/BenchmarksErrorEnum.BenchmarksError.md.txt#no_metrics_found) (in v25 and later): No metrics were found for the requested combination of inputs (for example, a niche category in a specific location and date range where no advertisers ran campaigns). Try adjusting the category, location, date range, or products. For general API error handling and best practices, refer to the [Error handling guide](https://developers.google.com/google-ads/api/docs/best-practices/understand-api-errors.md.txt). ## Google Issue Tracker Use Google Issue Tracker to ask support questions, report bugs, or submit feature requests. Google tracks, prioritizes, and posts updates on your requests directly in Issue Tracker. For more information, see [Create an issue in Google Issue Tracker](https://developers.google.com/issue-tracker/guides/create-issue-ui). Create an issue by using one of the following Issue Tracker templates: - [Ask a general support question or submit documentation feedback](https://issuetracker.google.com/issues/new?component=2315943&template=2440256) - [Report a technical bug](https://issuetracker.google.com/issues/new?component=2315943&template=2440158) - [Submit an API feature request](https://issuetracker.google.com/issues/new?component=2315943&template=2440255) Fill out all fields in the template with detailed information so that Google can reproduce and prioritize your request. Google might close incomplete reports and ask you to submit a new issue with the missing details.