Method: customers.generateCreatorInsights

Returns insights for a collection of YouTube Creators and Channels.

List of thrown errors: AuthenticationError AuthorizationError FieldError HeaderError InternalError QuotaError RangeError RequestError

HTTP request

POST https://googleads.googleapis.com/v18/customers/{customerId}:generateCreatorInsights

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
customerId

string

Required. The ID of the customer.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "customerInsightsGroup": string,

  // Union field criteria can be only one of the following:
  "searchAttributes": {
    object (SearchAttributes)
  },
  "searchChannels": {
    object (YouTubeChannels)
  }
  // End of list of possible types for union field criteria.
}
Fields
customerInsightsGroup

string

Required. The name of the customer being planned for. This is a user-defined value.
Union field criteria. A criteria used to search for creators and creator insights. criteria can be only one of the following:
searchAttributes

object (SearchAttributes)

The list of attributes to search for top creators in.
searchChannels

object (YouTubeChannels)

The list of YouTube Channel IDs to fetch creator insights for.

Response body

Response message for ContentCreatorInsightsService.GenerateCreatorInsights.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "creatorInsights": [
    {
      object (YouTubeCreatorInsights)
    }
  ]
}
Fields
creatorInsights[]

object (YouTubeCreatorInsights)

A collection of YouTube Creators, each containing a collection of YouTube Channels maintained by the YouTube Creator.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/adwords

For more information, see the OAuth 2.0 Overview.

SearchAttributes

The audience attributes (such as Age, Gender, Affinity, and In-Market) and creator attributes (such as creator location and creator's content topics) used to search for top creators.

JSON representation 
{
  "audienceAttributes": [
    {
      object (AudienceInsightsAttribute)
    }
  ],
  "creatorAttributes": [
    {
      object (AudienceInsightsAttribute)
    }
  ]
}
Fields
audienceAttributes[]

object (AudienceInsightsAttribute)

Optional. Audience attributes that describe an audience of viewers. This is used to search for creators whose own viewers match the input audience.
creatorAttributes[]

object (AudienceInsightsAttribute)

Optional. Creator attributes that describe a collection of types of content. This is used to search for creators whose content matches the input creator attributes.

AudienceInsightsAttribute

An audience attribute that can be used to request insights about the audience.

JSON representation 
{

  // Union field attribute can be only one of the following:
  "ageRange": {
    object (AgeRangeInfo)
  },
  "gender": {
    object (GenderInfo)
  },
  "location": {
    object (LocationInfo)
  },
  "userInterest": {
    object (UserInterestInfo)
  },
  "entity": {
    object (AudienceInsightsEntity)
  },
  "category": {
    object (AudienceInsightsCategory)
  },
  "dynamicLineup": {
    object (AudienceInsightsDynamicLineup)
  },
  "parentalStatus": {
    object (ParentalStatusInfo)
  },
  "incomeRange": {
    object (IncomeRangeInfo)
  },
  "youtubeChannel": {
    object (YouTubeChannelInfo)
  }
  // End of list of possible types for union field attribute.
}
Fields
Union field attribute. An audience attribute. attribute can be only one of the following:
ageRange

object (AgeRangeInfo)

An audience attribute defined by an age range.
gender

object (GenderInfo)

An audience attribute defined by a gender.
location

object (LocationInfo)

An audience attribute defined by a geographic location.
userInterest

object (UserInterestInfo)

An Affinity or In-Market audience.
entity

object (AudienceInsightsEntity)

An audience attribute defined by interest in a topic represented by a Knowledge Graph entity.
category

object (AudienceInsightsCategory)

An audience attribute defined by interest in a Product & Service category.
dynamicLineup

object (AudienceInsightsDynamicLineup)

A YouTube Dynamic Lineup.
parentalStatus

object (ParentalStatusInfo)

A Parental Status value (parent, or not a parent).
incomeRange

object (IncomeRangeInfo)

A household income percentile range.
youtubeChannel

object (YouTubeChannelInfo)

A YouTube channel.

AudienceInsightsEntity

A Knowledge Graph entity, represented by its machine id.

JSON representation 
{
  "knowledgeGraphMachineId": string
}
Fields
knowledgeGraphMachineId

string

Required. The machine ID (mid) of the Knowledge Graph entity.

AudienceInsightsCategory

A Product and Service category.

JSON representation 
{
  "categoryId": string
}
Fields
categoryId

string

Required. The criterion ID of the category.

AudienceInsightsDynamicLineup

A YouTube Dynamic Lineup.

JSON representation 
{
  "dynamicLineupId": string
}
Fields
dynamicLineupId

string

Required. The numeric ID of the dynamic lineup.

YouTubeChannels

A collection of YouTube Channels.

JSON representation 
{
  "youtubeChannels": [
    {
      object (YouTubeChannelInfo)
    }
  ]
}
Fields
youtubeChannels[]

object (YouTubeChannelInfo)

Optional. The YouTube Channel IDs to fetch creator insights for.

YouTubeCreatorInsights

A YouTube creator and the insights for this creator.

JSON representation 
{
  "creatorName": string,
  "creatorChannels": [
    {
      object (YouTubeChannelInsights)
    }
  ]
}
Fields
creatorName

string

The name of the creator.
creatorChannels[]

object (YouTubeChannelInsights)

The list of YouTube Channels

YouTubeChannelInsights

YouTube Channel insights, and its metadata (such as channel name and channel ID), returned for a creator insights response.

JSON representation 
{
  "displayName": string,
  "youtubeChannel": {
    object (YouTubeChannelInfo)
  },
  "channelMetrics": {
    object (YouTubeMetrics)
  },
  "channelAudienceDemographics": [
    {
      object (AudienceInsightsAttributeMetadata)
    }
  ],
  "channelAttributes": [
    {
      object (AudienceInsightsAttributeMetadata)
    }
  ],
  "channelType": string
}
Fields
displayName

string

The name of the YouTube Channel.
youtubeChannel

object (YouTubeChannelInfo)

The YouTube Channel ID.
channelMetrics

object (YouTubeMetrics)

The metrics for a YouTube Channel.
channelAudienceDemographics[]

object (AudienceInsightsAttributeMetadata)

The types of audiences and demographics associated with a channel's main audience. Audiences and demographics will have a breakdown of subscriber share across dimensions of the same value.
channelAttributes[]

object (AudienceInsightsAttributeMetadata)

The attributes associated with the content made by a channel.
channelType

string

Metadata string associated with the type of channel.

YouTubeMetrics

YouTube Channel metrics.

JSON representation 
{
  "subscriberCount": string,
  "viewsCount": string
}
Fields
subscriberCount

string (int64 format)

The number of subscribers.
viewsCount

string (int64 format)

The total number of views.

AudienceInsightsAttributeMetadata

An audience attribute, with metadata about it, returned in response to a search.

JSON representation 
{
  "dimension": enum (AudienceInsightsDimension),
  "attribute": {
    object (AudienceInsightsAttribute)
  },
  "displayName": string,
  "displayInfo": string,
  "potentialYoutubeReach": string,
  "subscriberShare": number,

  // Union field dimension_metadata can be only one of the following:
  "youtubeChannelMetadata": {
    object (YouTubeChannelAttributeMetadata)
  },
  "dynamicAttributeMetadata": {
    object (DynamicLineupAttributeMetadata)
  },
  "locationAttributeMetadata": {
    object (LocationAttributeMetadata)
  }
  // End of list of possible types for union field dimension_metadata.
}
Fields
dimension

enum (AudienceInsightsDimension)

The type of the attribute.
attribute

object (AudienceInsightsAttribute)

The attribute itself.
displayName

string

The human-readable name of the attribute.
displayInfo

string

A string that supplements the displayName 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".
potentialYoutubeReach

string (int64 format)

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

The share of subscribers within this attribute, between and including 0 and 1. This field is not populated in every response.
Union field dimension_metadata. Metadata specific to the dimension of this attribute. dimension_metadata can be only one of the following:
youtubeChannelMetadata

object (YouTubeChannelAttributeMetadata)

Special metadata for a YouTube channel.
dynamicAttributeMetadata

object (DynamicLineupAttributeMetadata)

Special metadata for a YouTube Dynamic Lineup.
locationAttributeMetadata

object (LocationAttributeMetadata)

Special metadata for a Location.

YouTubeChannelAttributeMetadata

Metadata associated with a YouTube channel attribute.

JSON representation 
{
  "subscriberCount": string
}
Fields
subscriberCount

string (int64 format)

The approximate number of subscribers to the YouTube channel.

DynamicLineupAttributeMetadata

Metadata associated with a Dynamic Lineup attribute.

JSON representation 
{
  "inventoryCountry": {
    object (LocationInfo)
  },
  "sampleChannels": [
    {
      object (SampleChannel)
    }
  ],
  "medianMonthlyInventory": string,
  "channelCountLowerBound": string,
  "channelCountUpperBound": string
}
Fields
inventoryCountry

object (LocationInfo)

The national market associated with the lineup.
sampleChannels[]

object (SampleChannel)

Examples of channels that are included in the lineup.
medianMonthlyInventory

string (int64 format)

The median number of impressions per month on this lineup.
channelCountLowerBound

string (int64 format)

The lower end of a range containing the number of channels in the lineup.
channelCountUpperBound

string (int64 format)

The upper end of a range containing the number of channels in the lineup.

SampleChannel

A YouTube channel returned as an example of the content in a lineup.

JSON representation 
{
  "youtubeChannel": {
    object (YouTubeChannelInfo)
  },
  "displayName": string,
  "youtubeChannelMetadata": {
    object (YouTubeChannelAttributeMetadata)
  }
}
Fields
youtubeChannel

object (YouTubeChannelInfo)

A YouTube channel.
displayName

string

The name of the sample channel.
youtubeChannelMetadata

object (YouTubeChannelAttributeMetadata)

Metadata for the sample channel.

LocationAttributeMetadata

Metadata associated with a Location attribute.

JSON representation 
{
  "countryLocation": {
    object (LocationInfo)
  }
}
Fields
countryLocation

object (LocationInfo)

The country location that this attribute’s sub country location is located in.