Google Ads API Version 17 Now Available

Google Ads has released a major version release for the Google Ads API, version 17. Version 17 includes preparation for resource usage policy changes, page size changes, batch reporting changes, more PMax and match type reporting, plus much more.

Again, this is a major release of this update, before that was version 16.1 and then Version 16 in February 2024. Before that was version 15 back in October 2023. Then before that was version 14.1 which was released in August. Version 13.1 preceded this new version, which was released in April 2023. Version 13 was released in February 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 the changes:

[embedded content]

Here is the full change log:

Ads

• Removed AdService.getAd. This brings the AdService in line with other services in the Google Ads API. See Retrieving objects for the recommended way to fetch ads and other resource types.
• Added more validations for ImageAdInfo.image_asset regarding dimensions and format. The following errors may be thrown if the image is invalid: ImageError.UNEXPECTED_SIZE, ImageError.FORMAT_NOT_ALLOWED

Assets

• Added new enum: ClickType.AD_IMAGE
• Added the following new reports with new metrics for Performance Max and Search campaigns: campaign_aggregate_asset_view and channel_aggregate_asset_view

Audiences

• Added OfflineUserDataJobError.OPERATION_LEVEL_CONSENT_PROVIDED

Batch Jobs

• Added BatchJobError.REQUEST_TOO_LARGE, which will be thrown when the submitted AddBatchJobOperationsRequest is larger than 10484504 bytes.
• Added support for setting MutateOperation.asset_group_operation when using BatchJobService. This lets you use batch processing to create and manage entire Performance Max campaigns. See our new dedicated guide.

Campaigns

• Renamed Discovery to Demand Gen in all fields, enums, errors of all resources across the Google Ads API, such as campaigns, ads, and assets. For example, AdvertisingChannelType.DISCOVERY is now AdvertisingChannelType.DEMAND_GEN.
• Added Campaign.keyword_match_type to let you set keyword match type for all keywords in a campaign.

Conversions

• For SKAdNetwork conversions, Renamed segments.sk_ad_network_conversion_value to segments.sk_ad_network_fine_conversion_value. and Added segments.sk_ad_network_redistributed_fine_conversion_value.
• The following metrics are now returned with the response even when they are zero. This makes them consistent with other metrics. metrics.all_conversions_value_by_conversion_date, metrics.all_conversions_by_conversion_date, metrics.conversions_value_by_conversion_date, metrics.conversions_by_conversion_date

Criteria

• Added to following fields to AdGroupCriterion to show whether the ad group criterion is serving or the reasons why it’s not serving: primary_status and primary_status_reasons.
• Added support for metrics.search_impression_share for gender_view
• Added support for metrics.phone_calls for keyword_view

Local Services

• Added LocalServicesLeadService.AppendLeadConversation() used to append a new LocalServicesLeadConversation to LocalServicesLead, which sends the messages to users through appropriate channels like SMS depending on how the lead was created. The size of AppendLeadConversationRequest.conversations is limited to 1,000. Only LocalServicesLead with lead_type set to LeadType.MESSAGE can be specified in Conversation.local_services_lead.
• Added new enum values to ConversationType: WHATSAPP to represent a conversation introduced through WhatsApp. ADS_API to represent a conversation introduced using the new LocalServicesLeadService.AppendLeadConversation() method.
• Added the following new fields to local_services_verification_artifact: local_services_verification_artifact.insurance_verification_artifact.expiration_date_time and local_services_verification_artifact.license_verification_artifact.expiration_date_time

Reporting

• You can now select only fields related to one linked product when querying product_link. Selecting multiple fields of several linked products will throw QueryError.PROHIBITED_FIELD_COMBINATION_IN_SELECT_CLAUSE. For example, product_link.advertising_partner.customer and product_link.data_partner.data_partner_id cannot be selected in the same query.
• Passing a page_size to GoogleAdsService.Search will result in a RequestError.PAGE_SIZE_NOT_SUPPORTED error.

Shopping

• Added a new report shopping_product, which corresponds to the Products page of the Google Ads UI. It supports returning data related to the current state of products from Google Merchant Center accounts linked to a Google Ads account.
• You can filter metrics from the shopping_product report using segments.date when using GoogleAdsService.Search or GoogleAdsService.SearchStream. Segmentation by date is not permitted and will return a ShoppingProductError.UNSUPPORTED_DATE_SEGMENTATION error.

Unified Goals

• Added UserListCustomerTypeService.MutateUserListCustomerTypes() to configure audience customer types.
• Removed CustomerLifecycleGoal.lifecycle_goal_customer_definition_settings. To configure audience settings of customer lifecycle goals, use UserListCustomerTypeService.MutateUserListCustomerTypes() instead.
• Attach or unattach a user list by setting UserListCustomerType.customer_type_category to UserListCustomerTypeCategory.PURCHASERS to include it into or exclude it from an existing customer definition for customer lifecycle goals, respectively. Visit segment your audiences for more details.

Videos

• Added the following values to ContentLabelType. You can exclude these ContentLabelTypes at the customer level: BRAND_SUITABILITY_CONTENT_FOR_FAMILIES, BRAND_SUITABILITY_GAMES_FIGHTING, BRAND_SUITABILITY_GAMES_MATURE, BRAND_SUITABILITY_HEALTH_SENSITIVE, BRAND_SUITABILITY_HEALTH_SOURCE_UNDETERMINED, BRAND_SUITABILITY_NEWS_RECENT, BRAND_SUITABILITY_NEWS_SENSITIVE, BRAND_SUITABILITY_NEWS_SOURCE_NOT_FEATURED, BRAND_SUITABILITY_POLITICS, BRAND_SUITABILITY_RELIGION
• Added AdVideoAsset.ad_video_asset_info to support inventory preferences for video assets when creating DemandGenVideoResponsiveAdInfo.
• (Allowlisted accounts only) Made Campaign.video_brand_safety_suitability mutable.

Forum discussion at X.