Audience insights

Page Summary

• Access to the AudienceInsightsService is currently limited to accounts on an allowlist.

• The AudienceInsightsService integrates Google audience insights data into tools, helping users understand target audiences better.

• The API offers three main use cases: refining and uncovering audiences, informing campaign planning, and developing creative messages.

• Eligibility for the AudienceInsightsService includes criteria such as existing access to Insights Finder, having a planning tool, and agreeing to data usage requirements.

• The AudienceInsightsService provides various methods for generating insights, such as audience composition, audience overlap, suggested targeting, and targeting suggestion metrics.

Important: This feature is only available to accounts on an allowlist. Contact your Google representative if you need access to this feature.

All requests to AudienceInsightsService are rate-limited. Fewer requests are permitted per day for generateAudienceCompositionInsights and generateSuggestedTargetingInsights than for other Audience Insights methods. See API quotas for more details.

AudienceInsightsService lets you integrate Google audience insights data into your planning tools. The data helps media agencies and media planners gain a deeper understanding of their target audience, including demographics, interests, and online behavior.

Audience insights help you understand an audience, category, topic, or brand by providing a high-level overview. By analyzing user behaviors on related topics, you can use these audience insights to uncover the associations and perceptions that consumers have and identify new audience segments.

The API supports three primary use cases:

• Refine and uncover audiences: Understand consumers' unique interests and behaviors to identify new audiences for a brand, develop audience personas, and refine audience segmentation strategies.
• Inform campaign planning: Translate data outputs into YouTube target audiences to plan against, estimate the potential reach of targeted audiences, and measure the overlap between audience segments to maximize campaign reach.
• Develop creative messages: Tailor creative messages to your target audience based on the topics and affinities they engage with most.

Eligibility requirements

To be eligible for AudienceInsightsService, partners must satisfy the following conditions:

• Have existing access, or eligibility for access, to Insights Finder.
• Have a planning tool or user interface that integrates the API.
• Use the API for media planning purposes or other relevant use cases.
• Complete a pre-screen assessment.
• Follow data usage requirements and undergo periodic data audits.
• Accept the Google Ads API terms of service and the associated data usage policy.

Contact your Google representative for more information.

List insights eligible dates

A typical workflow begins by checking which calendar months and date windows are available for analysis. The listInsightsEligibleDates method returns a ListInsightsEligibleDatesResponse, whose data_months field lists the months (in YYYY-MM format) for which audience insights data is available.

The response's last_thirty_days field contains the exact date range that generateAudienceCompositionInsights uses when data_month is not set in the request.

List audience insights attributes

Before querying audience composition or overlap metrics, discover valid attribute IDs using listAudienceInsightsAttributes. This method returns a ListAudienceInsightsAttributesResponse containing the available attributes for the requested dimensions.

For example, if AFFINITY_USER_INTEREST is selected as a dimension in the request, the method returns supported affinity audiences such as "Sports Fans" or "Music Lovers". Other supported user interest dimensions include IN_MARKET_USER_INTEREST and LIFE_EVENT_USER_INTEREST. You can set multiple dimensions in a single request. For a complete list of supported dimensions, see the dimensions field reference.

When searching for Knowledge Graph entities (topics) using the KNOWLEDGE_GRAPH dimension, you must provide a string query in the query_text field (for example, "football and the World Cup").

You can optionally include knowledge_graph_entity_search_options to customize your topic search:

• Filter by capabilities: Use search_filter to narrow down the retrieved entities to only those supporting specific capabilities. For example, you can filter for topics supported as creator attributes by providing CREATOR_ATTRIBUTE in the entity_capability_filters field. Multiple capabilities can be provided and are combined with OR logic.
• Retrieve all creator attributes: Set get_all_creator_attributes to true to retrieve all available Knowledge Graph entities tagged as creator attributes. When using this option, the KNOWLEDGE_GRAPH dimension must be selected, query_text must be empty, and you cannot combine this option with a search_filter.

The attributes returned by this discoverability method can be used as inputs for other AudienceInsightsService methods.

Each AudienceInsightsAttributeMetadata object in ListAudienceInsightsAttributesResponse provides a structured representation of an audience attribute alongside descriptive properties and engagement metrics. It includes the attribute's primary definition, display name, dimension type, and estimated audience reach. See the AudienceInsightsAttributeMetadata reference for field definitions.

Generate audience definition

The generateAudienceDefinition method translates a freeform text description of an audience into structured audience attribute suggestions that you can pass to downstream insight methods.

Generate suggested targeting insights

The generateSuggestedTargetingInsights method returns a collection of targeting insights (such as targetable audience segments) that are relevant to the requested audience.

You can specify the requested audience either as a structured InsightsAudienceDefinition or as a text description in InsightsAudienceDescription.

While generateAudienceCompositionInsights returns insights for individual attribute segments, generateSuggestedTargetingInsights returns bundled suggestions of targetable Google Ads audience segments. This method helps answer questions such as "Give me targetable audience suggestions for fathers in their 30s who enjoy fishing."

Generate targeting suggestion metrics

The generateTargetingSuggestionMetrics method returns a GenerateTargetingSuggestionMetricsResponse, which contains the potential YouTube population that can be reached for each audience definition requested in GenerateTargetingSuggestionMetricsRequest.

This method helps answer questions such as "How many men aged 18+ interested in camping in the United States can be reached on YouTube?"

Generate audience composition insights

The generateAudienceCompositionInsights method returns a GenerateAudienceCompositionInsightsResponse, which contains a list of attributes that represent the requested audience of interest, along with index and share metrics that compare each attribute's share of the audience against a baseline population.

You must provide a target country for the audience. The list of supported dimensions for retrieving composition insights is documented on the dimensions field of GenerateAudienceCompositionInsightsRequest.

This method helps answer questions such as "What are the top affinities my target audience is interested in compared to the general population, and how much more likely are they to engage with those affinities?"

Generate audience overlap insights

The generateAudienceOverlapInsights method returns a GenerateAudienceOverlapInsightsResponse, which contains a list of audience attributes with estimates of the overlap between their potential YouTube reach and that of a primary attribute.

You must provide a target country and a primary attribute. Age range, gender, affinity segments, and in-market segments are supported as audience dimensions.

This method helps answer questions such as "How large is the incremental audience size when we target both sports fans and music lovers in the United States?"

Generate Insights Finder report

The generateInsightsFinderReport method creates a saved report in Insights Finder based on the inputs specified in GenerateInsightsFinderReportRequest and returns a GenerateInsightsFinderReportResponse containing an externally accessible link to open that report in the Insights Finder UI.