Caution: You are viewing documentation for the API's REST interface. Most of our official client libraries use gRPC. See the REST Introduction for details.

Method: customers.generateAudienceCompositionInsights

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

HTTP request

POST https://googleads.googleapis.com/v12/customers/{customerId}:generateAudienceCompositionInsights

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 
{
  "audience": {
    object (InsightsAudience)
  },
  "dataMonth": string,
  "dimensions": [
    enum (AudienceInsightsDimension)
  ],
  "customerInsightsGroup": string
}
Fields
audience

object (InsightsAudience)

Required. The audience of interest for which insights are being requested.
dataMonth

string

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.
dimensions[]

enum (AudienceInsightsDimension)

Required. The audience dimensions for which composition insights should be returned.
customerInsightsGroup

string

The name of the customer being planned for. This is a user-defined value.

Response body

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

Response message for AudienceInsightsService.GenerateAudienceCompositionInsights.

JSON representation 
{
  "sections": [
    {
      object (AudienceCompositionSection)
    }
  ]
}
Fields
sections[]

object (AudienceCompositionSection)

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.

Authorization Scopes

Requires the following OAuth scope:

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

For more information, see the OAuth 2.0 Overview.

InsightsAudience

A set of users, defined by various characteristics, for which insights can be requested in AudienceInsightsService.

JSON representation 
{
  "countryLocations": [
    {
      object (LocationInfo)
    }
  ],
  "subCountryLocations": [
    {
      object (LocationInfo)
    }
  ],
  "gender": {
    object (GenderInfo)
  },
  "ageRanges": [
    {
      object (AgeRangeInfo)
    }
  ],
  "parentalStatus": {
    object (ParentalStatusInfo)
  },
  "incomeRanges": [
    {
      object (IncomeRangeInfo)
    }
  ],
  "dynamicLineups": [
    {
      object (AudienceInsightsDynamicLineup)
    }
  ],
  "topicAudienceCombinations": [
    {
      object (InsightsAudienceAttributeGroup)
    }
  ]
}
Fields
countryLocations[]

object (LocationInfo)

Required. The countries for the audience.
subCountryLocations[]

object (LocationInfo)

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 countryLocations and no further.
gender

object (GenderInfo)

Gender for the audience. If absent, the audience does not restrict by gender.
ageRanges[]

object (AgeRangeInfo)

Age ranges for the audience. If absent, the audience represents all people over 18 that match the other attributes.
parentalStatus

object (ParentalStatusInfo)

Parental status for the audience. If absent, the audience does not restrict by parental status.
incomeRanges[]

object (IncomeRangeInfo)

Household income percentile ranges for the audience. If absent, the audience does not restrict by household income range.
dynamicLineups[]

object (AudienceInsightsDynamicLineup)

Dynamic lineups representing the YouTube content viewed by the audience.
topicAudienceCombinations[]

object (InsightsAudienceAttributeGroup)

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.

InsightsAudienceAttributeGroup

A list of AudienceInsightsAttributes.

JSON representation 
{
  "attributes": [
    {
      object (AudienceInsightsAttribute)
    }
  ]
}
Fields
attributes[]

object (AudienceInsightsAttribute)

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.

AudienceCompositionSection

A collection of related attributes of the same type in an audience composition insights report.

JSON representation 
{
  "dimension": enum (AudienceInsightsDimension),
  "topAttributes": [
    {
      object (AudienceCompositionAttribute)
    }
  ],
  "clusteredAttributes": [
    {
      object (AudienceCompositionAttributeCluster)
    }
  ]
}
Fields
dimension

enum (AudienceInsightsDimension)

The type of the attributes in this section.
topAttributes[]

object (AudienceCompositionAttribute)

The most relevant segments for this audience. If dimension is GENDER, AGE_RANGE or PARENTAL_STATUS, then this list of attributes is exhaustive.
clusteredAttributes[]

object (AudienceCompositionAttributeCluster)

Additional attributes for this audience, grouped into clusters. Only populated if dimension is YOUTUBE_CHANNEL.

AudienceCompositionAttribute

An audience attribute with metadata and metrics.

JSON representation 
{
  "attributeMetadata": {
    object (AudienceInsightsAttributeMetadata)
  },
  "metrics": {
    object (AudienceCompositionMetrics)
  }
}
Fields
attributeMetadata

object (AudienceInsightsAttributeMetadata)

The attribute with its metadata.
metrics

object (AudienceCompositionMetrics)

Share and index metrics for the attribute.

AudienceCompositionMetrics

The share and index metrics associated with an attribute in an audience composition insights report.

JSON representation 
{
  "baselineAudienceShare": number,
  "audienceShare": number,
  "index": number,
  "score": number
}
Fields
baselineAudienceShare

number

The fraction (from 0 to 1 inclusive) of the baseline audience that match the attribute.
audienceShare

number

The fraction (from 0 to 1 inclusive) of the specific audience that match the attribute.
index

number

The ratio of audienceShare to baselineAudienceShare, or zero if this ratio is undefined or is not meaningful.
score

number

A relevance score from 0 to 1 inclusive.

AudienceCompositionAttributeCluster

A collection of related attributes, with metadata and metrics, in an audience composition insights report.

JSON representation 
{
  "clusterDisplayName": string,
  "clusterMetrics": {
    object (AudienceCompositionMetrics)
  },
  "attributes": [
    {
      object (AudienceCompositionAttribute)
    }
  ]
}
Fields
clusterDisplayName

string

The name of this cluster of attributes
clusterMetrics

object (AudienceCompositionMetrics)

If the dimension associated with this cluster is YOUTUBE_CHANNEL, then clusterMetrics are metrics associated with the cluster as a whole. For other dimensions, this field is unset.
attributes[]

object (AudienceCompositionAttribute)

The individual attributes that make up this cluster, with metadata and metrics.