YouTube benchmarks

The BenchmarksService 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).

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 method returns the historical date ranges that support benchmark data in a ListBenchmarksAvailableDatesResponse.

The response provides two distinct date ranges:

  • 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 (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 and 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 method returns the list of geographic locations (such as countries) that support benchmark data.

Each BenchmarksLocation 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 object containing the geographic target constant (such as geo_target_constant: "geoTargetConstants/2840").

List products

The ListBenchmarksProducts method returns the list of products and marketing objectives available for benchmarking.

Each BenchmarksProductMetadata entry includes:

  • product_name: The user-friendly product name.
  • product_code: The unique identifier string for the product, used when constructing a ProductFilter.
  • marketing_objective: The associated marketing objective (BenchmarksMarketingObjective):
    • 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 method retrieves available benchmark sources. Specify the source types to retrieve using BenchmarksSourceType:

  • 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 objects containing either:

  • IndustryVerticalInfo: Contains industry_vertical_name, industry_vertical_id, and parent_industry_vertical_id (if applicable).
  • CategoryInfo (in v25 and later): Contains category_name, category_id, and category_path (the full category hierarchy).

Generate benchmark metrics

Call GenerateBenchmarksMetrics to compare a customer's YouTube ad metrics against industry benchmarks.

Request parameters

A GenerateBenchmarksMetricsRequest scopes the analysis. At a minimum, you must specify a client customer_id, geographic location (LocationInfo), a benchmarks_source (either an industry_vertical_id or, in v25 and later, all_advertisers scoped by category_filter), and a product_filter. You can optionally:

  • Provide a date_range (if omitted, data is returned for the most recent quarter with available data).
  • Group metrics with a breakdown_definition.
  • 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 through supplemental_data (in v25 and later).

For full parameter definitions and requirements, refer to the GenerateBenchmarksMetricsRequest reference documentation.

Date breakdowns

You can group metrics by setting breakdown_definition.date_breakdown using BenchmarksTimeGranularity. When date_breakdown is set, date_range in GenerateBenchmarksMetricsRequest 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 returns:

  • customer_metrics (of type CustomerMetrics in v25 and later; of type Metrics containing only average_rate_metrics in v24 and earlier): Metrics representing a customer's YouTube ad performance, including:
    • average_rate_metrics: Average rate metrics for the customer.
    • share_metrics (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 (in v25 and later): Aggregated totals for the customer (such as cost, impressions, clicks, and video_trueview_views).
    • percentile_metrics (in v25 and later): Competitive standing percentile tiers across key dimensions.
  • average_benchmarks_metrics: Aggregated rate metrics (RateMetrics) across the selected benchmark source.
  • breakdown_metrics: A list of metrics segmented by the breakdowns defined in breakdown_definition.

For complete field specifications, refer to the GenerateBenchmarksMetricsResponse reference documentation.

Percentile metrics

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 to the supplemental_data field in GenerateBenchmarksMetricsRequest.

Percentile tiers

A customer's performance is classified into one of the following BenchmarksCustomerPercentileTier 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:

{
  "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:

{
  "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:

  • 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 (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.

Previous
YouTube creator insights