--- v19/services/audience_insights_service.proto 2025-04-16 17:10:13.000000000 +0000 +++ v20/services/audience_insights_service.proto 2025-05-30 15:34:58.000000000 +0000 @@ -1,669 +1,697 @@ // Copyright 2025 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.v19.services; +package google.ads.googleads.v20.services; -import "google/ads/googleads/v19/common/audience_insights_attribute.proto"; -import "google/ads/googleads/v19/common/criteria.proto"; -import "google/ads/googleads/v19/common/dates.proto"; -import "google/ads/googleads/v19/enums/audience_insights_dimension.proto"; -import "google/ads/googleads/v19/enums/audience_insights_marketing_objective.proto"; +import "google/ads/googleads/v20/common/additional_application_info.proto"; +import "google/ads/googleads/v20/common/audience_insights_attribute.proto"; +import "google/ads/googleads/v20/common/criteria.proto"; +import "google/ads/googleads/v20/common/dates.proto"; +import "google/ads/googleads/v20/enums/audience_insights_dimension.proto"; +import "google/ads/googleads/v20/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.V19.Services"; -option go_package = "google.golang.org/genproto/googleapis/ads/googleads/v19/services;services"; +option csharp_namespace = "Google.Ads.GoogleAds.V20.Services"; +option go_package = "google.golang.org/genproto/googleapis/ads/googleads/v20/services;services"; option java_multiple_files = true; option java_outer_classname = "AudienceInsightsServiceProto"; -option java_package = "com.google.ads.googleads.v19.services"; +option java_package = "com.google.ads.googleads.v20.services"; option objc_class_prefix = "GAA"; -option php_namespace = "Google\\Ads\\GoogleAds\\V19\\Services"; -option ruby_package = "Google::Ads::GoogleAds::V19::Services"; +option php_namespace = "Google\\Ads\\GoogleAds\\V20\\Services"; +option ruby_package = "Google::Ads::GoogleAds::V20::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: "/v19/customers/{customer_id=*}:generateInsightsFinderReport" + post: "/v20/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: "/v19/customers/{customer_id=*}:searchAudienceInsightsAttributes" + post: "/v20/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: "/v19/audienceInsights:listInsightsEligibleDates" + post: "/v20/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: "/v19/customers/{customer_id=*}:generateAudienceCompositionInsights" + post: "/v20/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: "/v19/customers/{customer_id=*}:generateSuggestedTargetingInsights" + post: "/v20/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: "/v19/customers/{customer_id=*}:generateAudienceOverlapInsights" + post: "/v20/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: "/v19/customers/{customer_id=*}:generateTargetingSuggestionMetrics" + post: "/v20/customers/{customer_id=*}:generateTargetingSuggestionMetrics" body: "*" }; option (google.api.method_signature) = "customer_id,audiences"; } } // Request message for -// [AudienceInsightsService.GenerateInsightsFinderReport][google.ads.googleads.v19.services.AudienceInsightsService.GenerateInsightsFinderReport]. +// [AudienceInsightsService.GenerateInsightsFinderReport][google.ads.googleads.v20.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.v20.common.AdditionalApplicationInfo + insights_application_info = 5 [(google.api.field_behavior) = OPTIONAL]; } // The response message for -// [AudienceInsightsService.GenerateInsightsFinderReport][google.ads.googleads.v19.services.AudienceInsightsService.GenerateInsightsFinderReport], +// [AudienceInsightsService.GenerateInsightsFinderReport][google.ads.googleads.v20.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.v19.services.AudienceInsightsService.GenerateAudienceCompositionInsights]. +// [AudienceInsightsService.GenerateAudienceCompositionInsights][google.ads.googleads.v20.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_DYNAMIC_LINEUP, + // 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.v19.enums.AudienceInsightsDimensionEnum + repeated google.ads.googleads.v20.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.v20.common.AdditionalApplicationInfo + insights_application_info = 7 [(google.api.field_behavior) = OPTIONAL]; } // Response message for -// [AudienceInsightsService.GenerateAudienceCompositionInsights][google.ads.googleads.v19.services.AudienceInsightsService.GenerateAudienceCompositionInsights]. +// [AudienceInsightsService.GenerateAudienceCompositionInsights][google.ads.googleads.v20.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.v19.services.AudienceInsightsService.GenerateSuggestedTargetingInsights]. +// [AudienceInsightsService.GenerateSuggestedTargetingInsights][google.ads.googleads.v20.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.v20.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.v19.services.AudienceInsightsService.GenerateSuggestedTargetingInsights]. +// [AudienceInsightsService.GenerateSuggestedTargetingInsights][google.ads.googleads.v20.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.v19.common.AudienceInsightsAttributeMetadata + repeated google.ads.googleads.v20.common.AudienceInsightsAttributeMetadata locations = 9; // Suggested age targeting; may be empty indicating no age targeting. - repeated google.ads.googleads.v19.common.AgeRangeInfo age_ranges = 2; + repeated google.ads.googleads.v20.common.AgeRangeInfo age_ranges = 2; // Suggested gender targeting. If present, this attribute has dimension // GENDER. - google.ads.googleads.v19.common.GenderInfo gender = 3; + google.ads.googleads.v20.common.GenderInfo gender = 3; // A Parental Status value (parent, or not a parent). - google.ads.googleads.v19.common.ParentalStatusInfo parental_status = 8; + google.ads.googleads.v20.common.ParentalStatusInfo parental_status = 8; // Suggested audience segments to target. These attributes all have dimension // AFFINITY_USER_INTEREST or IN_MARKET_USER_INTEREST - repeated google.ads.googleads.v19.common.AudienceInsightsAttributeMetadata + repeated google.ads.googleads.v20.common.AudienceInsightsAttributeMetadata user_interests = 10; // 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.v19.services.AudienceInsightsService.ListAudienceInsightsAttributes]. +// [AudienceInsightsService.ListAudienceInsightsAttributes][google.ads.googleads.v20.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, - // GEO_TARGET_COUNTRY, SUB_COUNTRY_LOCATION, YOUTUBE_DYNAMIC_LINEUP, + // 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.v19.enums.AudienceInsightsDimensionEnum + repeated google.ads.googleads.v20.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.v20.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.v19.common.LocationInfo + repeated google.ads.googleads.v20.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.v19.common.LocationInfo youtube_reach_location = 6; + google.ads.googleads.v20.common.LocationInfo youtube_reach_location = 6; } // Response message for -// [AudienceInsightsService.ListAudienceInsightsAttributes][google.ads.googleads.v19.services.AudienceInsightsService.ListAudienceInsightsAttributes]. +// [AudienceInsightsService.ListAudienceInsightsAttributes][google.ads.googleads.v20.services.AudienceInsightsService.ListAudienceInsightsAttributes]. message ListAudienceInsightsAttributesResponse { // The attributes matching the search query. - repeated google.ads.googleads.v19.common.AudienceInsightsAttributeMetadata + repeated google.ads.googleads.v20.common.AudienceInsightsAttributeMetadata attributes = 2; } // Request message for -// [AudienceInsightsService.ListInsightsEligibleDates][google.ads.googleads.v19.services.AudienceInsightsService.ListInsightsEligibleDates]. -message ListInsightsEligibleDatesRequest {} +// [AudienceInsightsService.ListInsightsEligibleDates][google.ads.googleads.v20.services.AudienceInsightsService.ListInsightsEligibleDates]. +message ListInsightsEligibleDatesRequest { + // Optional. Additional information on the application issuing the request. + google.ads.googleads.v20.common.AdditionalApplicationInfo + insights_application_info = 1 [(google.api.field_behavior) = OPTIONAL]; +} // Response message for -// [AudienceInsightsService.ListInsightsEligibleDates][google.ads.googleads.v19.services.AudienceInsightsService.ListInsightsEligibleDates]. +// [AudienceInsightsService.ListInsightsEligibleDates][google.ads.googleads.v20.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.v19.services.AudienceInsightsService.GenerateAudienceCompositionInsights] + // [AudienceInsightsService.GenerateAudienceCompositionInsights][google.ads.googleads.v20.services.AudienceInsightsService.GenerateAudienceCompositionInsights] // requests that have no data_month set. - google.ads.googleads.v19.common.DateRange last_thirty_days = 2; + google.ads.googleads.v20.common.DateRange last_thirty_days = 2; } // Request message for -// [AudienceInsightsService.GenerateAudienceOverlapInsights][google.ads.googleads.v19.services.AudienceInsightsService.GenerateAudienceOverlapInsights]. +// [AudienceInsightsService.GenerateAudienceOverlapInsights][google.ads.googleads.v20.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.v19.common.LocationInfo country_location = 2 + google.ads.googleads.v20.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.v19.common.AudienceInsightsAttribute primary_attribute = + google.ads.googleads.v20.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.v19.enums.AudienceInsightsDimensionEnum + repeated google.ads.googleads.v20.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.v20.common.AdditionalApplicationInfo + insights_application_info = 7 [(google.api.field_behavior) = OPTIONAL]; } // Response message for -// [AudienceInsightsService.GenerateAudienceOverlapInsights][google.ads.googleads.v19.services.AudienceInsightsService.GenerateAudienceOverlapInsights]. +// [AudienceInsightsService.GenerateAudienceOverlapInsights][google.ads.googleads.v20.services.AudienceInsightsService.GenerateAudienceOverlapInsights]. message GenerateAudienceOverlapInsightsResponse { // Metadata for the primary attribute, including potential YouTube reach. - google.ads.googleads.v19.common.AudienceInsightsAttributeMetadata + google.ads.googleads.v20.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.v19.services.GenerateAudienceOverlapInsightsResponse]. +// [GenerateAudienceOverlapInsightsResponse][google.ads.googleads.v20.services.GenerateAudienceOverlapInsightsResponse]. message DimensionOverlapResult { // The dimension of all the attributes in this section. - google.ads.googleads.v19.enums.AudienceInsightsDimensionEnum + google.ads.googleads.v20.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.v19.common.AudienceInsightsAttributeMetadata + google.ads.googleads.v20.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.v19.services.AudienceInsightsService.GenerateTargetingSuggestionMetrics]. +// [AudienceInsightsService.GenerateTargetingSuggestionMetrics][google.ads.googleads.v20.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 BasicInsightsAudience audiences = 2 [(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.v20.common.AdditionalApplicationInfo + insights_application_info = 4 [(google.api.field_behavior) = OPTIONAL]; } // Response message for -// [AudienceInsightsService.GenerateTargetingSuggestionMetrics][google.ads.googleads.v19.services.AudienceInsightsService.GenerateTargetingSuggestionMetrics]. +// [AudienceInsightsService.GenerateTargetingSuggestionMetrics][google.ads.googleads.v20.services.AudienceInsightsService.GenerateTargetingSuggestionMetrics]. message GenerateTargetingSuggestionMetricsResponse { // Suggested targetable audiences. There will be one suggestion for each // [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.v19.common.LocationInfo country_location = 1 + repeated google.ads.googleads.v20.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.v19.common.LocationInfo sub_country_locations = + repeated google.ads.googleads.v20.common.LocationInfo sub_country_locations = 2; // Gender for the audience. If absent, the audience does not restrict by // gender. - google.ads.googleads.v19.common.GenderInfo gender = 3; + google.ads.googleads.v20.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.v19.common.AgeRangeInfo age_ranges = 4; + repeated google.ads.googleads.v20.common.AgeRangeInfo age_ranges = 4; // User interests defining this audience. Affinity and In-Market audiences // are supported. - repeated google.ads.googleads.v19.common.UserInterestInfo user_interests = 5; + repeated google.ads.googleads.v20.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.v19.common.AudienceInsightsTopic topics = 7; + repeated google.ads.googleads.v20.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.v19.common.LocationInfo country_locations = 1 + repeated google.ads.googleads.v20.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.v19.enums.AudienceInsightsMarketingObjectiveEnum + google.ads.googleads.v20.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.v19.common.LocationInfo country_locations = 1 + repeated google.ads.googleads.v20.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.v19.common.LocationInfo sub_country_locations = + repeated google.ads.googleads.v20.common.LocationInfo sub_country_locations = 2; // Gender for the audience. If absent, the audience does not restrict by // gender. - google.ads.googleads.v19.common.GenderInfo gender = 3; + google.ads.googleads.v20.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.v19.common.AgeRangeInfo age_ranges = 4; + repeated google.ads.googleads.v20.common.AgeRangeInfo age_ranges = 4; // Parental status for the audience. If absent, the audience does not // restrict by parental status. - google.ads.googleads.v19.common.ParentalStatusInfo parental_status = 5; + google.ads.googleads.v20.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.v19.common.IncomeRangeInfo income_ranges = 6; + repeated google.ads.googleads.v20.common.IncomeRangeInfo income_ranges = 6; - // Dynamic lineups representing the YouTube content viewed by the audience. - repeated google.ads.googleads.v19.common.AudienceInsightsDynamicLineup - dynamic_lineups = 9; + // Lineups representing the YouTube content viewed by the audience. + repeated google.ads.googleads.v20.common.AudienceInsightsLineup lineups = 10; // 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.v19.common.AudienceInsightsAttribute + repeated google.ads.googleads.v20.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.v19.enums.AudienceInsightsDimensionEnum + google.ads.googleads.v20.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.v19.common.AudienceInsightsAttributeMetadata + google.ads.googleads.v20.common.AudienceInsightsAttributeMetadata attribute_metadata = 3; // Share and index metrics for the attribute. AudienceCompositionMetrics metrics = 2; }
