// 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;

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/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 java_multiple_files = true;
option java_outer_classname = "BenchmarksServiceProto";
option java_package = "com.google.ads.googleads.v24.services";
option objc_class_prefix = "GAA";
option php_namespace = "Google\\Ads\\GoogleAds\\V24\\Services";
option ruby_package = "Google::Ads::GoogleAds::V24::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"
      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"
      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"
      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"
      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"
      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].
message ListBenchmarksAvailableDatesRequest {
  // Additional information on the application issuing the request.
  google.ads.googleads.v24.common.AdditionalApplicationInfo application_info =
      1;
}

// Response message for
// [BenchmarksService.ListBenchmarksAvailableDates][google.ads.googleads.v24.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;
}

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

// Response message for
// [BenchmarksService.ListBenchmarksLocations][google.ads.googleads.v24.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;
}

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

// Response message for
// [BenchmarksService.ListBenchmarksProducts][google.ads.googleads.v24.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].
  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
      .BenchmarksMarketingObjective marketing_objective = 3;
}

// Request message for
// [BenchmarksService.ListBenchmarksSources][google.ads.googleads.v24.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
      .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 =
      2;
}

// Response message for
// [BenchmarksService.ListBenchmarksSources][google.ads.googleads.v24.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
      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].
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;

  // Required. The location to generate benchmarks metrics for.
  google.ads.googleads.v24.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 =
      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].
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
        .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
      .BenchmarksTimeGranularity date_breakdown = 1;
}

// Response message for
// [BenchmarksService.GenerateBenchmarksMetrics][google.ads.googleads.v24.services.BenchmarksService.GenerateBenchmarksMetrics].
message GenerateBenchmarksMetricsResponse {
  // Metrics belonging to the customer.
  Metrics customer_metrics = 1;

  // 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 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;
}

// All metrics returned against a criteria.
message Metrics {
  // 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;
}