--- title: "POST /v23/customers/{customersId}:generateAudienceDefinition" method: POST path: "/v23/customers/{customersId}:generateAudienceDefinition" tags: ["customers"] --- # POST /v23/customers/{customersId}:generateAudienceDefinition `POST /v23/customers/{customersId}:generateAudienceDefinition` ## Request - Base URL: `https://searchads360.googleapis.com` - URL: `https://searchads360.googleapis.com/v23/customers/{customersId}:generateAudienceDefinition` - Auth: OAuth 2 and OAuth 2 - Implicit: `https://accounts.google.com/o/oauth2/auth` - Scopes: `https://www.googleapis.com/auth/doubleclicksearch` - Authorization code: `https://accounts.google.com/o/oauth2/auth` - Token URL: `https://accounts.google.com/o/oauth2/token` scopes: `https://www.googleapis.com/auth/doubleclicksearch` - TypeScript: (a function with typed inputs; its response is checked against the schema) Returns a collection of audience attributes using generative AI based on the provided audience description. List of thrown errors: [AudienceInsightsError]() [AuthenticationError]() [AuthorizationError]() [FieldError]() [HeaderError]() [InternalError]() [QuotaError]() [RequestError]() ## Path parameters - `customersId` string, required ## Request body - GoogleAdsSearchads360V23ServicesGenerateAudienceDefinitionRequest: Request message for AudienceInsightsService.GenerateAudienceDefinition. - `audienceDescription` GoogleAdsSearchads360V23ServicesInsightsAudienceDescription: A text description of the audience of interest for which insights are being requested in AudienceInsightsService. - `audienceDescription` string: 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". - `audienceDimensions` GoogleAdsSearchads360V23ServicesAudienceInsightsDimensions: A collection of dimensions to be used for generating insights. - `dimensions` string[]: Required. A list of dimensions. - `countryLocations` GoogleAdsSearchads360V23CommonLocationInfo[]: Required. The countries for the audience. - `geoTargetConstant` string: The geo target constant resource name. - `marketingObjective` 'UNSPECIFIED' | 'UNKNOWN' | 'AWARENESS' | 'CONSIDERATION' | 'RESEARCH': Optional. An optional marketing objective which will influence the type of suggestions produced. - `customerInsightsGroup` string: Optional. The name of the customer being planned for. This is a user-defined value. - `insightsApplicationInfo` GoogleAdsSearchads360V23CommonAdditionalApplicationInfo: Additional information about the application/tool issuing the request. This field is only used by ContentCreatorInsightsService, AudienceInsightsService, and ReachPlanService APIs. - `applicationId` string: The unique identifier of the agency proprietary application. This identifier is generated by Google. Reach out to your Google representative to request an application_id for each new application being integrated. - `applicationInstance` 'UNSPECIFIED' | 'UNKNOWN' | 'DEVELOPMENT_AND_TESTING' | 'PRODUCTION': The instance type of the application sending the request. ## Response `200` Successful response - GoogleAdsSearchads360V23ServicesGenerateAudienceDefinitionResponse: Response message for AudienceInsightsService.GenerateAudienceDefinition. - `highRelevanceAttributes` GoogleAdsSearchads360V23CommonAudienceInsightsAttributeMetadata[]: The attributes that make up the audience definition. - `attribute` GoogleAdsSearchads360V23CommonAudienceInsightsAttribute: An audience attribute that can be used to request insights about the audience. - `ageRange` GoogleAdsSearchads360V23CommonAgeRangeInfo: An age range criterion. - `type` 'UNSPECIFIED' | 'UNKNOWN' | 'AGE_RANGE_18_24' | 'AGE_RANGE_25_34' | 'AGE_RANGE_35_44' | 'AGE_RANGE_45_54' | 'AGE_RANGE_55_64' | 'AGE_RANGE_65_UP' | 'AGE_RANGE_UNDETERMINED': Type of the age range. - `category` GoogleAdsSearchads360V23CommonAudienceInsightsCategory: A Product and Service category. - `categoryId` string: Required. The criterion ID of the category. - `device` GoogleAdsSearchads360V23CommonDeviceInfo: A device criterion. - `type` 'UNSPECIFIED' | 'UNKNOWN' | 'MOBILE' | 'TABLET' | 'DESKTOP' | 'CONNECTED_TV' | 'OTHER': Type of the device. - `entity` GoogleAdsSearchads360V23CommonAudienceInsightsEntity: A Knowledge Graph entity, represented by its machine id. - `knowledgeGraphMachineId` string: Required. The machine ID (mid) of the Knowledge Graph entity. - `gender` GoogleAdsSearchads360V23CommonGenderInfo: A gender criterion. - `type` 'UNSPECIFIED' | 'UNKNOWN' | 'MALE' | 'FEMALE' | 'UNDETERMINED': Type of the gender. - `incomeRange` GoogleAdsSearchads360V23CommonIncomeRangeInfo: An income range criterion. - `type` 'UNSPECIFIED' | 'UNKNOWN' | 'INCOME_RANGE_0_50' | 'INCOME_RANGE_50_60' | 'INCOME_RANGE_60_70' | 'INCOME_RANGE_70_80' | 'INCOME_RANGE_80_90' | 'INCOME_RANGE_90_UP' | 'INCOME_RANGE_UNDETERMINED': Type of the income range. - `lineup` GoogleAdsSearchads360V23CommonAudienceInsightsLineup: A YouTube Lineup. - `lineupId` string: Required. The numeric ID of the lineup. - `location` GoogleAdsSearchads360V23CommonLocationInfo: A location criterion. - `geoTargetConstant` string: The geo target constant resource name. - `parentalStatus` GoogleAdsSearchads360V23CommonParentalStatusInfo: A parental status criterion. - `type` 'UNSPECIFIED' | 'UNKNOWN' | 'PARENT' | 'NOT_A_PARENT' | 'UNDETERMINED': Type of the parental status. - `userInterest` GoogleAdsSearchads360V23CommonUserInterestInfo: Represents a particular interest-based topic to be targeted. - `userInterestCategory` string: The UserInterest resource name. - `userList` GoogleAdsSearchads360V23CommonUserListInfo: A User List criterion. Represents a user list that is defined by the advertiser to be targeted. - `userList` string: The User List resource name. - `youtubeChannel` GoogleAdsSearchads360V23CommonYouTubeChannelInfo: A YouTube Channel criterion. - `channelId` string: The YouTube uploader channel id or the channel code of a YouTube channel. - `youtubeVideo` GoogleAdsSearchads360V23CommonYouTubeVideoInfo: A YouTube Video criterion. - `videoId` string: YouTube video id as it appears on the YouTube watch page. - `dimension` 'UNSPECIFIED' | 'UNKNOWN' | 'CATEGORY' | 'KNOWLEDGE_GRAPH' | 'GEO_TARGET_COUNTRY' | 'SUB_COUNTRY_LOCATION' | 'YOUTUBE_CHANNEL' | 'AFFINITY_USER_INTEREST' | 'IN_MARKET_USER_INTEREST' | 'PARENTAL_STATUS' | 'INCOME_RANGE' | 'AGE_RANGE' | 'GENDER' | 'YOUTUBE_VIDEO' | 'DEVICE' | 'YOUTUBE_LINEUP' | 'USER_LIST' | 'LIFE_EVENT_USER_INTEREST': The type of the attribute. - `displayInfo` string: A string that supplements the display_name to identify the attribute. If the dimension is TOPIC, this is a brief description of the Knowledge Graph entity, such as "American singer-songwriter". If the dimension is CATEGORY, this is the complete path to the category in The Product & Service taxonomy, for example "/Apparel/Clothing/Outerwear". - `displayName` string: The human-readable name of the attribute. - `knowledgeGraphAttributeMetadata` GoogleAdsSearchads360V23CommonKnowledgeGraphAttributeMetadata: Metadata associated with a Knowledge Graph Entity attribute. - `entityCapabilities` string[]: The capabilities of the entity used in ContentCreatorInsightsService. - `relatedCategories` GoogleAdsSearchads360V23CommonAudienceInsightsAttributeMetadata[]: A list of CATEGORY attributes related to this entity. - `lineupAttributeMetadata` GoogleAdsSearchads360V23CommonLineupAttributeMetadata: Metadata associated with a Lineup attribute. - `channelCountLowerBound` string, int64: The lower end of a range containing the number of channels in the lineup. - `channelCountUpperBound` string, int64: The upper end of a range containing the number of channels in the lineup. - `inventoryCountry` GoogleAdsSearchads360V23CommonLocationInfo: A location criterion. - `geoTargetConstant` string: The geo target constant resource name. - `medianMonthlyInventory` string, int64: The median number of impressions per month on this lineup. - `sampleChannels` GoogleAdsSearchads360V23CommonLineupAttributeMetadataSampleChannel[]: Examples of channels that are included in the lineup. - `displayName` string: The name of the sample channel. - `youtubeChannel` GoogleAdsSearchads360V23CommonYouTubeChannelInfo: A YouTube Channel criterion. - `channelId` string: The YouTube uploader channel id or the channel code of a YouTube channel. - `youtubeChannelMetadata` GoogleAdsSearchads360V23CommonYouTubeChannelAttributeMetadata: Metadata associated with a YouTube channel attribute. - `subscriberCount` string, int64: The approximate number of subscribers to the YouTube channel. - `locationAttributeMetadata` GoogleAdsSearchads360V23CommonLocationAttributeMetadata: Metadata associated with a Location attribute. - `countryLocation` GoogleAdsSearchads360V23CommonLocationInfo: A location criterion. - `geoTargetConstant` string: The geo target constant resource name. - `potentialYoutubeReach` string, int64: 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. This field is not populated in every response. - `subscriberShare` number, double: The share of subscribers within this attribute, between and including 0 and 1. This field is not populated in every response. - `userInterestAttributeMetadata` GoogleAdsSearchads360V23CommonUserInterestAttributeMetadata: Metadata associated with a User Interest attribute. - `userInterestDescription` string: English language text description of the user interest category (200 characters max). - `userListAttributeMetadata` GoogleAdsSearchads360V23CommonUserListAttributeMetadata: Metadata associated with a User List attribute. - `userListType` 'UNSPECIFIED' | 'UNKNOWN' | 'REMARKETING' | 'LOGICAL' | 'EXTERNAL_REMARKETING' | 'RULE_BASED' | 'SIMILAR' | 'CRM_BASED' | 'LOOKALIKE': The user list type. - `viewerShare` number, double: The share of viewers within this attribute, between and including 0 and 1. This field is not populated in every response. - `youtubeChannelMetadata` GoogleAdsSearchads360V23CommonYouTubeChannelAttributeMetadata: Metadata associated with a YouTube channel attribute. - `subscriberCount` string, int64: The approximate number of subscribers to the YouTube channel. - `youtubeVideoMetadata` GoogleAdsSearchads360V23CommonYouTubeVideoAttributeMetadata: Metadata for a YouTube video attribute. - `commentsCount` string, int64: The total number of comments. - `likesCount` string, int64: The total number of likes. - `publishDate` string: The date that the video was created. Formatted as "yyyy-mm-dd". - `thumbnailUrl` string: The URL of the video thumbnail, prefixed by "https://img.youtube.com/". - `videoProperties` string[]: The properties of this video (such as shorts, live stream). - `videoUrl` string: The URL of the video, prefixed by "https://www.youtube.com/". - `viewsCount` string, int64: The total number of views. - `mediumRelevanceAttributes` GoogleAdsSearchads360V23CommonAudienceInsightsAttributeMetadata[]: Additional attributes that are less relevant but still related to the audience description. Use these attributes to broaden the audience definition to reach more users. - `attribute` GoogleAdsSearchads360V23CommonAudienceInsightsAttribute: An audience attribute that can be used to request insights about the audience. - `ageRange` GoogleAdsSearchads360V23CommonAgeRangeInfo: An age range criterion. - `type` 'UNSPECIFIED' | 'UNKNOWN' | 'AGE_RANGE_18_24' | 'AGE_RANGE_25_34' | 'AGE_RANGE_35_44' | 'AGE_RANGE_45_54' | 'AGE_RANGE_55_64' | 'AGE_RANGE_65_UP' | 'AGE_RANGE_UNDETERMINED': Type of the age range. - `category` GoogleAdsSearchads360V23CommonAudienceInsightsCategory: A Product and Service category. - `categoryId` string: Required. The criterion ID of the category. - `device` GoogleAdsSearchads360V23CommonDeviceInfo: A device criterion. - `type` 'UNSPECIFIED' | 'UNKNOWN' | 'MOBILE' | 'TABLET' | 'DESKTOP' | 'CONNECTED_TV' | 'OTHER': Type of the device. - `entity` GoogleAdsSearchads360V23CommonAudienceInsightsEntity: A Knowledge Graph entity, represented by its machine id. - `knowledgeGraphMachineId` string: Required. The machine ID (mid) of the Knowledge Graph entity. - `gender` GoogleAdsSearchads360V23CommonGenderInfo: A gender criterion. - `type` 'UNSPECIFIED' | 'UNKNOWN' | 'MALE' | 'FEMALE' | 'UNDETERMINED': Type of the gender. - `incomeRange` GoogleAdsSearchads360V23CommonIncomeRangeInfo: An income range criterion. - `type` 'UNSPECIFIED' | 'UNKNOWN' | 'INCOME_RANGE_0_50' | 'INCOME_RANGE_50_60' | 'INCOME_RANGE_60_70' | 'INCOME_RANGE_70_80' | 'INCOME_RANGE_80_90' | 'INCOME_RANGE_90_UP' | 'INCOME_RANGE_UNDETERMINED': Type of the income range. - `lineup` GoogleAdsSearchads360V23CommonAudienceInsightsLineup: A YouTube Lineup. - `lineupId` string: Required. The numeric ID of the lineup. - `location` GoogleAdsSearchads360V23CommonLocationInfo: A location criterion. - `geoTargetConstant` string: The geo target constant resource name. - `parentalStatus` GoogleAdsSearchads360V23CommonParentalStatusInfo: A parental status criterion. - `type` 'UNSPECIFIED' | 'UNKNOWN' | 'PARENT' | 'NOT_A_PARENT' | 'UNDETERMINED': Type of the parental status. - `userInterest` GoogleAdsSearchads360V23CommonUserInterestInfo: Represents a particular interest-based topic to be targeted. - `userInterestCategory` string: The UserInterest resource name. - `userList` GoogleAdsSearchads360V23CommonUserListInfo: A User List criterion. Represents a user list that is defined by the advertiser to be targeted. - `userList` string: The User List resource name. - `youtubeChannel` GoogleAdsSearchads360V23CommonYouTubeChannelInfo: A YouTube Channel criterion. - `channelId` string: The YouTube uploader channel id or the channel code of a YouTube channel. - `youtubeVideo` GoogleAdsSearchads360V23CommonYouTubeVideoInfo: A YouTube Video criterion. - `videoId` string: YouTube video id as it appears on the YouTube watch page. - `dimension` 'UNSPECIFIED' | 'UNKNOWN' | 'CATEGORY' | 'KNOWLEDGE_GRAPH' | 'GEO_TARGET_COUNTRY' | 'SUB_COUNTRY_LOCATION' | 'YOUTUBE_CHANNEL' | 'AFFINITY_USER_INTEREST' | 'IN_MARKET_USER_INTEREST' | 'PARENTAL_STATUS' | 'INCOME_RANGE' | 'AGE_RANGE' | 'GENDER' | 'YOUTUBE_VIDEO' | 'DEVICE' | 'YOUTUBE_LINEUP' | 'USER_LIST' | 'LIFE_EVENT_USER_INTEREST': The type of the attribute. - `displayInfo` string: A string that supplements the display_name to identify the attribute. If the dimension is TOPIC, this is a brief description of the Knowledge Graph entity, such as "American singer-songwriter". If the dimension is CATEGORY, this is the complete path to the category in The Product & Service taxonomy, for example "/Apparel/Clothing/Outerwear". - `displayName` string: The human-readable name of the attribute. - `knowledgeGraphAttributeMetadata` GoogleAdsSearchads360V23CommonKnowledgeGraphAttributeMetadata: Metadata associated with a Knowledge Graph Entity attribute. - `entityCapabilities` string[]: The capabilities of the entity used in ContentCreatorInsightsService. - `relatedCategories` GoogleAdsSearchads360V23CommonAudienceInsightsAttributeMetadata[]: A list of CATEGORY attributes related to this entity. - `lineupAttributeMetadata` GoogleAdsSearchads360V23CommonLineupAttributeMetadata: Metadata associated with a Lineup attribute. - `channelCountLowerBound` string, int64: The lower end of a range containing the number of channels in the lineup. - `channelCountUpperBound` string, int64: The upper end of a range containing the number of channels in the lineup. - `inventoryCountry` GoogleAdsSearchads360V23CommonLocationInfo: A location criterion. - `geoTargetConstant` string: The geo target constant resource name. - `medianMonthlyInventory` string, int64: The median number of impressions per month on this lineup. - `sampleChannels` GoogleAdsSearchads360V23CommonLineupAttributeMetadataSampleChannel[]: Examples of channels that are included in the lineup. - `displayName` string: The name of the sample channel. - `youtubeChannel` GoogleAdsSearchads360V23CommonYouTubeChannelInfo: A YouTube Channel criterion. - `channelId` string: The YouTube uploader channel id or the channel code of a YouTube channel. - `youtubeChannelMetadata` GoogleAdsSearchads360V23CommonYouTubeChannelAttributeMetadata: Metadata associated with a YouTube channel attribute. - `subscriberCount` string, int64: The approximate number of subscribers to the YouTube channel. - `locationAttributeMetadata` GoogleAdsSearchads360V23CommonLocationAttributeMetadata: Metadata associated with a Location attribute. - `countryLocation` GoogleAdsSearchads360V23CommonLocationInfo: A location criterion. - `geoTargetConstant` string: The geo target constant resource name. - `potentialYoutubeReach` string, int64: 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. This field is not populated in every response. - `subscriberShare` number, double: The share of subscribers within this attribute, between and including 0 and 1. This field is not populated in every response. - `userInterestAttributeMetadata` GoogleAdsSearchads360V23CommonUserInterestAttributeMetadata: Metadata associated with a User Interest attribute. - `userInterestDescription` string: English language text description of the user interest category (200 characters max). - `userListAttributeMetadata` GoogleAdsSearchads360V23CommonUserListAttributeMetadata: Metadata associated with a User List attribute. - `userListType` 'UNSPECIFIED' | 'UNKNOWN' | 'REMARKETING' | 'LOGICAL' | 'EXTERNAL_REMARKETING' | 'RULE_BASED' | 'SIMILAR' | 'CRM_BASED' | 'LOOKALIKE': The user list type. - `viewerShare` number, double: The share of viewers within this attribute, between and including 0 and 1. This field is not populated in every response. - `youtubeChannelMetadata` GoogleAdsSearchads360V23CommonYouTubeChannelAttributeMetadata: Metadata associated with a YouTube channel attribute. - `subscriberCount` string, int64: The approximate number of subscribers to the YouTube channel. - `youtubeVideoMetadata` GoogleAdsSearchads360V23CommonYouTubeVideoAttributeMetadata: Metadata for a YouTube video attribute. - `commentsCount` string, int64: The total number of comments. - `likesCount` string, int64: The total number of likes. - `publishDate` string: The date that the video was created. Formatted as "yyyy-mm-dd". - `thumbnailUrl` string: The URL of the video thumbnail, prefixed by "https://img.youtube.com/". - `videoProperties` string[]: The properties of this video (such as shorts, live stream). - `videoUrl` string: The URL of the video, prefixed by "https://www.youtube.com/". - `viewsCount` string, int64: The total number of views. --- [API](https://skmtc.dev/google/apis/searchads360.md) - [All operations](https://skmtc.dev/google/apis/searchads360/llms.txt) - [OpenAPI document](https://skmtc.dev/google/apis/searchads360/revisions/4a4511f84b18?raw)