Google Ads API Version 15 Now Available

Google has released version 15 of the Google Ads API last week but I did not notice until over the weekend. The big updates include but are not limited to new recommendation types, updates to Performance Max, new lookalike segments and improved offline conversion upload diagnostics, plus so much more.

This is a big update, since the last update was version 14.1 which was released in August. Version 13.1 preceded this new version, which was released in April 2023. Version 12.0 was released in October 2022, Version 11.0 of the Google Ads API was released in June, and version 11.1 was in August. Also Version 10.1 was released on April 27, 2022 and version 10.0 was released on February 9, 2022. And Google has sunset the AdWords API on April 27th which will completely stop working at the end of July.

Here is a video overview of what is new with version 15 of the Google Ads API:

Here are the release notes for version 15:

Account Management

• If your account is suspended because of unauthorized account activity, customer.status and customer_client.status are now returned as SUSPENDED. Previously, they were returned as ENABLED.
• Added support for adding and removing a link between a Google Ads account and a Merchant Center account:
  Added ProductLink.merchant_center and MerchantCenterIdentifier.
  Added LinkedProductType.MERCHANT_CENTER.
• Added ProductLinkInvitationService and ProductLinkInvitation to support updating a link invitation sent from other products, available for Hotel Center and Merchant Center accounts.
• Removed MerchantCenterLinkService.
  To link Google Ads accounts with Merchant Center accounts, use ProductLinkInvitationService and ProductLinkService.
• Removed AccountLink.hotel_center and support for updating link invitations from Hotel Center accounts using AccountLinkService.
  To update a link invitation from a Hotel Center account, use ProductLinkInvitationService.

Assets

• Replaced ImageAdInfo.media_file with ImageAdInfo.image_asset to support adding and removing images using the assets. As a result, we also removed MediaFileService, which is no longer needed.
• Added ListingGroupFilterDimension.webpage to support creating a listing group filter based on custom labels and URL substrings.
  Also replaced AssetGroupListingGroupFilter.vertical with AssetGroupListingGroupFilter.listing_source and ListingGroupFilterListingSource
• Added asset_group_asset.source to show the source of the asset group asset.
• Added ad_group_ad_asset_view.source to show the source of ad group ad asset.

Audiences

• For Customer Match, added CustomerMatchUserListMetadata.consent to support providing a consent. No action is required at this time, but follow our blog for updates in the coming months.
• For Store Sales, added UserData.consent to support providing a consent. No action is required at this time, but follow our blog for updates in the coming months.
• Added UserList.lookalike_user_list to support creating a Lookalike segment, an audience created based on the provided existing seed audience. Lookalike segments can be used in a Demand Gen campaign only.

Campaigns

• Updates to Performance Max campaigns:
  AssetGroupSignal now supports for two signal types that can be attached to an asset group for enhanced targeting:
  AssetGroupSignal.audience
  Added Audience.scope and Audience.asset_group to limit audience usage to a specific asset group. Audience.asset_group must be set if and only if Audience.scope is ASSET_GROUP.
  AssetGroupSignal.search_theme
  Added CriterionType.SEARCH_THEME to support this new criterion type. This new criterion type can only be used in Performance Max campaigns to create an AssetGroupSignal by populating the AssetGroupSignal.search_theme with a SearchThemeInfo criterion.
  Added AssetGroupSignalOperation.exempt_policy_violation_keys to support requesting exemption when adding asset group signals.
  Added a new asset_group_top_combination_view to report the top performing assets at the asset group level.
  asset_group can now be queried with metric fields to support retrieving the performance of a Performance Max campaign.
  In PerformanceMaxUpgradeStatus, renamed UPGRADE_ELIGIBLE to UPGRADE_ELIGIBLE.
• For Demand Gen and Discovery Target CPA campaigns, the campaign-level Target CPA bid simulations (campaign_simulation.target_cpa_point_list.points) now returns TargetCpaSimulationPoint.interactions instead of TargetCpaSimulationPoint.clicks.
• Added BrandSuggestionService that can suggest brands based on the provided brand prefix and the excluded list of brands. These brands can be used to create a BRAND criterion, added to a BRANDS shared set, and then attached to a campaign by creating a CampaignCriterion with brand_list set to the shared set. The campaign criteria can be targeted in Search campaigns and excluded in Performance Max campaigns, respectively.
  Fields:
  SharedCriterion.brand
  CampaignCriterion.brand_list
  Enums:
  SharedSetType.BRANDS
  CriterionType.BRAND_LIST
• Added Campaign.asset_automation_settings[] to show the automation status of each asset type.
• Added the following values to the CampaignPrimaryStatusReason enum: NO_ASSET_GROUPS and ASSET_GROUPS_PAUSED

Conversions

• Added CallConversion.consent and ClickConversion.consent to support providing a consent. No action is required at this time, but follow our blog for updates in the coming months.
• Added the following fields related to SKAdNetwork conversions, available when querying them with customer or campaign:
  Segments:
  segments.sk_ad_network_coarse_conversion_value
  segments.sk_ad_network_source_domain
  segments.sk_ad_network_source_type
  segments.sk_ad_network_postback_sequence_index
  Metrics:
  metrics.sk_ad_network_total_conversions
  metrics.sk_ad_network_installs
• Replaced metrics.sk_ad_network_conversions with metrics.sk_ad_network_installs.
• Added support for diagnosing offline conversion upload
  Moved the offline_conversion_upload_client_summary from a field on the customer resource to a top-level report. Use this report to obtain useful details of the conversion upload status such as the successful events count, success rate, and error percentage.
  Caveat: A conversion that is uploaded but results in a ConversionUploadError.CLICK_NOT_FOUND error is still counted as successful, but it’s also flagged as an OfflineConversionAlert.
  Added job_id as an optional parameter for the following request types so you can logically group multiple upload requests into a single conceptual job:
  UploadConversionAdjustmentsRequest
  UploadClickConversionsRequest
  Added INVALID_JOB_ID to the following errors:
  ConversionAdjustmentUploadError
  ConversionUploadError
  Replaced INVALID_CONVERSION_ACTION with NO_CONVERSION_ACTION_FOUND and INVALID_CONVERSION_ACTION_TYPE in the following errors:
  ConversionAdjustmentUploadError
  ConversionUploadError
• Added three reports to support Android Privacy Sandbox Cross-network attribution without redirects:
  android_privacy_shared_key_google_campaign which contains shared_campaign_key and some fields that help encode the key.
  android_privacy_shared_key_google_ad_group which contains shared_ad_group_key and some fields that help encode the key.
  android_privacy_shared_key_google_network_type which contains shared_network_type_key and some fields that help encode the key.
• Added ConversionActionError.CANNOT_SET_RULE_BASED_ATTRIBUTION_MODELS. A ConversionActionOperation that attempts to use one of the deprecated rule-based attribution ****** now fails with this error. Previously, the operation would fail with an UNKNOWN error.

Hotel & Travel

• Added support for the following fields in travel_activity_group_view and travel_activity_performance_view:
  Segments:
  segments.activity_account_id
  segments.activity_rating
  segments.external_activity_id
  Metrics:
  metrics.search_absolute_top_impression_share
  metrics.search_budget_lost_absolute_top_impression_share
  metrics.search_budget_lost_impression_share
  metrics.search_budget_lost_top_impression_share
  metrics.search_impression_share
  metrics.search_rank_lost_absolute_top_impression_share
  metrics.search_rank_lost_impression_share
  metrics.search_rank_lost_top_impression_share
  metrics.search_top_impression_share

Local Services Ads

• Added LocalServicesSettings and its fields to the customer report for returning a Local Services advertiser’s granular license and insurance statuses.
• Added the following new reports for Local Services:
  local_services_lead contains all the details pertaining to Local Services Ads leads such as lead_charged, lead_type, lead_status.
  Enums:
  LeadStatus
  LeadType
  local_services_lead_conversation contains message and phone conversation details such as conversation_channel, call_duration_millis, call_recording_url.
  Phone call recording URL is authenticated against the target customer account and its manager accounts.
  local_services_verification_artifact returns a Local Services advertiser’s artifacts such as background check, business licenses, and business insurance data. Any documents associated with license and insurance can be accessed through a URL.
  Enums:
  LocalServicesVerificationArtifactStatus
  LocalServicesVerificationArtifactType
  LocalServicesInsuranceRejectionReason
  LocalServicesLicenseRejectionReason

Planning

• Added support to return Forecast.views and PlannedProductForecast.views for ReachPlanService.ListPlannableProducts for applicable product types.
• Added support to return PlannableTargeting.surface_targeting for ReachPlanService.ListPlannableProducts, which describes the available surfaces for a product.
• Added a new ReachPlanSurface enum.
• Added support for targeting Target frequency using AdvancedProductTargeting.target_frequency_settings, which returns PlannedProductForecast.average_frequency.
• Added AudienceInsightsService.GenerateSuggestedTargetingInsights to return suggested targetable audiences.
• Added the following values to ReachPlanError:
  NOT_FORECASTABLE_NOT_ENOUGH_INVENTORY
  NOT_FORECASTABLE_ACCOUNT_NOT_ENABLED

Recommendations

• Added RecommendationSubscriptionService which manages recommendation subscriptions:
  Resource: RecommendationSubscription
  Field: MutateOperation.recommendation_subscription_operation
  Enum: ChangeClientType.GOOGLE_ADS_RECOMMENDATIONS_SUBSCRIPTION
  Errors:
  RecommendationSubscriptionError
  RecommendationSubscriptionStatus
• Added the following types of recommendations:
  FORECASTING_SET_TARGET_CPA which recommends setting a target CPA for campaigns that don’t have one specified, in advance of a seasonal event that is forecasted to increase traffic.
  SET_TARGET_CPA which recommends setting a target CPA for campaigns that don’t have one specified.
  SET_TARGET_ROAS which recommends setting a target ROAS for campaigns that don’t have one specified.

Reporting

• Added the following new metrics, which can be queried with campaign (available for Display, Video, Discovery, and App campaigns) and segments.device:
  metrics.unique_users
  metrics.average_impression_frequency_per_user

Shopping

• Removed ShoppingSetting.sales_country, whose values are now returned as ShoppingSetting.feed_label.
  You can continue to use a specific Merchant Center feed for a campaign by using the ShoppingSetting.feed_label field. It should be set to the feed label value or the two-letter country code previously used for ShoppingSetting.sales_country. For more details, see the support article for feed labels.
• Removed the dependency of product categories on a country code in reporting. The set of supported category IDs has not changed.
  Replaced the following fields used in shopping_performance_view:
  segments.product_bidding_category_level1 with segments.product_category_level1
  segments.product_bidding_category_level2 with segments.product_category_level2
  segments.product_bidding_category_level3 with segments.product_category_level3
  segments.product_bidding_category_level4 with segments.product_category_level4
  segments.product_bidding_category_level5 with segments.product_category_level5
  Replaced product_bidding_category_constant with product_category_constant, which returns all available localizations of a category in a repeated field.
  Replaced ListingDimensionInfo.product_bidding_category with ListingDimensionInfo.product_category.
  Replaced ListingGroupFilterDimension.product_bidding_category with ListingGroupFilterDimension.product_category.
• Removed support for adding Campaign.shopping_setting to Search campaigns. Trying to create a Search campaign with Campaign.shopping_setting or add Campaign.shopping_setting to an existing Search campaign now results in OPERATION_NOT_PERMITTED_FOR_CONTEXT.
• Removed support for adding CampaignCriterion.listing_scope to Search campaigns. Trying to add CampaignCriterion.listing_scope to an existing Search campaign now results in OPERATION_NOT_PERMITTED_FOR_CONTEXT.
• Added following conversions with cart data metrics:
  metrics.orders
  metrics.average_order_value_micros
  metrics.average_cart_size
  metrics.cost_of_goods_sold_micros
  metrics.gross_profit_micros
  metrics.gross_profit_margin
  metrics.revenue_micros
  metrics.units_sold
  metrics.cross_sell_cost_of_goods_sold_micros
  metrics.cross_sell_gross_profit_micros
  metrics.cross_sell_revenue_micros
  metrics.cross_sell_units_sold
  metrics.lead_cost_of_goods_sold_micros
  metrics.lead_gross_profit_micros
  metrics.lead_revenue_micros
  metrics.lead_units_sold
  All these metrics are selectable with following reports:
  ad_group
  ad_group_ad
  asset_group_product_group_view
  campaign
  customer
  keyword_view
  product_group_view
  shopping_performance_view

Unified Goals

• Added CustomerLifecycleGoalService.ConfigureCustomerLifecycleGoals for configuring customer acquisition goals at the customer level.
  Report: customer_lifecycle_goal
• Added CampaignLifecycleGoalService.ConfigureCampaignLifecycleGoals for configuring customer acquisition goals at the campaign level.
  Report: campaign_lifecycle_goal
• Added CampaignConversionGoalError.CANNOT_USE_STORE_SALE_GOAL_FOR_PERFORMANCE_MAX_CAMPAIGN.
• Added the following values to ConversionGoalCampaignConfigError:
  EMPTY_CONVERSION_GOALS
  STORE_SALE_STORE_VISIT_CANNOT_BE_BOTH_INCLUDED
  PERFORMANCE_MAX_CAMPAIGN_CANNOT_USE_CUSTOM_GOAL_WITH_STORE_SALES

Videos

• Added support for targeting Google TV at the campaign level:
  Added NetworkSettings.target_google_tv_network
  Added AdNetworkType.GOOGLE_TV.
• Added support for targeting YouTube at the campaign level:
  Added NetworkSettings.target_youtube
  In AdNetworkType, merged YOUTUBE_WATCH and YOUTUBE_SEARCH into YOUTUBE.
  Added CampaignError.CANNOT_TARGET_DISPLAY_NETWORK_WITHOUT_YOUTUBE.

I should not that there are also Updates to Customer Match, Conversions, and Store Sales Uploads.

Finally, happy 23rd birthday Google Ads (AdWords):

Google Ads turns 23 years old tomorrow – it launched on October 23, 2000 pic.twitter.com/g9KY9oltxQ

— Barry Schwartz (@rustybrick) October 22, 2023

Forum discussion at X.