--- v17/services/audience_insights_service.proto 2024-08-06 12:42:08.000000000 +0000 +++ v17-1/services/audience_insights_service.proto 2024-08-06 12:42:18.000000000 +0000 @@ -147,6 +147,30 @@ }; option (google.api.method_signature) = "customer_id,audience"; } + + // 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: "/v17/customers/{customer_id=*}:generateAudienceOverlapInsights" + body: "*" + }; + option (google.api.method_signature) = + "customer_id,country_location,primary_attribute,dimensions"; + } } // Request message for @@ -332,6 +363,69 @@ google.ads.googleads.v17.common.DateRange last_thirty_days = 2; } +// Request message for +// [AudienceInsightsService.GenerateAudienceOverlapInsights][google.ads.googleads.v17.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.v17.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. + AudienceInsightsAttribute primary_attribute = 3 + [(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.v17.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; +} + +// Response message for +// [AudienceInsightsService.GenerateAudienceOverlapInsights][google.ads.googleads.v17.services.AudienceInsightsService.GenerateAudienceOverlapInsights]. +message GenerateAudienceOverlapInsightsResponse { + // Metadata for the primary attribute, including potential YouTube reach. + AudienceInsightsAttributeMetadata primary_attribute_metadata = 1; + + // 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.v17.services.GenerateAudienceOverlapInsightsResponse]. +message DimensionOverlapResult { + // The dimension of all the attributes in this section. + google.ads.googleads.v17.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. + AudienceInsightsAttributeMetadata attribute_metadata = 1; + + // 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; +} + // An audience attribute that can be used to request insights about the // audience. message AudienceInsightsAttribute { @@ -451,6 +545,14 @@ // "/Apparel/Clothing/Outerwear". string display_info = 5; + // An estimate of the number of reachable YouTube users matching this + // attribute in the requested location, or zero if that information is not + // available for this attribute. Only populated in + // GenerateAudienceOverlapInsightsResponses and in + // ListAudienceInsightsAttributesResponses when youtube_reach_location is + // present in the request. + int64 potential_youtube_reach = 9; + // Metadata specific to the dimension of this attribute. oneof dimension_metadata { // Special metadata for a YouTube channel.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2024-08-06 UTC.
[{
"type": "thumb-down",
"id": "missingTheInformationINeed",
"label":"Missing the information I need"
},{
"type": "thumb-down",
"id": "tooComplicatedTooManySteps",
"label":"Too complicated / too many steps"
},{
"type": "thumb-down",
"id": "outOfDate",
"label":"Out of date"
},{
"type": "thumb-down",
"id": "samplesCodeIssue",
"label":"Samples / code issue"
},{
"type": "thumb-down",
"id": "otherDown",
"label":"Other"
}]
[{
"type": "thumb-up",
"id": "easyToUnderstand",
"label":"Easy to understand"
},{
"type": "thumb-up",
"id": "solvedMyProblem",
"label":"Solved my problem"
},{
"type": "thumb-up",
"id": "otherUp",
"label":"Other"
}]
{
"lastModified": "Last updated 2024-08-06 UTC.",
"confidential": False
}