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

object (InsightsAudience)

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

object (InsightsAudience)

The baseline audience to which the audience of interest is being compared.
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. Supported dimensions are KNOWLEDGE_GRAPH, GEO_TARGET_COUNTRY, SUB_COUNTRY_LOCATION, YOUTUBE_CHANNEL, YOUTUBE_DYNAMIC_LINEUP, AFFINITY_USER_INTEREST, IN_MARKET_USER_INTEREST, PARENTAL_STATUS, INCOME_RANGE, AGE_RANGE, and GENDER.
customerInsightsGroup

string

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

Response body

Response message for AudienceInsightsService.GenerateAudienceCompositionInsights.

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

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.

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.