// 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.v21.services;

import "google/ads/googleads/v21/common/additional_application_info.proto";
import "google/ads/googleads/v21/common/audience_insights_attribute.proto";
import "google/ads/googleads/v21/common/criteria.proto";
import "google/ads/googleads/v21/common/dates.proto";
import "google/ads/googleads/v21/enums/audience_insights_dimension.proto";
import "google/ads/googleads/v21/enums/audience_insights_marketing_objective.proto";
import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";

option csharp_namespace = "Google.Ads.GoogleAds.V21.Services";
option go_package = "google.golang.org/genproto/googleapis/ads/googleads/v21/services;services";
option java_multiple_files = true;
option java_outer_classname = "AudienceInsightsServiceProto";
option java_package = "com.google.ads.googleads.v21.services";
option objc_class_prefix = "GAA";
option php_namespace = "Google\\Ads\\GoogleAds\\V21\\Services";
option ruby_package = "Google::Ads::GoogleAds::V21::Services";

// Proto file describing the audience insights service.

// Audience Insights Service helps users find information about groups of
// people and how they can be reached with Google Ads. Accessible to
// allowlisted customers only.
service AudienceInsightsService {
  option (google.api.default_host) = "googleads.googleapis.com";
  option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/adwords";

  // Creates a saved report that can be viewed in the Insights Finder tool.
  //
  // List of thrown errors:
  //   [AuthenticationError]()
  //   [AuthorizationError]()
  //   [FieldError]()
  //   [HeaderError]()
  //   [InternalError]()
  //   [QuotaError]()
  //   [RangeError]()
  //   [RequestError]()
  rpc GenerateInsightsFinderReport(GenerateInsightsFinderReportRequest)
      returns (GenerateInsightsFinderReportResponse) {
    option (google.api.http) = {
      post: "/v21/customers/{customer_id=*}:generateInsightsFinderReport"
      body: "*"
    };
    option (google.api.method_signature) =
        "customer_id,baseline_audience,specific_audience";
  }

  // Searches for audience attributes that can be used to generate insights.
  //
  // List of thrown errors:
  //   [AuthenticationError]()
  //   [AuthorizationError]()
  //   [FieldError]()
  //   [HeaderError]()
  //   [InternalError]()
  //   [QuotaError]()
  //   [RangeError]()
  //   [RequestError]()
  rpc ListAudienceInsightsAttributes(ListAudienceInsightsAttributesRequest)
      returns (ListAudienceInsightsAttributesResponse) {
    option (google.api.http) = {
      post: "/v21/customers/{customer_id=*}:searchAudienceInsightsAttributes"
      body: "*"
    };
    option (google.api.method_signature) = "customer_id,dimensions,query_text";
  }

  // Lists date ranges for which audience insights data can be requested.
  //
  // List of thrown errors:
  //   [AuthenticationError]()
  //   [AuthorizationError]()
  //   [FieldError]()
  //   [HeaderError]()
  //   [InternalError]()
  //   [QuotaError]()
  //   [RangeError]()
  //   [RequestError]()
  rpc ListInsightsEligibleDates(ListInsightsEligibleDatesRequest)
      returns (ListInsightsEligibleDatesResponse) {
    option (google.api.http) = {
      post: "/v21/audienceInsights:listInsightsEligibleDates"
      body: "*"
    };
  }

  // Returns a collection of attributes that are represented in an audience of
  // interest, with metrics that compare each attribute's share of the audience
  // with its share of a baseline audience.
  //
  // List of thrown errors:
  //   [AudienceInsightsError]()
  //   [AuthenticationError]()
  //   [AuthorizationError]()
  //   [FieldError]()
  //   [HeaderError]()
  //   [InternalError]()
  //   [QuotaError]()
  //   [RangeError]()
  //   [RequestError]()
  rpc GenerateAudienceCompositionInsights(
      GenerateAudienceCompositionInsightsRequest)
      returns (GenerateAudienceCompositionInsightsResponse) {
    option (google.api.http) = {
      post: "/v21/customers/{customer_id=*}:generateAudienceCompositionInsights"
      body: "*"
    };
    option (google.api.method_signature) = "customer_id,audience,dimensions";
  }

  // Returns a collection of targeting insights (e.g. targetable audiences) that
  // are relevant to the requested audience.
  //
  // List of thrown errors:
  //   [AudienceInsightsError]()
  //   [AuthenticationError]()
  //   [AuthorizationError]()
  //   [FieldError]()
  //   [HeaderError]()
  //   [InternalError]()
  //   [QuotaError]()
  //   [RangeError]()
  //   [RequestError]()
  rpc GenerateSuggestedTargetingInsights(
      GenerateSuggestedTargetingInsightsRequest)
      returns (GenerateSuggestedTargetingInsightsResponse) {
    option (google.api.http) = {
      post: "/v21/customers/{customer_id=*}:generateSuggestedTargetingInsights"
      body: "*"
    };
  }

  // Returns a collection of audience attributes along with estimates of the
  // overlap between their potential YouTube reach and that of a given input
  // attribute.
  //
  // List of thrown errors:
  //   [AudienceInsightsError]()
  //   [AuthenticationError]()
  //   [AuthorizationError]()
  //   [FieldError]()
  //   [HeaderError]()
  //   [InternalError]()
  //   [QuotaError]()
  //   [RangeError]()
  //   [RequestError]()
  rpc GenerateAudienceOverlapInsights(GenerateAudienceOverlapInsightsRequest)
      returns (GenerateAudienceOverlapInsightsResponse) {
    option (google.api.http) = {
      post: "/v21/customers/{customer_id=*}:generateAudienceOverlapInsights"
      body: "*"
    };
    option (google.api.method_signature) =
        "customer_id,country_location,primary_attribute,dimensions";
  }

  // Returns potential reach metrics for targetable audiences.
  //
  // This method helps answer questions like "How many Men aged 18+ interested
  // in Camping can be reached on YouTube?"
  //
  // List of thrown errors:
  //   [AudienceInsightsError]()
  //   [AuthenticationError]()
  //   [AuthorizationError]()
  //   [FieldError]()
  //   [HeaderError]()
  //   [InternalError]()
  //   [QuotaError]()
  //   [RangeError]()
  //   [RequestError]()
  rpc GenerateTargetingSuggestionMetrics(
      GenerateTargetingSuggestionMetricsRequest)
      returns (GenerateTargetingSuggestionMetricsResponse) {
    option (google.api.http) = {
      post: "/v21/customers/{customer_id=*}:generateTargetingSuggestionMetrics"
      body: "*"
    };
    option (google.api.method_signature) = "customer_id,audiences";
  }
}

// Request message for
// [AudienceInsightsService.GenerateInsightsFinderReport][google.ads.googleads.v21.services.AudienceInsightsService.GenerateInsightsFinderReport].
message GenerateInsightsFinderReportRequest {
  // Required. The ID of the customer.
  string customer_id = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. A baseline audience for this report, typically all people in a
  // region.
  BasicInsightsAudience baseline_audience = 2
      [(google.api.field_behavior) = REQUIRED];

  // Required. The specific audience of interest for this report.  The insights
  // in the report will be based on attributes more prevalent in this audience
  // than in the report's baseline audience.
  BasicInsightsAudience specific_audience = 3
      [(google.api.field_behavior) = REQUIRED];

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

  // Optional. Additional information on the application issuing the request.
  google.ads.googleads.v21.common.AdditionalApplicationInfo
      insights_application_info = 5 [(google.api.field_behavior) = OPTIONAL];
}

// The response message for
// [AudienceInsightsService.GenerateInsightsFinderReport][google.ads.googleads.v21.services.AudienceInsightsService.GenerateInsightsFinderReport],
// containing the shareable URL for the report.
message GenerateInsightsFinderReportResponse {
  // An HTTPS URL providing a deep link into the Insights Finder UI with the
  // report inputs filled in according to the request.
  string saved_report_url = 1;
}

// Request message for
// [AudienceInsightsService.GenerateAudienceCompositionInsights][google.ads.googleads.v21.services.AudienceInsightsService.GenerateAudienceCompositionInsights].
message GenerateAudienceCompositionInsightsRequest {
  // Required. The ID of the customer.
  string customer_id = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. The audience of interest for which insights are being requested.
  InsightsAudience audience = 2 [(google.api.field_behavior) = REQUIRED];

  // The baseline audience to which the audience of interest is being
  // compared.
  InsightsAudience baseline_audience = 6;

  // The one-month range of historical data to use for insights, in the format
  // "yyyy-mm". If unset, insights will be returned for the last thirty days of
  // data.
  string data_month = 3;

  // Required. The audience dimensions for which composition insights should be
  // returned. Supported dimensions are KNOWLEDGE_GRAPH, GEO_TARGET_COUNTRY,
  // SUB_COUNTRY_LOCATION, YOUTUBE_CHANNEL, YOUTUBE_LINEUP,
  // AFFINITY_USER_INTEREST, IN_MARKET_USER_INTEREST, PARENTAL_STATUS,
  // INCOME_RANGE, AGE_RANGE, and GENDER.
  repeated google.ads.googleads.v21.enums.AudienceInsightsDimensionEnum
      .AudienceInsightsDimension dimensions = 4
      [(google.api.field_behavior) = REQUIRED];

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

  // Optional. Additional information on the application issuing the request.
  google.ads.googleads.v21.common.AdditionalApplicationInfo
      insights_application_info = 7 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for
// [AudienceInsightsService.GenerateAudienceCompositionInsights][google.ads.googleads.v21.services.AudienceInsightsService.GenerateAudienceCompositionInsights].
message GenerateAudienceCompositionInsightsResponse {
  // The contents of the insights report, organized into sections.
  // Each section is associated with one of the AudienceInsightsDimension values
  // in the request. There may be more than one section per dimension.
  repeated AudienceCompositionSection sections = 1;
}

// Request message for
// [AudienceInsightsService.GenerateSuggestedTargetingInsights][google.ads.googleads.v21.services.AudienceInsightsService.GenerateSuggestedTargetingInsights].
message GenerateSuggestedTargetingInsightsRequest {
  // Required. The ID of the customer.
  string customer_id = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. The name of the customer being planned for.  This is a
  // user-defined value.
  string customer_insights_group = 5 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Additional information on the application issuing the request.
  google.ads.googleads.v21.common.AdditionalApplicationInfo
      insights_application_info = 8 [(google.api.field_behavior) = OPTIONAL];

  // Required. The audience to get suggestions for.
  oneof audience_input {
    // Provide a seed audience to get suggestions for.
    InsightsAudienceDefinition audience_definition = 6;

    // Provide a text description of an audience to get AI-generated targeting
    // suggestions. This can take around 5 or more seconds to complete.
    InsightsAudienceDescription audience_description = 7;
  }
}

// Response message for
// [AudienceInsightsService.GenerateSuggestedTargetingInsights][google.ads.googleads.v21.services.AudienceInsightsService.GenerateSuggestedTargetingInsights].
message GenerateSuggestedTargetingInsightsResponse {
  // Suggested insights for targetable audiences.
  repeated TargetingSuggestionMetrics suggestions = 1;
}

// A suggested targetable audience relevant to the requested audience.
message TargetingSuggestionMetrics {
  // Suggested location targeting.  These attributes all have dimension
  // GEO_TARGET_COUNTRY or SUB_COUNTRY_LOCATION
  repeated google.ads.googleads.v21.common.AudienceInsightsAttributeMetadata
      locations = 9;

  // Suggested age targeting; may be empty indicating no age targeting.
  repeated google.ads.googleads.v21.common.AgeRangeInfo age_ranges = 2;

  // Suggested gender targeting.  If present, this attribute has dimension
  // GENDER.
  google.ads.googleads.v21.common.GenderInfo gender = 3;

  // A Parental Status value (parent, or not a parent).
  google.ads.googleads.v21.common.ParentalStatusInfo parental_status = 8;

  // List of user interest attributes with metadata defining the audience. The
  // combination has a logical AND-of-ORs structure: The attributes within each
  // AudienceInsightsAttributeMetadataGroup are ORed, and the groups themselves
  // are ANDed.
  repeated
      google.ads.googleads.v21.common.AudienceInsightsAttributeMetadataGroup
          user_interests = 11;

  // The fraction (from 0 to 1 inclusive) of the requested audience that can be
  // reached using the suggested targeting.
  double coverage = 5;

  // The ratio of coverage to the coverage of the baseline audience or zero if
  // this ratio is undefined or is not meaningful.
  double index = 6;

  // The approximate estimated number of people that can be reached on YouTube
  // using this targeting.
  int64 potential_youtube_reach = 7;
}

// Request message for
// [AudienceInsightsService.ListAudienceInsightsAttributes][google.ads.googleads.v21.services.AudienceInsightsService.ListAudienceInsightsAttributes].
message ListAudienceInsightsAttributesRequest {
  // Required. The ID of the customer.
  string customer_id = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. The types of attributes to be returned. Supported
  // dimensions are CATEGORY, KNOWLEDGE_GRAPH, DEVICE,
  // GEO_TARGET_COUNTRY, SUB_COUNTRY_LOCATION, YOUTUBE_LINEUP,
  // AFFINITY_USER_INTEREST, IN_MARKET_USER_INTEREST, PARENTAL_STATUS,
  // INCOME_RANGE, AGE_RANGE, and GENDER.
  repeated google.ads.googleads.v21.enums.AudienceInsightsDimensionEnum
      .AudienceInsightsDimension dimensions = 2
      [(google.api.field_behavior) = REQUIRED];

  // Required. A free text query.  If the requested dimensions include
  // Attributes CATEGORY or KNOWLEDGE_GRAPH, then the attributes returned for
  // those dimensions will match or be related to this string.  For other
  // dimensions, this field is ignored and all available attributes are
  // returned.
  string query_text = 3 [(google.api.field_behavior) = REQUIRED];

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

  // Optional. Additional information on the application issuing the request.
  google.ads.googleads.v21.common.AdditionalApplicationInfo
      insights_application_info = 7 [(google.api.field_behavior) = OPTIONAL];

  // If SUB_COUNTRY_LOCATION attributes are one of the requested dimensions and
  // this field is present, then the SUB_COUNTRY_LOCATION attributes returned
  // will be located in these countries. If this field is absent, then location
  // attributes are not filtered by country. Setting this field when
  // SUB_COUNTRY_LOCATION attributes are not requested will return an error.
  repeated google.ads.googleads.v21.common.LocationInfo
      location_country_filters = 5;

  // If present, potential YouTube reach estimates within the specified market
  // will be returned for attributes for which they are available.  Reach is
  // only available for the AGE_RANGE, GENDER, AFFINITY_USER_INTEREST and
  // IN_MARKET_USER_INTEREST dimensions, and may not be available for every
  // attribute of those dimensions in every market.
  google.ads.googleads.v21.common.LocationInfo youtube_reach_location = 6;
}

// Response message for
// [AudienceInsightsService.ListAudienceInsightsAttributes][google.ads.googleads.v21.services.AudienceInsightsService.ListAudienceInsightsAttributes].
message ListAudienceInsightsAttributesResponse {
  // The attributes matching the search query.
  repeated google.ads.googleads.v21.common.AudienceInsightsAttributeMetadata
      attributes = 2;
}

// Request message for
// [AudienceInsightsService.ListInsightsEligibleDates][google.ads.googleads.v21.services.AudienceInsightsService.ListInsightsEligibleDates].
message ListInsightsEligibleDatesRequest {
  // Optional. Additional information on the application issuing the request.
  google.ads.googleads.v21.common.AdditionalApplicationInfo
      insights_application_info = 1 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for
// [AudienceInsightsService.ListInsightsEligibleDates][google.ads.googleads.v21.services.AudienceInsightsService.ListInsightsEligibleDates].
message ListInsightsEligibleDatesResponse {
  // The months for which AudienceInsights data is currently
  // available, each represented as a string in the form "YYYY-MM".
  repeated string data_months = 1;

  // The actual dates covered by the "last 30 days" date range that will be used
  // implicitly for
  // [AudienceInsightsService.GenerateAudienceCompositionInsights][google.ads.googleads.v21.services.AudienceInsightsService.GenerateAudienceCompositionInsights]
  // requests that have no data_month set.
  google.ads.googleads.v21.common.DateRange last_thirty_days = 2;
}

// Request message for
// [AudienceInsightsService.GenerateAudienceOverlapInsights][google.ads.googleads.v21.services.AudienceInsightsService.GenerateAudienceOverlapInsights].
message GenerateAudienceOverlapInsightsRequest {
  // Required. The ID of the customer.
  string customer_id = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. The country in which to calculate the sizes and overlaps of
  // audiences.
  google.ads.googleads.v21.common.LocationInfo country_location = 2
      [(google.api.field_behavior) = REQUIRED];

  // Required. The audience attribute that should be intersected with all other
  // eligible audiences.  This must be an Affinity or In-Market UserInterest, an
  // AgeRange or a Gender.
  google.ads.googleads.v21.common.AudienceInsightsAttribute primary_attribute =
      6 [(google.api.field_behavior) = REQUIRED];

  // Required. The types of attributes of which to calculate the overlap with
  // the primary_attribute. The values must be a subset of
  // AFFINITY_USER_INTEREST, IN_MARKET_USER_INTEREST, AGE_RANGE and GENDER.
  repeated google.ads.googleads.v21.enums.AudienceInsightsDimensionEnum
      .AudienceInsightsDimension dimensions = 4
      [(google.api.field_behavior) = REQUIRED];

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

  // Optional. Additional information on the application issuing the request.
  google.ads.googleads.v21.common.AdditionalApplicationInfo
      insights_application_info = 7 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for
// [AudienceInsightsService.GenerateAudienceOverlapInsights][google.ads.googleads.v21.services.AudienceInsightsService.GenerateAudienceOverlapInsights].
message GenerateAudienceOverlapInsightsResponse {
  // Metadata for the primary attribute, including potential YouTube reach.
  google.ads.googleads.v21.common.AudienceInsightsAttributeMetadata
      primary_attribute_metadata = 3;

  // Lists of attributes and their overlap with the primary attribute, one list
  // per requested dimension.
  repeated DimensionOverlapResult dimension_results = 2;
}

// A list of audience attributes of a single dimension, including their overlap
// with a primary attribute, returned as part of a
// [GenerateAudienceOverlapInsightsResponse][google.ads.googleads.v21.services.GenerateAudienceOverlapInsightsResponse].
message DimensionOverlapResult {
  // The dimension of all the attributes in this section.
  google.ads.googleads.v21.enums.AudienceInsightsDimensionEnum
      .AudienceInsightsDimension dimension = 1;

  // The attributes and their overlap with the primary attribute.
  repeated AudienceOverlapItem items = 2;
}

// An audience attribute, with metadata including the overlap between this
// attribute's potential YouTube reach and that of a primary attribute.
message AudienceOverlapItem {
  // The attribute and its metadata, including potential YouTube reach.
  google.ads.googleads.v21.common.AudienceInsightsAttributeMetadata
      attribute_metadata = 3;

  // The estimated size of the intersection of this audience attribute with the
  // primary attribute, that is, the number of reachable YouTube users who match
  // BOTH the primary attribute and this one.
  int64 potential_youtube_reach_intersection = 2;
}

// Request message for
// [AudienceInsightsService.GenerateTargetingSuggestionMetrics][google.ads.googleads.v21.services.AudienceInsightsService.GenerateTargetingSuggestionMetrics].
message GenerateTargetingSuggestionMetricsRequest {
  // Required. The ID of the customer.
  string customer_id = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. Audiences to request metrics for.
  repeated InsightsAudience audiences = 5
      [(google.api.field_behavior) = REQUIRED];

  // Optional. The name of the customer being planned for.  This is a
  // user-defined value.
  string customer_insights_group = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Additional information on the application issuing the request.
  google.ads.googleads.v21.common.AdditionalApplicationInfo
      insights_application_info = 4 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for
// [AudienceInsightsService.GenerateTargetingSuggestionMetrics][google.ads.googleads.v21.services.AudienceInsightsService.GenerateTargetingSuggestionMetrics].
message GenerateTargetingSuggestionMetricsResponse {
  // Suggested targetable audiences. There will be one suggestion for each
  // [GenerateTargetingSuggestionMetricsRequest.audiences][google.ads.googleads.v21.services.GenerateTargetingSuggestionMetricsRequest.audiences]
  // requested, matching the order requested.
  repeated TargetingSuggestionMetrics suggestions = 1;
}

// A description of an audience used for requesting insights.
message BasicInsightsAudience {
  // Required. The countries for this audience.
  repeated google.ads.googleads.v21.common.LocationInfo country_location = 1
      [(google.api.field_behavior) = REQUIRED];

  // Sub-country geographic location attributes.  If present, each of these
  // must be contained in one of the countries in this audience.
  repeated google.ads.googleads.v21.common.LocationInfo sub_country_locations =
      2;

  // Gender for the audience.  If absent, the audience does not restrict by
  // gender.
  google.ads.googleads.v21.common.GenderInfo gender = 3;

  // Age ranges for the audience.  If absent, the audience represents all people
  // over 18 that match the other attributes.
  repeated google.ads.googleads.v21.common.AgeRangeInfo age_ranges = 4;

  // User interests defining this audience.  Affinity and In-Market audiences
  // are supported.
  repeated google.ads.googleads.v21.common.UserInterestInfo user_interests = 5;

  // Topics, represented by Knowledge Graph entities and/or Product & Service
  // categories, that this audience is interested in.
  repeated google.ads.googleads.v21.common.AudienceInsightsTopic topics = 7;
}

// A structured definition of the audience of interest for which insights are
// being requested in AudienceInsightsService.
message InsightsAudienceDefinition {
  // Required. The audience of interest for which insights are being requested.
  InsightsAudience audience = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. The baseline audience. The default, if unspecified, is all people
  // in the same country as the audience of interest.
  InsightsAudience baseline_audience = 2
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. The one-month range of historical data to use for insights, in
  // the format "yyyy-mm". If unset, insights will be returned for the last
  // thirty days of data.
  string data_month = 3 [(google.api.field_behavior) = OPTIONAL];
}

// A text description of the audience of interest for which insights are being
// requested in AudienceInsightsService.
message InsightsAudienceDescription {
  // Required. The countries for the audience.
  repeated google.ads.googleads.v21.common.LocationInfo country_locations = 1
      [(google.api.field_behavior) = REQUIRED];

  // Required. An English language text description of an audience to get
  // suggestions for. Maximum length is 2000 characters. For example, "Women in
  // their 30s who love to travel".
  string audience_description = 2 [(google.api.field_behavior) = REQUIRED];

  // Optional. An optional marketing objective which will influence the type of
  // suggestions produced. AWARENESS will provide affinity audience segments,
  // while CONSIDERATION will provide in-market audience segments. Leaving it
  // unset will provide both.
  google.ads.googleads.v21.enums.AudienceInsightsMarketingObjectiveEnum
      .AudienceInsightsMarketingObjective marketing_objective = 3
      [(google.api.field_behavior) = OPTIONAL];
}

// A set of users, defined by various characteristics, for which insights can
// be requested in AudienceInsightsService.
message InsightsAudience {
  // Required. The countries for the audience.
  repeated google.ads.googleads.v21.common.LocationInfo country_locations = 1
      [(google.api.field_behavior) = REQUIRED];

  // Sub-country geographic location attributes.  If present, each of these
  // must be contained in one of the countries in this audience.  If absent, the
  // audience is geographically to the country_locations and no further.
  repeated google.ads.googleads.v21.common.LocationInfo sub_country_locations =
      2;

  // Gender for the audience.  If absent, the audience does not restrict by
  // gender.
  google.ads.googleads.v21.common.GenderInfo gender = 3;

  // Age ranges for the audience.  If absent, the audience represents all people
  // over 18 that match the other attributes.
  repeated google.ads.googleads.v21.common.AgeRangeInfo age_ranges = 4;

  // Parental status for the audience.  If absent, the audience does not
  // restrict by parental status.
  google.ads.googleads.v21.common.ParentalStatusInfo parental_status = 5;

  // Household income percentile ranges for the audience.  If absent, the
  // audience does not restrict by household income range.
  repeated google.ads.googleads.v21.common.IncomeRangeInfo income_ranges = 6;

  // Lineups representing the YouTube content viewed by the audience.
  repeated google.ads.googleads.v21.common.AudienceInsightsLineup lineups = 10;

  // User list to be targeted by the audience.
  google.ads.googleads.v21.common.UserListInfo user_list = 11;

  // A combination of entity, category and user interest attributes defining the
  // audience. The combination has a logical AND-of-ORs structure: Attributes
  // within each InsightsAudienceAttributeGroup are combined with OR, and
  // the combinations themselves are combined together with AND.  For example,
  // the expression (Entity OR Affinity) AND (In-Market OR Category) can be
  // formed using two InsightsAudienceAttributeGroups with two Attributes
  // each.
  repeated InsightsAudienceAttributeGroup topic_audience_combinations = 8;
}

// A list of AudienceInsightsAttributes.
message InsightsAudienceAttributeGroup {
  // Required. A collection of audience attributes to be combined with logical
  // OR. Attributes need not all be the same dimension.  Only Knowledge Graph
  // entities, Product & Service Categories, and Affinity and In-Market
  // audiences are supported in this context.
  repeated google.ads.googleads.v21.common.AudienceInsightsAttribute
      attributes = 2 [(google.api.field_behavior) = REQUIRED];
}

// A collection of related attributes of the same type in an audience
// composition insights report.
message AudienceCompositionSection {
  // The type of the attributes in this section.
  google.ads.googleads.v21.enums.AudienceInsightsDimensionEnum
      .AudienceInsightsDimension dimension = 1;

  // The most relevant segments for this audience.  If dimension is GENDER,
  // AGE_RANGE or PARENTAL_STATUS, then this list of attributes is exhaustive.
  repeated AudienceCompositionAttribute top_attributes = 3;

  // Additional attributes for this audience, grouped into clusters.  Only
  // populated if dimension is YOUTUBE_CHANNEL.
  repeated AudienceCompositionAttributeCluster clustered_attributes = 4;
}

// A collection of related attributes, with metadata and metrics, in an audience
// composition insights report.
message AudienceCompositionAttributeCluster {
  // The name of this cluster of attributes
  string cluster_display_name = 1;

  // If the dimension associated with this cluster is YOUTUBE_CHANNEL, then
  // cluster_metrics are metrics associated with the cluster as a whole.
  // For other dimensions, this field is unset.
  AudienceCompositionMetrics cluster_metrics = 3;

  // The individual attributes that make up this cluster, with metadata and
  // metrics.
  repeated AudienceCompositionAttribute attributes = 4;
}

// The share and index metrics associated with an attribute in an audience
// composition insights report.
message AudienceCompositionMetrics {
  // The fraction (from 0 to 1 inclusive) of the baseline audience that match
  // the attribute.
  double baseline_audience_share = 1;

  // The fraction (from 0 to 1 inclusive) of the specific audience that match
  // the attribute.
  double audience_share = 2;

  // The ratio of audience_share to baseline_audience_share, or zero if this
  // ratio is undefined or is not meaningful.
  double index = 3;

  // A relevance score from 0 to 1 inclusive.
  double score = 4;
}

// An audience attribute with metadata and metrics.
message AudienceCompositionAttribute {
  // The attribute with its metadata.
  google.ads.googleads.v21.common.AudienceInsightsAttributeMetadata
      attribute_metadata = 3;

  // Share and index metrics for the attribute.
  AudienceCompositionMetrics metrics = 2;
}