Page Summary

outlined_flag

• Periodically upgrading to the newest major version of the Google Ads API is recommended, especially if a version is sunsetting or to use new features.

• To get started with an upgrade, update your client libraries to use the newest endpoint, review release notes for changes, and check tables for version-specific focus areas.

• The provided content includes specific changes for upgrading from v21 to v22, v20 to v21, v19 to v20, and v18 to v19, detailing renamed fields, new limits, removed elements, and service/component changes.

• Upgrading from v18 to v19 is specifically highlighted as v18 is sunset, requiring immediate action.

Periodically, you might want to upgrade from an older major version of theGoogle Ads API to a newer major version. It could be because a version is sunsetting,or it could be because you want to use a new feature. We recommend that youalways upgrade to the newest version.

Check out ourdeprecation schedule to plan yourupgrades. See ourversioning guide to learn howversioning works.

Here's a checklist to help you get started with the process of upgrading:

1. Your endpoint will change when you change major versions. Update yourclient libraries to use the newest endpoint.
2. Go through therelease notes to see changes thatwere introduced in each release.
3. Check out the key changes lists, likeKey changes from v22 to v23,for specific areas to focus on for the version to which you are upgrading.
4. Check out the proto difference tables, likeProto differences between v22 and v23.

v22 to v23

The following sections describe key changes and proto differences for upgradingfrom v22 to v23.

Key changes from v22 to v23

• AddedIncentiveService to allow partnersto programmatically fetch and apply Google Ads incentives for their customers.
• Sharing ads among multiple ad groups is no longer allowed. Attempting to doso returnsAD_SHARING_NOT_ALLOWED.
• Deprecated create and update operations forCallAd andCallAdInfo.
• Added read-only fieldorientation toimage and video assets inAsset.
• Added support to retrieveCampaignAssetwith afield_type ofHEADLINE andDESCRIPTION.
• InInvoiceService.ListInvoices, youcan now request granular details, including campaign-level cost breakdown, bysettinginclude_granular_level_invoice_details inListInvoicesRequest.
• AddedCampaign.start_date_timeandCampaign.end_date_time to replaceCampaign.start_date andCampaign.end_date, allowing you to specify timecomponents for certain campaign types.
• In Demand Gen, added fieldDemandGenVideoResponsiveAdInfo.companion_bannerand removed fieldDemandGenMultiAssetAdInfo.lead_form_only.
• Enabled ad network type breakdown for Performance Max campaigns.
• AddedBenchmarksService to compareYouTube advertisement data against industry benchmarks.
• AddedAudienceInsightsService.GenerateAudienceDefinitionto translate a free text description of a target audience into matching audienceattributes using generative AI.
• Removed aggregate asset performance label metrics from reports. Theperformance label enum is no longer returned for Search and Display campaigns.
• AddedPerStoreView to query store locationdetails andMatchedLocationInterestViewfor AI Max campaigns to view performance metrics broken down by geographiclocations users showed interest in.
• ShoppingPerformanceView nowsupports metrics segmented by conversion date, and new competitive metrics:search_budget_lost_impression_share,search_rank_lost_impression_share,search_budget_lost_absolute_top_impression_share, andsearch_rank_lost_absolute_top_impression_share.
• AddedShoppingProduct.product_image_uri.

Proto differences between v22 and v23

This table shows the protos that were added, removed, and changed in theGoogle Ads API v23 release. You can click the links to view the protos in ourGitHub repository

after they're released. You can view quick and full-context diffs in theChanged tab.

v21 to v22

The following sections describe key changes and proto differences for upgradingfrom v21 to v22.

Key changes from v21 to v22

• Renamed the fieldBudgetPerDayMinimumErrorDetails.minimum_bugdet_amount_micros tominimum_budget_amount_micros.

• New limits are enforced for batch jobs.

  • Added a limit of 10,000 operations perAddBatchJobOperations request.
  • Updated handling for thepage_size field inListBatchJobResultsRequest:
    • Ifpage_size is not set or is 0, it now defaults to the maximum of1,000 (previously returnedINVALID_PAGE_SIZE).
    • Ifpage_size exceeds 1,000, the API now returns anINVALID_PAGE_SIZE error (previously silently capped at 1,000).

• RemovedAssetPerformanceLabel for Performance Max campaigns.

• The functionality of the removedCampaign.url_expansion_opt_outis now managed by setting theAssetAutomationTypeFINAL_URL_EXPANSION_TEXT_ASSET_AUTOMATIONinAssetAutomationSetting.

• InReachPlanService, added the fieldtrueview_views, whichreplaces theviews field.

• Renamed several video-views related metrics:

  • average_cpv is nowtrueview_average_cpv
  • video_view_rate is nowvideo_trueview_view_rate
  • video_views is nowvideo_trueview_views
  • video_view_rate_in_feed is nowvideo_trueview_view_rate_in_feed
  • video_view_rate_in_stream is nowvideo_trueview_view_rate_in_stream
  • video_view_rate_shorts is nowvideo_trueview_view_rate_shorts

Proto differences between v21 and v22

This table shows the protos that were added, removed, and changed in theGoogle Ads API v22 release. You can click the links to view the protos in ourGitHub repositoryafter they're released. You can view quick and full-context diffs in theChanged tab.

v20 to v21

The following sections describe key changes and proto differences for upgradingfrom v20 to v21.

Key changes from v20 to v21

Proto differences between v20 and v21

This table shows the protos that were added, removed, and changed in theGoogle Ads API v21 release. You can click the links to view the protos in ourGitHub repositoryafter they're released. You can view quick and full-context diffs in theChanged tab.

v19 to v20

The following sections describe key changes and proto differences for upgradingfrom v19 to v20. Note that v19 is now sunset.

Key changes from v19 to v20

Proto differences between v19 and v20

This table shows the protos that were added, removed, and changed in theGoogle Ads API v20 release. You can click the links to view the protos in ourGitHub repositoryafter they're released. You can view quick and full-context diffs in theChanged tab.