Google Ads API Release Notes

Changes

• Renamed the field BudgetPerDayMinimumErrorDetails.minimum_bugdet_amount_micros to minimum_budget_amount_micros.

New limits are enforced for batch jobs

• Added a limit of 10,000 operations per AddBatchJobOperations request.
• Updated handling for the page_size field in ListBatchJobResultsRequest :
  • If page_size is not set or is 0, it now defaults to the maximum of 1,000 (previously returned INVALID_PAGE_SIZE).
  • If page_size exceeds 1,000, the API now returns an INVALID_PAGE_SIZE error (previously silently capped at 1,000).

Removed AssetPerformanceLabel for Performance Max campaigns

The functionality of the removed Campaign.url_expansion_opt_out is now managed by setting the AssetAutomationType FINAL_URL_EXPANSION_TEXT_ASSET_AUTOMATION in AssetAutomationSetting.

In ReachPlanService , added the field trueview_views , which replaces the views field.

Renamed several video-views related metrics:

• average_cpv is now trueview_average_cpv
• video_view_rate is now video_trueview_view_rate
• video_views is now video_trueview_views
• video_view_rate_in_feed is now video_trueview_view_rate_in_feed
• video_view_rate_in_stream is now video_trueview_view_rate_in_stream
• video_view_rate_shorts is now video_trueview_view_rate_shorts

Warning: v18 of the Google Ads API is now sunset. These instructions are for those who missed the deadline and must upgrade.

Changes to services and their components

API-wide

All feed-related entities are removed from the API. Feeds have been deprecated for some time, replaced with assets. Removed entities and their associated services: AdGroupExtensionSetting AdGroupFeed CampaignExtensionSetting CampaignFeed CustomerExtensionSetting CustomerFeed ExtensionFeedItem Feed FeedItem FeedItemSet FeedItemSetLink FeedItemTarget FeedMapping Removed enums: FeedOrigin PlaceholderType Removed fields: ChangeEvent.{feed,feed_item,feed_origin} ChangeEvent.ChangedResource.{feed,feed_item,campaign_feed,ad_group_feed} ChangeStatus.{feed,feed_item,ad_group_feed,campaign_feed,feed_origin} Campaign.DynamicSearchAdsSetting.feeds LocationGroupInfo.feed Segments.placeholder_type Removed views: FeedPlaceholderView

AudienceInsightsService

Submessage types AudienceInsightsAttribute, AudienceInsightsTopic, AudienceInsightsEntity, AudienceInsightsCategory, AudienceInsightsDynamicLineup, AudienceInsightsAttributeMetadata, YouTubeChannelAttributeMetadata, DynamicLineupAttributeMetadata, LocationAttributeMetadata, and UserInterestAttributeMetadata have been migrated out of the "resources" folder into the "common" folder so that they can be reused with the ContentCreatorInsightsService. These types work the same way, but you may need to import them from a different location, depending on your implementation.

AdGroupType, AdType, and AdvertisingChannelSubType

The VIDEO_OUTSTREAM ad type has been removed.

DemandGenVideoResponsiveAdInfo

When specifying the Campaign.asset_automation_settings or AdGroupAd.ad_group_ad_asset_automation_settings, omitting a setting for AssetAutomationType.GENERATE_SHORTER_YOUTUBE_VIDEOS for the DemandGenVideoResponsiveAdInfo ad type will result in being opted in for this feature. Previously, when omitting this setting, they were opted out.

The following new features and updates were added in v22.
See Upgrade to the latest version for guidance.

Assets

• Added LANDING_PAGE_PREVIEW as a new image asset field type.
• Introduced the AssetGenerationService (Beta):
  • This service allows generating text and image assets using generative AI. This service is initially available only to a limited set of closed beta participants.
  • GenerateText: Generates text based on inputs like final URL, freeform prompts, keywords, and existing campaign context.
  • GenerateImages: Generates images based on inputs like final URL, freeform prompts, existing campaign context, or by recontextualizing existing product images.
  • Errors during asset generation are returned with codes from AssetGenerationErrorEnum.

Campaigns

• Added new bidding goals for App campaigns for installs (ACi) to optimize without specifying a target, useful for rapid scaling or when determining the right target is challenging. In AppCampaignBiddingStrategyGoalType:
  • OPTIMIZE_IN_APP_CONVERSIONS_WITHOUT_TARGET_CPA: Use with standard Maximize Conversions.
  • OPTIMIZE_TOTAL_VALUE_WITHOUT_TARGET_ROAS: Use with standard Maximize Conversion Value.
• Added support for the fixed share of voice bidding strategy type.
• Added Campaign.feed_types, showing the types of feeds attached to a campaign. For Performance Max campaigns, this can indicate the business vertical, such as MERCHANT_CENTER_FEED for retail.
• Allowed attaching NEGATIVE_KEYWORDS shared sets to MULTI_CHANNEL (for App campaigns) and LOCAL campaigns.

Demand Gen

• Added the TargetCPC bidding strategy for Demand Gen campaigns. This strategy sets bids to maximize clicks at the configured target cost-per-click (CPC).
  • Set the campaign-level target CPC using Campaign.target_cpc.
  • Override at the ad group level using AdGroup.target_cpc_micros.
• Added a new AssetAutomationType:
  • GENERATE_DESIGN_VERSIONS_FOR_IMAGES: Available for DemandGenMultiAssetAds. If enabled, this adds design elements and embeds text assets into image assets to create new image assets with different aspect ratios. New DemandGenMultiAssetAds are opted in by default.
• Added a new AssetAutomationType:
  • GENERATE_VIDEOS_FROM_OTHER_ASSETS: Available for DemandGenMultiAssetAds. If enabled, it generates videos using other assets like images and text. These videos can then be used to create new DemandGenVideoResponsiveAds. New DemandGenMultiAssetAds are opted in by default.
• Renamed the field BudgetPerDayMinimumErrorDetails.minimum_bugdet_amount_micros to minimum_budget_amount_micros.

General

• Added a limit of 10,000 operations per AddBatchJobOperations request.
• Updated handling for the page_size field in ListBatchJobResultsRequest:
  • If page_size is not set or is 0, it now defaults to the maximum of 1,000 (previously returned INVALID_PAGE_SIZE).
  • If page_size exceeds 1,000, the API now returns an INVALID_PAGE_SIZE error (previously silently capped at 1,000).
• Added a new error code: QuotaError.PAYMENTS_PROFILE_ACTIVATION_RATE_LIMIT_EXCEEDED to indicate when the payment profile activation rates limit has been exceeded.

Performance Max

• Added new AssetAutomationType values for Performance Max campaigns:
  • GENERATE_IMAGE_ENHANCEMENT: Enables automatic creation of enhanced images such as auto-cropping. Enabled by default.
  • GENERATE_IMAGE_EXTRACTION: Enables automatically sourcing images from final URLs. Defaults to the account-level Dynamic Image Extension setting.
• Removed AssetPerformanceLabel for Performance Max campaigns.
• The functionality of the removed Campaign.url_expansion_opt_out is now managed by setting the AssetAutomationType FINAL_URL_EXPANSION_TEXT_ASSET_AUTOMATION in AssetAutomationSetting.
• Added new segments for Performance Max campaigns. Each of these segments is only available for Performance Max campaigns and won't return data when any other campaign type is selected.
  • ad_using_product_data: Indicates if an ad uses product data from a Google Merchant Center feed.
  • ad_using_video: Indicates if an ad uses a video asset.

Planning

• In UserListCrmDataSourceType, added the value THIRD_PARTY_PARTNER_DATA.
• Added new error codes related to partner audiences:
  • PARTNER_AUDIENCE_SOURCE_NOT_SUPPORTED_FOR_USER_LIST_TYPE
  • PARTNER_AUDIENCE_TYPE_NOT_SUPPORTED_FOR_USER_LIST_TYPE
  • COMMERCE_PARTNER_NOT_ALLOWED
  • PARTNER_AUDIENCE_INFO_NOT_SUPPORTED_FOR_USER_LIST_TYPE
  • PARTNER_MANAGER_ACCOUNT_DISALLOWED
  • PARTNER_NOT_ALLOWLISTED_FOR_THIRD_PARTY_PARTNER_DATA
  • ADVERTISER_TOS_NOT_ACCEPTED
  • ADVERTISER_PARTNER_LINK_MISSING
  • ADVERTISER_NOT_ALLOWLISTED_FOR_THIRD_PARTY_PARTNER_DATA
  • ACCOUNT_SETTING_TYPE_NOT_ALLOWED_FOR_USER_LIST_TYPE
  • INVALID_CAMPAIGN_TYPE_FOR_THIRD_PARTY_PARTNER_DATA_LIST
• Added is_active_live_stream_creator to YouTubeMetrics. This is returned by ContentCreatorInsightsService.GenerateCreatorInsights and indicates if a creator published a livestream in the past 90 days.
• Added a new PlannableUserListMetadata message that contains UserListCrmDataSourceType in PlannableUserList. This message is returned by 'ReachPlanService.ListPlannableUserLists' to show if a CRM user list data source is either FIRST_PARTY or THIRD_PARTY_PARTNER_DATA.
• In ReachPlanService, added the field trueview_views, which replaces the views field.
• In TrendInsight, added support for related_videos and related_creators. Also added video properties metadata and publish dates in YouTubeVideoAttributeMetadata.video_properties and YouTubeVideoAttributeMetadata.publish_date.
• AudienceInsightsService.GenerateInsightsFinderReport now supports parental_status and income_ranges, and more complex AND/OR combinations of topics and audiences.

Reports

• Added two new click types: CLICK_TO_MESSAGE_THIRD_PARTY_CLICK and CLICK_TO_MESSAGE_LANDING_PAGE_CLICK.
• AssetGroupAsset is now segmentable by device, conversion_action, conversion_action_name, and conversion_action_category.
• AdGroupAdAssetView and AdGroupAdAssetCombinationView now fully support performance and conversion metrics for RESPONSIVE_SEARCH_AD. Previously, only impressions were returned for this ad type in these views.
• To facilitate Smart Bidding Exploration, the following metrics are now segmentable by date fields (date, month, quarter, week, year):
  • clicks_unique_query_clusters
  • conversions_unique_query_clusters
  • impressions_unique_query_clusters
• Added a new resource: TargetingExpansionView, which reports metrics for expansions over manual targeting, such as keywordless expansion for AI Max for Search Campaigns.
• Added new segments for PMax campaigns. See Performance Max updates.

Shopping

• Fixed the campaign and ad group scoping of metrics in the ShoppingProduct resource.

Unified Goals

• Added support for customer retention goals to optimize for re-engaging existing customers.
  • Configure targeting using CampaignRetentionGoalSettings.target_option:
    • TARGET_SPECIFIC: Only uses users from user lists associated with the campaign. (Currently allowlist only).
    • TARGET_ALL (Default): Targets all users for re-engagement.

Video

• Renamed several video-views related metrics:
  • average_cpv is now trueview_average_cpv
  • video_view_rate is now video_trueview_view_rate
  • video_views is now video_trueview_views
  • video_view_rate_in_feed is now video_trueview_view_rate_in_feed
  • video_view_rate_in_stream is now video_trueview_view_rate_in_stream
  • video_view_rate_shorts is now video_trueview_view_rate_shorts
• Added metrics for video ad watch time:
  • video_watch_time_duration_millis: Total watch time.
  • average_video_watch_time_duration_millis: Average watch time per impression.

The type of asset automation.

Enums

• UNSPECIFIED
  Not specified.

• UNKNOWN
  Used as a return value only. Represents value unknown in this version.

• TEXT_ ASSET_ AUTOMATION
  Text asset automation includes headlines and descriptions. By default, advertisers are opted-in for Performance Max and opted-out for Search.

• GENERATE_ VERTICAL_ YOUTUBE_ VIDEOS
  Converts horizontal video assets to vertical orientation using content-aware technology. By default, advertisers are opted in for DemandGenVideoResponsiveAd.

• GENERATE_ SHORTER_ YOUTUBE_ VIDEOS
  Shortens video assets to better capture user attention using content-aware technology. By default, advertisers are opted in for DemandGenVideoResponsiveAd.

• GENERATE_ LANDING_ PAGE_ PREVIEW
  Generates a preview of the landing page shown in the engagement panel. By using this feature, you confirm that you own all legal rights to the images on the landing page used by this account (or you have permission to share the images with Google). You hereby instruct Google to publish these images on your behalf for advertising or other commercial purposes.

• GENERATE_ ENHANCED_ YOUTUBE_ VIDEOS
  Generates video enhancements (vertical and shorter videos) for PMax campaigns. Opted in by default.

• GENERATE_ IMAGE_ ENHANCEMENT
  Generates image enhancements (AutoCrop and AutoEnhance). Opted in by default for pmax.

• GENERATE_ IMAGE_ EXTRACTION
  Generates image extraction. It defaults to account level Dynamic Image Extension control value.

• GENERATE_ DESIGN_ VERSIONS_ FOR_ IMAGES
  Adds design elements and embeds text assets into image assets to create images with different aspect ratios. By default, advertisers are opted in for DemandGenMultiAssetAd.

• FINAL_ URL_ EXPANSION_ TEXT_ ASSET_ AUTOMATION
  Controls automation for text assets related to Final URL expansion. This includes automatically creating dynamic landing pages from the final URL and generating text assets from the content of those landing pages. This setting is turned OFF by default for Search campaigns, but it is turned ON by default for Performance Max campaigns.

• GENERATE_ VIDEOS_ FROM_ OTHER_ ASSETS
  Generates videos using other Assets as input, such as images and text. By default, advertisers are opted in for DemandGenMultiAssetAd.