Sunsetted versions

AI-generated Key Takeaways

outlined_flag

• The Google Ads API has undergone significant updates across various versions, introducing new features and refining existing ones in areas like account management, advertising formats, bidding strategies, campaign types, reporting, and targeting.

• Recent versions like v18 bring enhancements to account linking for partnership ads, demographic exclusion for optimized targeting, automatic asset generation options, and expanded reporting metrics for video views and store visits.

• Performance Max campaigns continue to evolve with support for brand guidelines and more detailed placement reporting, while planning tools now offer insights into YouTube Creator data and generative AI-driven audience suggestions.

• The API has transitioned towards asset-based management for various ad formats and extensions, replacing older methods and services like MediaFile and Feed-based extensions.

• Reporting and metrics have been consistently updated across versions, providing more granular data on user engagement, conversions (including SKAdNetwork and offline uploads), shopping performance, and unique users.

For archival purposes, so links on this page might not work.

v18 (2024-10-16)

The following new features and updates were added in v18.

Account Management

:

• (For allowlisted accounts only) Added DataLinkService.CreateDataLink, which allows linking a Google Ads account to creator videos hosted on the creator's YouTube channel. Video linking enables the Google Ads account to run partnership ads using creator videos.

Ad Groups

• Added AdGroup.exclude_demographic_expansion, which lets you exclude demographics from being expanded when optimized_targeting_enabled is true, a feature that was previously only supported for Demand Gen.

Ads

• Added AdGroupAd.ad_group_ad_asset_automation_settings, which allows opting ads into or out of automatic asset generation.
• Added the following values to AssetAutomationType:
  • GENERATE_VERTICAL_YOUTUBE_VIDEOS
  • GENERATE_SHORTER_YOUTUBE_VIDEOS
• Added AdNetworkType.GOOGLE_OWNED_CHANNELS, which is used by ads that serve on Google-owned channels such as YouTube, Gmail, and the Discover feed.

Assets

• Renamed AssetType.DISCOVERY_CAROUSEL_CARD to AssetType.DEMAND_GEN_CAROUSEL_CARD.

Campaigns

• Added metrics.store_visits_last_click_model_attributed_conversions, which returns the number of store visits attributed by the last click model of a campaign.
• Added the following video view-related metrics for a campaign:
  • metrics.video_view_rate_in_feed
  • metrics.video_view_rate_in_stream
  • metrics.video_view_rate_shorts
• Added metrics.results_conversions_purchase, which returns conversion purchases for the unified goals results of a campaign.
• Changed the default value of DemandGenCampaignSettings.upgraded_targeting from false to true.

Criterion

• Added content_criterion_view, which returns performance metrics of targeted contents, such as keywords, placements and topics, for Display, Demand Gen and Video campaigns.

Hotel & Travel

• Support for Travel Feeds in Search Ads
  • Added ClickType.TRAVEL_ASSETS to allow segmentation of metrics of Travel Feeds in Search Ads.
  • Added AssetSetType.TRAVEL_FEED which can be used to opt-in and opt-out of using Travel Feed in Search Ads.
• (For allowlisted accounts only) Added travel itinerary as a new conversion value rule with the following new fields and values:
  • ConversionValueRule.itinerary_condition with ValueRuleItineraryCondition, which allows for specifying an advance booking window, an itinerary length, and a travel start days of week
  • ConversionValueRulePrimaryDimensionEnum.ITINERARY
  • ValueRuleSetDimension.ITINERARY
• Added the following segments for campaign and ad_group reports to allow for segmenting performance data based on specific destinations (cities, countries and regions) for Hotel and Search campaigns:
  • segments.travel_destination_city
  • segments.travel_destination_country
  • segments.travel_destination_region

Local Services

• PhoneCallDetails.call_recording_url will be empty, instead of providing an invalid URL if the call recording doesn't exist for the given Local Services lead conversation.
• Added CategoryBid.target_cpa_bid_micro which allows for setting target CPA for a category through Campaign.local_services_campaign_settings.

Performance Max

• Support for brand guidelines
  • Added Campaign.brand_guidelines_enabled, which shows whether brand guidelines are enabled for a given Performance Max campaign. If enabled, assets with field_type set to BUSINESS_NAME, LOGO, LANDSCAPE_LOGO must be linked as CampaignAsset resources instead of AssetGroupAsset resources.
  • Added CampaignError.REQUIRED_BUSINESS_NAME_ASSET_NOT_LINKED and CampaignError.REQUIRED_LOGO_ASSET_NOT_LINKED errors, which indicate that Performance Max campaigns with brand guidelines enabled don't have the required CampaignAsset resources linked to the campaign.
  • When brand guidelines are enabled, at least one asset with field_type set to BUSINESS_NAME and at least one with LOGO must be linked to the campaign as CampaignAsset resources. Performance Max campaigns for online sales with a product feed must meet this requirement only when there are assets that are linked to the campaign's asset groups.
  • Added the following values to AssetLinkError:
  • BRAND_ASSETS_NOT_LINKED_AT_ASSET_GROUP_LEVEL, which is thrown when attempting to link brand assets to campaigns as CampaignAsset resources instead of AssetGroupAsset resources in Performance Max campaigns with brand guidelines not enabled.
  • BRAND_ASSETS_NOT_LINKED_AT_CAMPAIGN_LEVEL error, which is thrown when attempting to link brand assets to campaigns as AssetGroupAsset resources instead of CampaignAsset resources in Performance Max campaigns with brand guidelines enabled.
• Added performance_max_placement_view, which returns impressions of the placements where Performance Max ads served.
• Added AssetGroupListingGroupFilterError.TREE_WAS_INVALID_BEFORE_MUTATION

Planning

• (For allowlisted accounts only) Added a new service with the method ContentCreatorInsightsService.GenerateCreatorInsights, which allows users to explore insights about top YouTube Creators. This allows customers to search for creators given an audience targeting and content targeting combination or creator insights given a list of YouTube Channel IDs.
• Updates to AudienceInsightsService.GenerateSuggestedTargetingInsights:
  • Moved audience, baseline_audience and data_month into audience_definition.
  • Added audience_description to generate targeting suggestions from a free form text description using generative AI.
• Added AudienceInsightsService.GenerateTargetingSuggestionMetrics, which returns potential reach metrics for given audience targeting combinations.

Recommendations

• RecommendationService.GenerateRecommendations can now be used to generate recommendations about optimized budget suggestions during campaign construction, by including the CAMPAIGN_BUDGET recommendation type in GenerateRecommendationsRequest.recommendation_types[]. This works for Performance Max and Search campaigns.

Reporting

• Replaced the summary_row_setting and return_total_results_count fields of SearchGoogleAdsRequest with the search_settings field, whose type is SearchSettings with the following fields:
  • omit_results
  • return_summary_row
  • return_total_results_count
• Added the following new metrics about general invalid clicks, such as those generated by bots or crawlers, those having irregular patterns. They can be queried with the campaign report.
  • metrics.general_invalid_clicks
  • metrics.general_invalid_click_rate
• Added the following values to QuotaError:
  • EXCESSIVE_LONG_TERM_QUERY_RESOURCE_CONSUMPTION

v17.1.0 (2024-08-07)

The following new features and updates were added in v17_1.

Assets

• AdGroupAdService.RemoveAutomaticallyCreatedAssets() lets you remove specified automatically created assets linked to Responsive Search Ads.

Audiences

• New enum values in UserListCustomerTypeCategory:
  • LOYALTY_TIER_1_MEMBERS
  • LOYALTY_TIER_2_MEMBERS
  • LOYALTY_TIER_3_MEMBERS
  • LOYALTY_TIER_4_MEMBERS
  • LOYALTY_TIER_5_MEMBERS
  • LOYALTY_TIER_6_MEMBERS
  • LOYALTY_TIER_7_MEMBERS

Campaigns

• ShareablePreviewService.GenerateShareablePreviews() generates the URLs shareable_preview_url in the response for shareable ad previews for enabled and paused asset groups.
  • The expiration_date_time field indicates the expiration date of the URLs in the response.
  • If an error occurs, the method will return partial_failure_error instead of the URLs.

Change History

• New change status resource type: ASSET_GROUP.

Conversions

• New segment field for SKAdNetwork version: segments.sk_ad_network_version
• offline_conversion_upload_conversion_action_summary, which exposes conversion upload diagnostics at the conversion action level.
• The following metrics are added to the offline diagnostics reports to convey the number of uploaded conversions that are still being processed:
  • offline_conversion_upload_client_summary
  • pending_event_count
  • pending_rate
  • offline_conversion_upload_conversion_action_summary:
  • pending_count

Planning

• AudienceInsights.GenerateAudienceOverlapInsights(), which accepts an input primary attribute and a collection of audience attributes, and returns the estimates of the overlap of potential YouTube reach between the primary attribute and the audience attributes.

Reporting

• Support for segmenting per_store_view based on segments.date

Videos

• Support for retrieving information related to the following standard bidding strategies for video campaigns using reports, such as, ad_group, campaign:
  • Campaign.fixed_cpm (Fixed CPM (cost per thousand impression))
  • Campaign.target_cpv (Target CPV (cost per view))
• Campaign.video_campaign_settings which lets you determine on which inventories the video ads can be shown, using the following report fields:
  • campaign.video_campaign_settings.video_ad_inventory_control.allow_in_feed
  • campaign.video_campaign_settings.video_ad_inventory_control.allow_in_stream
  • campaign.video_campaign_settings.video_ad_inventory_control.allow_shorts
• segments.ad_format_type which lets you segment the following reports based on the video ad format type:
  • ad_group
  • ad_group_ad
  • ad_group_ad_asset_view
  • campaign
  • customer

v17 (2024-06-05)

The following features and changes were added in v17.

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
  • 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.
  • 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
  • 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
  • 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 un-attach 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.

v16.1.0 (2024-04-24)

The following features and changes were added in v16.1.

Account Management

• CustomerNegativeCriterion.ip_block which supports adding an IP as a negative criterion at the customer level.
• New enum value: ProductLinkError.LINK_EXISTS.
• New enum value: ProductLinkInvitationError.CUSTOMER_NOT_PERMITTED_TO_CREATE_INVITATION.

Assets

• Support for assets related to Demand Gen to ad_group_ad_asset_view and asset_field_type_view.
• New enum value: AssetFieldType.DISCOVERY_CAROUSEL_CARD.

Audiences

• New enum value: ResourceLimitType.LOOKALIKE_USER_LISTS_PER_CUSTOMER which limits the number of lookalike user lists a customer can have to 1000.

Campaigns

• Support for returning Target ROAS campaign bid simulations for App campaigns using the campaign_simulation report.
• New enum value: CampaignError.DYNAMIC_TEXT_ASSET_CANNOT_OPT_OUT_WITH_FINAL_URL_EXPANSION_OPT_IN.
• New enum value: AdGroupPrimaryStatusReason.AD_GROUP_PAUSED_DUE_TO_LOW_ACTIVITY.
• New enum value: CampaignCriterionError.CANNOT_REMOVE_ALL_LOCATIONS_DUE_TO_TOO_MANY_COUNTRY_EXCLUSIONS.

Conversions

• SkAdNetworkConversionValueSchema.postback_mappings which supports SKAdNetwork 4.0 features.
• Added support for warnings for CustomerSkAdNetworkConversionValueSchemaService as MutateCustomerSkAdNetworkConversionValueSchemaRequest.enable_warnings. When set to true, any non-blocking errors pertaining to operation failures will be returned as MutateCustomerSkAdNetworkConversionValueSchemaResponse.warning.
• New enum values in CustomerSkAdNetworkConversionValueSchemaError:
  • INVALID_EVENT_COUNTER
  • INVALID_EVENT_NAME

Criteria

• New fields in BrandInfo:
  • display_name
  • primary_url
  • rejection_reason
  • status
• New enum: BrandRequestRejectionReason.
• New enum value: CriterionType.LIFE_EVENT.

Experiments

• New enum value: ExperimentError.INVALID_DURATION_FOR_AN_EXPERIMENT.

Local Services

• local_services_lead.credit_details.credit_state and local_services_lead.credit_details.credit_state_last_update_date_time which returns the state of credit and the timestamp when the credit state was updated, respectively.
• local_services_lead_conversation.message_details.attachment_urls which returns the URLs that can be used to download the contents of the attachment.

Videos

• customer.video_brand_safety_suitability and BrandSafetySuitability which support retrieving video brand safety suitability at the customer level.
• New enum value: VideoCampaignError.MUTATE_REQUIRES_RESERVATION.

v16 (2024-02-21)

The following features and changes were added in v16.

Account Management

• Migrated advertising_partner from AccountLink to ProductLink and ProductLinkInvitation.
• Removed data_partner and google_ads from AccountLink.
• Added IdentityVerificationService to manage advertiser verification.
  • StartIdentityVerification() is used to start a verification session using the provided verification_program. It creates a new verification session and returns an empty response for a successfully created verification.
    • Added IdentityVerificationProgram.ADVERTISER_IDENTITY_VERIFICATION.
  • GetIdentityVerification() can be used for retrieving verification information, which returns several objects of IdentityVerification. Each IdentityVerification includes:
    • verification_program which is the identity verification program type
    • identity_verification_requirement that contains details related to the deadline by which the advertiser should finish verification
    • verification_progress that contains details related to the verification session including:
      • program_status represents the current status of this verification session
      • action_url directs the customer to a URL to complete the verification.
      • invitation_link_expiration_time represents the expiration date for the action_url
  • Enums:
    • IdentityVerificationProgram
    • IdentityVerificationProgramStatus
  • Errors:
    • IdentityVerificationError
• Added AuthorizationError.ACTION_NOT_PERMITTED_FOR_SUSPENDED_ACCOUNT.

Assets

• Changes to asset_group:
  • Added support for time-related segments, such as segments.year and segments.month.
  • Made campaign an attributed resource instead of segmenting resource.

Campaigns

• Changes to Demand Gen campaigns:
  • Added support for setting Campaign.shopping_setting to an existing Demand Gen campaign.
  • Added ShoppingSetting.disable_product_feed to disable the optional product feed of Demand Gen campaigns.
  • Added Ad.demand_gen_product_ad and the corresponding DemandGenProductAdInfo, available to Demand Gen campaigns with a non-null Campaign.shopping_setting.
• Added to following fields to AdGroup to show whether the ad group is serving or the reasons why it's not serving:
  • primary_status
  • primary_status_reasons
• Added to following fields to AdGroupAd to show whether the ad group ad is serving or the reasons why it's not serving:
  • primary_status
  • primary_status_reasons
• Added the following values to AdGroupError:
  • CANNOT_ADD_AD_GROUP_FOR_CAMPAIGN_TYPE
  • INVALID_STATUS

Experiment

• Added Experiment.sync_enabled to specify if sync should be enabled in the experiment. With sync enabled, changes made to the original campaign while your experiment is running, are automatically copied to the experiment campaign.
• Added ExperimentError.CANNOT_ENABLE_SYNC_FOR_UNSUPPORTED_EXPERIMENT_TYPE.
• Added CampaignError.CANNOT_MODIFY_TEXT_ASSET_AUTOMATION_WITH_ENABLED_TRIAL.

Hotel & Travel

• Added the following fields to ListingDimensionInfo for a Things to do ad to enable creating listing groups based on the state and city where the travel activity is available:
  • activity_state
  • activity_city
• Added support for the following segments to travel_activity_performance_view:
  • segments.activity_city
  • segments.activity_country
  • segments.activity_state

Local Services

• Added LocalServicesVerificationArtifact.business_registration_check_verification_artifact and BusinessRegistrationCheckArtifact to allow advertisers to monitor the progress of the business registration verification process.
• Added a new resource local_services_employee to allow advertisers to retrieve the employee information they've added.

Planning

• Removed score from AudienceInsightsAttributeMetadata.

Recommendations

• Added RecommendationService.GenerateRecommendations() which returns recommendations based on the specified settings, such as recommendation types and advertising channel types. This is particularly helpful during campaign construction.
• Added RecommendationMetrics.conversions_value.
• Recommended keywords with unset keyword match type now have recommended_match_type set to UNSPECIFIED instead of UNKNOWN.
• Added the following types of recommendations:
  • MAXIMIZE_CONVERSION_VALUE_OPT_IN which recommends opting in to the Maximize conversion value bidding strategy
  • IMPROVE_GOOGLE_TAG_COVERAGE which recommends deploying Google Tag on more pages
  • PERFORMANCE_MAX_FINAL_URL_OPT_IN which recommends turning on final URL expansion for your Performance Max campaigns
  • REFRESH_CUSTOMER_MATCH_LIST which recommends updating a customer list that hasn't been updated in the last 90 days
  • CUSTOM_AUDIENCE_OPT_IN which recommends creating a custom audience
  • LEAD_FORM_ASSET which recommends adding lead form assets at the campaign or customer level
  • IMPROVE_DEMAND_GEN_AD_STRENGTH which recommends improving ad strength on Demand Gen campaigns

Shopping

• Added CampaignError.CANNOT_LINK_TO_COMPARISON_SHOPPING_SERVICE_ACCOUNT and CampaignError.CANNOT_TARGET_NETWORK_FOR_COMPARISON_SHOPPING_SERVICE_LINKED_ACCOUNTS in order to provide more detailed errors for Shopping campaigns linked to a Comparison Shopping Service Center account.
• Added the following values to AssetGroupListingGroupFilterError:
  • DIMENSION_TYPE_NOT_ALLOWED
  • DUPLICATE_WEBPAGE_FILTER_UNDER_ASSET_GROUP
  • FILTER_EXCLUSION_NOT_ALLOWED
  • LISTING_SOURCE_NOT_ALLOWED
  • MULTIPLE_LISTING_SOURCES
  • MULTIPLE_WEBPAGE_CONDITION_TYPES_NOT_ALLOWED
  • MULTIPLE_WEBPAGE_TYPES_PER_ASSET_GROUP
  • PAGE_FEED_FILTER_HAS_PARENT

Lifecycle Goals

• Added update to CustomerLifecycleGoalOperation and CampaignLifecycleGoalOperation to make these operation types consistent with other operation types in the API.

v15 (2023-10-18)

The following new features and updates were introduced in v15.

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. Starting on March 6, 2024 if consent is missing for EEA users, then the consent value is determined as not consented. Data from unconsented EEA users won't be processed and cannot be used for ad personalization using Customer Match. Check out our Customer Match guide for more details.
• For Store Sales, added UserData.consent to support providing a consent. Check out our Store Sales guide for more details. If you are using Customer Match with store sales, review the FAQ for additional information.
• 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
  • ASSET_GROUPS_PAUSED

Conversions

• Added CallConversion.consent and ClickConversion.consent to support providing a consent. Check out our call conversions guide and click conversions guide for more details.
• 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 models 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. ## v14.1.0 (2023-08-09)

The following new features and updates were introduced in v14.1.

Account Management

• Customer.customer_agreement_setting which shows if the customer has accepted the lead form term of service

Assets

• New fields in AssetGroup to show whether the asset group is serving or the reasons why it's not serving:
  • primary_status
  • primary_status_reasons
• New fields in AssetGroupAsset to show whether the asset group asset is serving or the reasons why it's not serving:
  • primary_status
  • primary_status_details
  • primary_status_reasons
• New values in the CallToActionType enum:
  • BUY_NOW
  • DONATE_NOW
  • ORDER_NOW
  • PLAY_NOW
  • SEE_MORE
  • START_NOW
  • VISIT_SITE
  • WATCH_NOW
• New values in the AssetLinkError enum:
  • CUSTOMER_NOT_VERIFIED
  • UNSUPPORTED_CALL_TO_ACTION
  • PAGE_FEED_INVALID_LABEL_TEXT

Billing

• New fields in Invoice and AccountSummary:
  • export_charge_subtotal_amount_micros
  • export_charge_tax_amount_micros
  • export_charge_total_amount_micros

Campaigns

• New values in the CampaignPrimaryStatusReason enum:

  • HAS_ASSET_GROUPS_DISAPPROVED
  • HAS_ASSET_GROUPS_LIMITED_BY_POLICY
  • MOST_ASSET_GROUPS_UNDER_REVIEW

• (Allowlisted accounts only) DiscoveryCampaignSettings with upgraded_targeting:

  • When upgraded_targeting is set to true, you can add a location and a language as an ad group criterion

Criteria

• New enum value: CriterionError.INVALID_DETAILED_DEMOGRAPHIC

• (Allowlisted accounts only) Support for adding LanguageInfo and LocationInfo as an AdGroupCriterion:

  • This is available only for a Discovery campaign with upgraded targeting enabled

Experiments

• New values in the ExperimentError enum:
  • DUPLICATE_EXPERIMENT_CAMPAIGN_NAME
  • CANNOT_REMOVE_IN_CREATION_EXPERIMENT
  • CANNOT_ADD_CAMPAIGN_WITH_DEPRECATED_AD_TYPES

Recommendations

• New types of recommendations:
  • PerformanceMaxOptInRecommendation which recommends creating the first Performance Max campaign in the account
  • ImprovePerformanceMaxAdStrengthRecommendation which recommends improving the asset group's strength of a Performance Max campaign
  • MigrateDynamicSearchAdsCampaignToPerformanceMaxRecommendation which recommends migrating a Dynamic Search Ad campaign to Performance Max

Reporting

• New metrics and segments about new versus returning customers:
  • metrics.new_customer_lifetime_value
  • metrics.all_new_customer_lifetime_value
  • segments.new_versus_returning_customers
• New customer_search_term_insight and campaign_search_term_insight views:
  • metrics.search_volume shows the volume range for a search term insight category

Shopping

• New fields for listing groups:
  • ListingGroupInfo.path
  • AssetGroupListingGroupFilter.path
• New field: ShoppingSetting.advertising_partner_ids
• New values in the CampaignError enum:
  • NOT_LINKED_ADVERTISING_PARTNER
  • INVALID_NUMBER_OF_ADVERTISING_PARTNER_IDS

Videos

• (Allowlisted accounts only) AdType.DISCOVERY_VIDEO_RESPONSIVE_AD and its corresponding DiscoveryVideoResponsiveAdInfo

v14 (2023-06-07)

The following new features and updates were introduced in v14.

Campaigns

• Added CampaignBudgetError.BUDGET_AMOUNT_MUST_BE_UNSET_FOR_CUSTOM_BUDGET_PERIOD

Conversions

• Added support for identifying Google Analytics conversions and determining whether a conversion is imported from a Universal Analytics or GA4 property:

  • Added the following values to ConversionActionType:
    • UNIVERSAL_ANALYTICS_GOAL
    • UNIVERSAL_ANALYTICS_TRANSACTION
    • GOOGLE_ANALYTICS_4_CUSTOM
    • GOOGLE_ANALYTICS_4_PURCHASE
  • Added ConversionAction.google_analytics_4_settings

• Added Customer.offline_conversion_client_summaries, which summarizes the status and diagnostic information of the customer's offline conversion uploads and adjustments.

  • Enums
    • OfflineEventUploadClient:
      • GOOGLE_ADS_API
      • GOOGLE_ADS_WEB_CLIENT
      • ADS_DATA_CONNECTOR
    • OfflineConversionDiagnosticStatus:
      • EXCELLENT
      • GOOD
      • NEEDS_ATTENTION
      • NO_RECENT_UPLOAD

• Added job_id to the responses returned by ConversionAdjustmentUploadService.UploadConversionAdjustments and ConversionUploadService.UploadClickConversions for associating a response to an OfflineConversionUploadSummary.job_id.

Criteria

• Added support for retrieving, creating and updating account-level negative keywords:

  • Fields:
    • CustomerNegativeCriterion.negative_keyword_list
  • Enums:
    • CriterionType.NEGATIVE_KEYWORD_LIST
    • SharedSetType.ACCOUNT_LEVEL_NEGATIVE_KEYWORDS
    • ResourceLimitType
      • SHARED_SETS_PER_ACCOUNT_FOR_ACCOUNT_LEVEL_NEGATIVE_KEYWORDS
      • ACCOUNT_LEVEL_NEGATIVE_KEYWORDS_PER_SHARED_SET
  • Errors:
    • CriterionError
      • NEGATIVE_KEYWORD_SHARED_SET_DOES_NOT_EXIST
      • CANNOT_ADD_REMOVED_NEGATIVE_KEYWORD_SHARED_SET
      • CANNOT_HAVE_MULTIPLE_NEGATIVE_KEYWORD_LIST_PER_ACCOUNT
      • CUSTOMER_CANNOT_ADD_CRITERION_OF_THIS_TYPE

• Added CriterionError.CANNOT_TARGET_SIMILAR_USER_LIST

Hotel Ads

• Renamed SuggestTravelAssetsRequest.place_id to SuggestTravelAssetsRequest.place_ids

Planning

• Removed the following methods from KeywordPlanService:
  • GenerateForecastCurve
  • GenerateForecastMetrics
  • GenerateForecastTimeSeries
  • GenerateHistoricalMetrics
• Added KeywordPlanIdeaService.GenerateKeywordForecastMetrics to support generating keyword campaign forecast metrics without the need of creating a keyword plan first.
• Removed support for retrieving the campaign_criterion_simulation report
• Added support for YOUTUBE_DYNAMIC_LINEUP as a dimension in AudienceInsightsService.ListAudienceInsightsAttributes.
• Added DynamicLineupAttributeMetadata.sample_channels, used in GenerateAudienceCompositionInsights responses to provide sample channels within lineups.

Recommendations

• Added DynamicImageExtensionOptInRecommendation which recommends enabling dynamic image extensions on the account
• Added LowerTargetRoasRecommendation which recommends lowering target ROAS
• Added RaiseTargetCpaRecommendation which recommends raising target CPA
• Added ResponsiveSearchAdAssetRecommendation.current_ad

Reporting

• Added the following values to ServedAssetFieldType, which are available from ad_group_ad_asset_view.pinned_field:
  • SITELINK
  • CALL
  • MOBILE_APP
  • CALLOUT
  • STRUCTURED_SNIPPET
  • PRICE
  • PROMOTION
  • AD_IMAGE
  • LEAD_FORM
  • BUSINESS_LOGO

v13.1.0 (2023-04-26)

The following new features and updates were introduced in v13.1.

Assets

• LeadFormField.has_location_answer supports displaying locations from the location assets associated with campaigns or a customer with a lead form.

  Accompanying errors:

  • AssetError.LEAD_FORM_LOCATION_ANSWER_TYPE_DISALLOWED
  • AssetLinkError.CANNOT_LINK_LOCATION_LEAD_FORM_WITHOUT_LOCATION_ASSET

• New values in the AssetGroupError enum:

  • PATH1_REQUIRED_WHEN_PATH2_IS_SET
  • SHORT_DESCRIPTION_REQUIRED
  • FINAL_URL_REQUIRED
  • FINAL_URL_CONTAINS_INVALID_DOMAIN_NAME
  • AD_CUSTOMIZER_NOT_SUPPORTED
  • CANNOT_MUTATE_ASSET_GROUP_FOR_REMOVED_CAMPAIGN

Audiences

• New values in the UserListError enum:
  • APP_ID_NOT_ALLOWED
  • CANNOT_MUTATE_SYSTEM_LIST
  • MOBILE_APP_IS_SENSITIVE

Campaigns

• Support for returning campaign-level bid simulations for Performance Max using campaign_simulation.
• (Allowlisted accounts only) Campaign.listing_type and ListingType for Performance Max campaigns. This field is replacing ShoppingSetting.use_vehicles_inventory, which will be used only for Smart Shopping campaigns.

Conversions

• CustomerSkAdNetworkConversionValueSchemaService.MutateCustomerSkAdNetworkConversionValueSchema enables advertisers to define SKAdNetwork conversion value schemas for iOS app campaigns.
• New enum value: CustomConversionGoalError.NON_BIDDABLE_CONVERSION_ACTION_NOT_ELIGIBLE_FOR_CUSTOM_GOAL

Planning

• New fields in the following request and response objects of AudienceInsightsService:
  • GenerateAudienceCompositionInsightsRequest.baseline_audience supports specifying the baseline audience to which the audience of interest is being compared.
  • ListInsightsEligibleDatesResponse.last_thirty_days supports retrieving the current default date range used in GenerateAudienceCompositionInsights requests.

Recommendations

• New types of recommendation for Shopping campaigns and Google Merchant Center:
  • shopping_add_age_group_recommendation
  • shopping_add_color_recommendation
  • shopping_add_gender_recommendation
  • shopping_add_gtin_recommendation
  • shopping_add_more_identifiers_recommendation
  • shopping_add_size_recommendation
  • shopping_add_products_to_campaign_recommendation
  • shopping_fix_disapproved_products_recommendation
  • shopping_target_all_offers_recommendation
  • shopping_fix_suspended_merchant_center_account_recommendation
  • shopping_fix_merchant_center_account_suspension_warning_recommendation
  • shopping_migrate_regular_shopping_campaign_offers_to_performance_max_recommendation

Reporting

• New metrics:
  • metrics.average_target_cpa_micros to show the average target CPA.
  • metrics.average_target_roas to show the average target ROAS.

v13 (2023-02-15)

The following new features and updates were introduced in v13.

Account Management

• Added ProductLinkService to support adding and removing a link between a Google Ads account and another product. This is similar to the Linked accounts view in the Google Ads UI. In this version, only Customer Match data partner linking is supported.

Assets

• Added the following fields to Customer to track the migration status of location and image assets:

  • location_asset_auto_migration_done
  • image_asset_auto_migration_done
  • location_asset_auto_migration_done_time
  • image_asset_auto_migration_done_time

• Added the following fields to CustomerAsset, CampaignAsset, AdGroupAsset:

  • primary_status
  • primary_status_details
  • primary_status_reasons

• Added Asset.field_type_policy_summaries to return information about policy summaries for each field type.

• Asset field types

  • Added AssetFieldType.BUSINESS_LOGO.
  • Added support for setting CampaignAsset.field_type to the following values:
    • AssetFieldType.BUSINESS_NAME
    • AssetFieldType.BUSINESS_LOGO

• Added INVALID_EXCLUDED_PARENT_ASSET_SET_TYPE to

  • AdGroupError
  • CampaignError

• Added the following fields to AssetSetError:

  • OAUTH_INFO_INVALID
  • OAUTH_INFO_MISSING
  • CANNOT_DELETE_AS_ENABLED_LINKAGES_EXIST

Audiences

• Removed CombinedRuleUserListInfo and ExpressionRuleUserListInfo and their references from RuleBasedUserListInfo. Use FlexibleUserListInfo instead.
• Added QualifyingQuestion and qualifying_question to support returning details about qualifying questions of lead form assets. When advertisers suggest a qualifying question, it'll be reviewed and approved before being used in the lead forms.

Batch Jobs

• Added BatchJobMetadata.execution_limit_seconds to return the limit of execution in seconds. Batch jobs will be canceled if their execution time is longer than specified in this field.

Billing

• Added InvalidActivitySummary to allow for returning more details about the invalid activity for the invoice.
• Added AccountBudgetProposalError.CANCELED_BILLING_SETUP.

Campaigns

• Added SmartCampaignSettingService.GetSmartCampaignStatus for retrieving a more aggregated view of assets belonging to the Smart campaign. This should be preferred over other status fields—for example, Campaign.primary_status or Campaign.primary_status_reasons for Smart campaigns.
• Replaced AdGroup.explorer_auto_optimizer_setting with AdGroup.optimized_targeting_enabled to support optimized targeting. This is for the following AdvertisingChannelType: DISPLAY, VIDEO, DISCOVERY. This field is for allowlisted customers only.
• Added several new enum values to CampaignError:
  • AVERAGE_DAILY_SPEND_TOO_HIGH
  • CANNOT_ATTACH_TO_REMOVED_CAMPAIGN_GROUP
  • CANNOT_ATTACH_TO_BIDDING_STRATEGY
  • CANNOT_CHANGE_BUDGET_PERIOD
  • CANNOT_CREATE_DRAFT_CAMPAIGN
  • CANNOT_CREATE_MORE_THAN_ONE_DRAFT_CAMPAIGN
  • NOT_ENOUGH_CONVERSIONS
  • CANNOT_SET_MORE_THAN_ONE_CONVERSION_ACTION
  • NOT_COMPATIBLE_WITH_BUDGET_TYPE
  • NOT_COMPATIBLE_WITH_UPLOAD_CLICKS_CONVERSION
  • TRIAL_MUST_USE_SAME_BUDGET_AS_BASE
  • INVALID_EXCLUDED_PARENT_ASSET_SET_TYPE

Conversions

• ConversionUploadError.CUSTOMER_NOT_ACCEPTED_CUSTOMER_DATA_TERMS will be returned if you upload a ClickConversion with user_identifiers set using ConversionUploadService.UploadClickConversion, but have not accepted the customer data terms.
• ConversionUploadError.CLICK_CONVERSION_ALREADY_EXISTS will be returned if you try to upload the same combination of gbraid, conversion_action, and conversion_date_time on different days.
• ConversionUploadError.CUSTOMER_NOT_ENABLED_ENHANCED_CONVERSIONS_FOR_LEADS will be returned if you haven't followed the setup instructions before using enhanced conversions for leads.
• Added ConversionActionType.WEBPAGE_CODELESS to represent conversions created from website events.

Criteria

• Added CampaignCriterion.local_service_id and LocalServiceIdInfo to allow for adding and removing services an advertiser serves to a Local Services Campaign.
  • CampaignCriterionError.AT_LEAST_ONE_LOCAL_SERVICE_ID_CRITERION_REQUIRED_FOR_LOCAL_SERVICES_CAMPAIGN will be returned if you attempt to remove the last campaign criterion that contains local_service_id from a Local Services Campaign.
  • CampaignCriterionError.LOCAL_SERVICE_ID_NOT_FOUND_FOR_CATEGORY will be returned if you attempt to add a campaign criterion that contains local_service_id that is invalid for the category of your Local Service campaign. You can get information about the category by fetching campaign.local_services_campaign_settings.category_bids.

Errors

• Starting in v13, the error codes returned for some invalid operations have changed for the following fields.

  Previous error	New error
  BiddingError.INVALID_BID	FieldError.FIELD_CANNOT_BE_CLEARED
  BiddingError.CANNOT_ATTACH_BIDDING_STRATEGY_TO_CAMPAIGN	CampaignError.CANNOT_ATTACH_TO_BIDDING_STRATEGY
  DistinctError.DUPLICATE_ELEMENT	MutateError.ID_EXISTS_IN_MULTIPLE_MUTATES
  OperationAccessDeniedError.OPERATION_NOT_PERMITTED_FOR_CAMPAIGN_TYPE	ContextError.OPERATION_NOT_PERMITTED_FOR_CONTEXT
  BiddingError.BID_TOO_SMALL	RangeError.TOO_LOW
  OperationAccessDeniedError.CREATE_OPERATION_NOT_PERMITTED	ContextError.OPERATION_NOT_PERMITTED_FOR_CONTEXT
  CampaignError.MISSING_SHOPPING_SETTING	FieldError.REQUIRED
  OperationAccessDeniedError.MUTATE_NOT_PERMITTED_FOR_CUSTOMER	MutateError.MUTATE_NOT_ALLOWED

Hotel & Travel

• Added support for Performance Max for travel goals with the following new fields, resources, and enums:
  • Fields
    • Campaign.hotel_property_asset_set
    • AssetSet.hotel_property_data and HotelPropertyData
    • Asset.hotel_property_asset and HotelPropertyAsset
  • Enums
    • Added HOTEL_PROPERTY to:
      • AssetSetType
      • AssetType
      • AssetFieldType
    • AssetGroupAssetError.HOTEL_PROPERTY_ASSET_NOT_LINKED_TO_CAMPAIGN
    • CampaignError.ASSET_SET_NOT_A_HOTEL_PROPERTY_ASSET_SET
    • CampaignError.HOTEL_PROPERTY_ASSET_SET_ONLY_FOR_PERFORMANCE_MAX_FOR_TRAVEL_GOALS
• Added TravelAssetSuggestionService to suggest required images and text assets (such as headlines, descriptions, long descriptions) to be used to create asset groups in Performance Max for travel goal campaigns.
• Allowlisted customers only: Added support for Things to do ads campaigns by adding the following new fields, resources, and enums:
  • Fields
    • Campaign.travel_campaign_settings and TravelCampaignSettings
    • Ad.travel_ad and TravelAdInfo
    • ListingDimensionInfo
      • activity_id and ActivityIdInfo
      • activity_rating and ActivityRatingInfo
      • activity_country and ActivityCountryInfo
  • Enums
    • For campaign creation
      • AdvertisingChannelType.TRAVEL
      • AdvertisingChannelSubType.TRAVEL_ACTIVITIES
    • For ad group creation
      • AdGroupType.TRAVEL_ADS
    • For ad creation
      • AdType.TRAVEL_AD
    • Errors
      • CampaignError.MISSING_TRAVEL_CUSTOMER_LINK
      • CampaignError.INVALID_TRAVEL_CUSTOMER_LINK
  • Reports
    • travel_performance_view
    • travel_activity_group_view

Recommendations

• The following feed-based recommendations are replaced with asset-based recommendations:
  • Recommendation.call_extension_recommendation replaced by Recommendation.call_asset_recommendation
  • Recommendation.callout_extension_recommendation replaced by Recommendation.callout_asset_recommendation
  • Recommendation.sitelink_extension_recommendation replaced by Recommendation.sitelink_asset_recommendation
• Added Recommendation.campaigns to show the campaigns targeted by the recommendation.
• Removed ResponsiveSearchAdAssetRecommendation.current_ad.

Shopping

• Removed ProductBiddingCategoryInfo.country_code.
• Added support for segments.product_feed_label in shopping_performance_view.

Video

• Removed PreferredContentInfo and its reference from AdGroupBidModifier.
• Added call-to-action fields for video bumper ads:
  • VideoBumperInStreamAdInfo.action_button_label
  • VideoBumperInStreamAdInfo.action_headline
• Added TargetCpm.target_frequency_goal and TargetCpmTargetFrequencyGoal to support providing additional details about the goal of the Target CPM bidding strategy.
• Added AdvertisingChannelSubType.VIDEO_REACH_TARGET_FREQUENCY.
• Added PlacementType.GOOGLE_PRODUCTS.

12.0.0 (2022-10-26)

The features and changes below were added in v12.

Account Management

• Added a new account link type, ADVERTISING_PARTNER for linking a customer account to another one. This is preparation for an upcoming feature in a following release.
• Added AccountLinkError.PERMISSION_DENIED for the case where a non-admin user tries to create an account link.

Ads

• Removed support for creating a new Gmail ad. Use Discovery campaigns instead.

Assets

• Added support for retrieving CustomLeadFormSubmissionField through LeadFormSubmissionData using GoogleAdsService.SearchStream or GoogleAdsService.Search.

• Added support for adding, updating, and removing CampaignAsset and AdGroupAsset with the field_type as AD_IMAGE (for allowlisted customers only).

  • You can retrieve stats for Image assets (asset_field_type_view.field_type = AD_IMAGE) using the asset_field_type_view report.

• The asset_set_asset report now supports metrics and segments.

• Added ad_group_ad_asset_view.pinned_field to allow filtering by a pinned asset.

• Added support for segment.conversion_action to the ad_group_ad_asset_view report.

• Added support for linking customers and ad groups with asset sets for test accounts only.

  • CustomerAssetSetService for adding/updating/removing CustomerAssetSet, which represents a link between a Customer and an AssetSet.

  • AdGroupAssetSetService for adding/updating/removing AdGroupAssetSet, which represents a link between an AdGroup and an AssetSet.

• Added support for mutating and fetching location assets for test accounts only.

  • Fields:

    • Added Asset.location_asset whose type is LocationAsset.
    • Added the following fields to AssetSet:
      • location_group_parent_asset_set_id
      • asset_set_source (oneof field)
        • location_set (use with CustomerAssetSet)
        • business_profile_location_group (use with CampaignAssetSet and AdGroupAssetSet)
        • chain_location_group (use with CampaignAssetSet and AdGroupAssetSet)
    • Added excluded_parent_asset_set_types to Campaign and AdGroup.

  • Enums:

    • Added AssetType.LOCATION.
    • Added the following values to AssetSetType:
      • LOCATION_SYNC
      • BUSINESS_PROFILE_DYNAMIC_LOCATION_GROUP
      • CHAIN_DYNAMIC_LOCATION_GROUP
      • STATIC_LOCATION_GROUP

  • Reports (available for all accounts):

    • per_store_view returns stats at the place ID level. There are no stats returned yet; this is a future feature that was added so you can begin building your implementation against it.
    • asset_set_type_view returns stats at the AssetSetType level, which currently only supports location asset set.

Audiences

• Added the following values to OfflineUserDataJobFailureReason:

  • HIGH_AVERAGE_TRANSACTION_VALUE
  • LOW_AVERAGE_TRANSACTION_VALUE
  • NEWLY_OBSERVED_CURRENCY_CODE

Bidding

• Added support for linked portfolio bidding strategies and campaign budget. Bidding strategies and campaign budgets can modify these links using bulk mutates:

  • BiddingStrategy.aligned_campaign_budget_id
  • CampaignBudget.aligned_bidding_strategy_id

Billing

• Added AccountSummary as Invoice.account_summaries[] for reporting reconciliation (for allowlisted customers only).
• Added BillingSetupError.TOO_MANY_BILLING_SETUPS_FOR_PAYMENTS_ACCOUNT.
• Added AccountBudgetProposalError.INVALID_MASTER_SERVICE_AGREEMENT.

Campaigns

• Changes in Smart campaigns:

  • Updated SmartCampaignSuggestService.SuggestKeywordThemes to generate more keyword theme suggestions for Smart campaigns and can suggest free-form keyword themes in some cases.
  • Improved error handling and added more user-facing error codes for SmartCampaignSuggestService.SuggestKeywordThemes.

• Removed support for creating new Smart Display campaigns. Existing Smart Display campaigns still serve as usual.

  • OperationAccessDeniedError.CREATE_OPERATION_NOT_PERMITTED is thrown if you try to create a new Smart Display campaign.

• Added the following fields to Campaign:

  • primary_status to provide insight into why a campaign is not serving or not serving optimally.
  • primary_status_reasons to provide reasons into why a campaign is not serving or not serving optimally. These reasons are aggregated to determine primary_status.

• Enabled adding and removing location targeting to Local Services campaigns except for proximity targeting.

  • Added the following errors to CampaignCriterionError for the Local service campaigns:
    • AT_LEAST_ONE_POSITIVE_LOCATION_REQUIRED_FOR_LOCAL_SERVICES_CAMPAIGN
    • CANNOT_ADD_OR_REMOVE_LOCATION_FOR_LOCAL_SERVICES_CAMPAIGN
    • CANNOT_TARGET_COUNTRY_FOR_LOCAL_SERVICES_CAMPAIGN
    • LOCATION_INVALID_FOR_LOCAL_SERVICES_CAMPAIGN
    • LOCATION_NOT_IN_HOME_COUNTRY_FOR_LOCAL_SERVICES_CAMPAIGN
    • LOCATION_NOT_LAUNCHED_FOR_LOCAL_SERVICES_CAMPAIGN

Conversions

• conversion_tracking_id will always be > 0 for all customers. Previously, this field could be 0 for customers who hadn't created any conversion actions before.
• Added debug_enabled for performing all checks and returning errors if found when uploading enhanced conversions.

Criteria

• Added the following asset set fields to LocationGroupInfo for test accounts:

  • enable_customer_level_location_asset_set
  • location_group_asset_sets

• Added the following values to CriterionError:

  • CANNOT_SET_ASSET_SET_FIELD_FOR_CUSTOMER
  • CANNOT_SET_ASSET_SETS_WITH_FEED_ITEM_SETS
  • CANNOT_SET_BOTH_ASSET_SET_AND_FEED
  • CANNOT_SET_FEED_OR_FEED_ITEM_SETS_FOR_CUSTOMER
  • CANNOT_SET_GEO_TARGET_CONSTANTS_WITH_ASSET_SETS
  • INVALID_LOCATION_GROUP_ASSET_SETS

Errors

• Error codes returned for some invalid operations have changed for the following fields.

  • BiddingStrategy.currency_code
  • BiddingStrategy.scheme
  • BiddingStrategy.type
  • TargetCpa.target_cpa_micros
  • TargetImpressionShare.cpc_bid_ceiling_micros
  • TargetSpend.target_spend_micros (deprecated)

Previous Error	New Error
BiddingError.BID_TOO_BIG	RangeError.TOO_HIGH
BiddingError.BID_TOO_SMALL	RangeError.TOO_LOW
FieldError.INVALID_VALUE	ContextError.OPERATION_NOT_PERMITTED_FOR_CONTEXT
BiddingStrategyError.CANNOT_CHANGE_BIDDING_STRATEGY_TYPE	FieldError.IMMUTABLE_FIELD
MutateError.RESOURCE_READ_ONLY	MutateError.MUTATE_NOT_ALLOWED
OperationAccessDeniedError.MUTATE_ACTION_NOT_PERMITTED_FOR_CLIENT	MutateError.MUTATE_NOT_ALLOWED

Experiments

• Removed CampaignExperimentService in favor of the previously added new experiments.
• Renamed ExperimentArm.trial to ExperimentArm.experiment.
• When you create a new experiment arm using MutateExperimentArms and set response_content_type of your mutate request toMUTABLE_RESOURCE, it now also populates values in ExperimentArm.in_design_campaigns.

Feeds

• Added LEGACY_FEED_TYPE_READ_ONLY to the following enums:

  • CampaignFeedError
  • FeedItemError
  • FeedMappingError

Planning

• AudienceInsightsService.ListAudienceInsightsAttributes now accepts AudienceInsightsDimension.GEO_TARGET_COUNTRY and AudienceInsightsDimension.SUB_COUNTRY_LOCATION, enabling clients to discover the location criteria that can be used in AudienceInsightsService.
• Added AudienceInsightsService.ListInsightsEligibleDates (available to allowlisted accounts only), enabling clients to discover the set of date ranges that can be used in AudienceInsightsService.

• Removed GenerateProductMixIdeas from ReachPlanService.

• Added Targeting.plannable_location_ids, which supports targeting multiple geo locations within the same parent location in a single reach forecast.

Recommendations

• Added RaiseTargetCpaBidTooLowRecommendation which identifies target CPA adjustments to help campaigns start serving.
• Added ForecastingSetTargetRoasRecommendation which identifies target ROAS adjustments to capture additional conversion value from expected traffic increases.

Reporting

• Added support for returning the number of clicks for sitelinks (when segments.click_type = SITELINKS) in the landing_page_view report.

• Added the following purchased traffic metrics:

  • metrics.publisher_purchased_clicks
  • metrics.publisher_organic_clicks
  • metrics.publisher_unknown_clicks

Video

• Made AdGroup.cpv_bid_micros mutable.

11.1.0 (2022-08-17)

The functionality and changes below were added in v11.1.

Assets

• Added AssetGroup.ad_strength to represent the overall quality of the asset group.
  • When advertisers mutate asset groups or assets associated with the asset groups, this field is recalculated. Until the recalculation is finished, the value is PENDING.
• Added AssetLinkError.EXCLUDED_PARENT_FIELD_TYPE.

Audiences

• Added FlexibleRuleUserListInfo and RuleBasedUserListInfo.flexible_rule_user_list.
• Added more values to the LeadFormFieldUserInputType enum (used as predefined questions for lead form extensions).
• Added the following fields to UserAttribute:
  • lifecycle_stage
  • first_purchase_date_time
  • event_attribute
• Added the following errors to OfflineUserDataJobError:
  • FIRST_PURCHASE_TIME_GREATER_THAN_LAST_PURCHASE_TIME
  • INVALID_LIFECYCLE_STAGE
  • INVALID_EVENT_VALUE
  • EVENT_ATTRIBUTE_ALL_FIELDS_ARE_REQUIRED

Bidding

• Added Campaign.bidding_strategy_system_status to show the system status of the bidding strategy, such as whether it is learning, limited, or misconfigured. Learn more.

Campaigns

• Added support for the following metrics in the campaign report:
  • all_conversions_from_click_to_call
  • all_conversions_from_directions
  • all_conversions_from_menu
  • all_conversions_from_order
  • all_conversions_from_other_engagement
  • all_conversions_from_store_visit
  • all_conversions_from_store_website
• Made metrics.phone_call compatible with segments.hour in the campaign report.

Experiments

• You can now create experiments using GoogleAdsService.Mutate(). Previously, it was possible only when using ExperimentService.

Planning

• Added Targeting.audience_targeting, which allows for specifying affinity and in-market categories to generate a reach forecast using ReachPlanService.GenerateReachForecast.

• Added support for YouTube Select:

  • Added support for returning YouTubeSelectLineUp as product metadata when calling ReachPlanService.ListPlannableProducts.
  • Added PlannedProduct.advanced_product_targeting, which allows for specifying YouTubeSelectSettings to generate a reach forecast using ReachPlanService.GenerateReachForecast.

• Added AudienceInsightsService.GenerateAudienceCompositionInsights (available to allowlisted accounts only), used to find attributes strongly associated with a particular audience, similar to Insights Finder.

Recommendations

• Added UpgradeLocalCampaignToPerformanceMaxRecommendation. Learn more.
• Added DisplayExpansionOptInRecommendation.

11.0 (2022-06-08)

The functionality and changes below were added in v11.0.

Assets

• Added AssetSource to show the source of asset or asset link for whom generated the entity. This is available as source in Asset, CustomerAsset, CampaignAsset, and AdGroupAsset.

Audiences

• Removed DateSpecificRuleUserListInfo and RuleBasedUserListInfo.date_specific_rule_user_list.

Bidding

• Renamed MaximizeConversions.target_cpa to MaximizeConversions.target_cpa_micros. MaximizeConversions.target_cpa of AccessibleBiddingStrategy is renamed to target_cpa_micros.

Campaigns

• Smart campaigns

  • Added SmartCampaignSetting.ad_optimized_business_profile_setting and AdOptimizedBusinessProfileSetting to allow Smart campaigns to use business profiles optimized for ads as landing pages.
  • Added SmartCampaignSetting.business_profile_location to accept the resource names of the Google Business Profile location to associate with Smart campaigns.
  • Removed SmartCampaignSetting.business_location_id, which is superseded by SmartCampaignSetting.business_profile_location.

• Added Campaign.performance_max_upgrade, whose type is PerformanceMaxUpgrade, to show the status information about a campaign being upgraded to Performance Max. Use the new UpgradeSmartShoppingCampaignToPerformanceMaxRecommendation to initiate the upgrade.

• The search_click_share metric is now available for Performance Max campaigns.

• For Local Services campaigns:

  • Added the ManualCpa bidding strategy and Campaign.local_services_campaign_settings, whose type is LocalServicesCampaignSettings.

  • You can set bids of the ManualCpa bidding strategy through LocalServicesCampaignSettings.category_bids.

  • Added support for setting the MaximizeConversions bidding strategy as standard bidding strategy.

  • Added support for setting ad schedules as a campaign criterion.

Conversions

• Added two new fields to FirebaseSettings:

  • property_id
  • property_name

• Added ConversionAdjustmentUploadError.ORDER_ID_CONTAINS_PII.

• Added ConversionUploadError.ORDER_ID_CONTAINS_PII.

• Removed ConversionUploadError.EXTERNALLY_ATTRIBUTED_CONVERSION_TYPE_NOT_PERMITTED_WITH_BRAID.

Criteria

• Added SettingError.BID_ONLY_IS_NOT_ALLOWED_TO_BE_MODIFIED_WITH_CUSTOMER_MATCH_TARGETING.

Experiments

• Removed ExperimentType.SMART_DISPLAY.

Planning

• Added KeywordPlanIdeaService.GenerateAdGroupThemes, which you can provide keywords and a list of ad groups. The method returns suggested modifications (such as keyword text and match type) of the keywords along with the suggested ad groups in which the keywords should be placed.
• Added two methods to AudienceInsightsService that are available to allowlisted accounts only:
  • GenerateInsightsFinderReport, used to create links to audience insight reports in Insights Finder.
  • ListAudienceInsightsAttributes, used to discover topics or categories for which insights are available.

• Added several new fields to support co-viewing metrics in Reach Forecast.

  • Several new fields as part of ReachForecast:

    • In Forecast: on_target_coview_reach total_coview_reach on_target_coview_impressions total_coview_impressions

    • In EffectiveFrequencyBreakdown: effective_coview_reach on_target_effective_coview_reach

    • In PlannedProductForecast: on_target_coview_reach total_coview_reach on_target_coview_impressions total_coview_impressions

  • Added ForecastMetricOption.include_coview, which is used in GenerateReachForecastRequest.forecast_metric_options as an option to request the above co-view metrics to be included in the response.

Recommendation

• Added ResponsiveSearchAdImproveAdStrengthRecommendation.

• Added UpgradeSmartShoppingCampaignToPerformanceMaxRecommendation.

Reporting

• Made segments.asset_interaction_target.asset and segments.asset_interaction_target.interaction_on_this_asset compatible with ad_group and campaign.

Shopping

• Added ShoppingSetting.feed_label, a more flexible way of matching campaigns with Merchant feeds. This field replaces the functionality of ShoppingSetting.sales_country. Only one of these fields can be used at a time, but both fields are supported. This is available to allowlisted accounts only.

10.1.0 (2022-04-27)

The functionality and changes below were added in v10.1.0.

Assets

• Added the following for lead forms:
  • Support for retrieving submitted lead form data through LeadFormSubmissionData using GoogleAdsService.Search and GoogleAdsService.SearchStream
  • LeadFormAsset.custom_question_fields
• Added the following asset types:
  • Added dynamic_real_estate_asset to Asset to support dynamic real estate assets.
  • Added dynamic_custom_asset to Asset to support dynamic custom assets.
  • Added dynamic_hotels_and_rentals_asset to Asset to support dynamic hotels and rentals assets.
  • Added dynamic_flights_asset to Asset to support dynamic flights assets.
  • Added dynamic_travel_asset to Asset to support dynamic travel assets.
  • Added dynamic_local_asset to Asset to support dynamic local assets.
  • Added dynamic_jobs_asset to Asset to support dynamic jobs assets.
• Added support for the following fields to asset_group_product_group_view:
  • asset_group
  • asset_group_listing_group_filter
• Added ad_group_ad_asset_combination_view.enabled.
• Added AssetError.NAME_CONFLICT_FOR_ASSET_TYPE.

Audiences

• Added support for metrics.absolute_top_impression_percentage and metrics.top_impression_percentage in campaign_audience_view and ad_group_audience_view.
• Added ResourceLimitType.RULE_BASED_USER_LISTS_PER_CUSTOMER.
• Added the following values to AudienceError:
  • AUDIENCE_SEGMENT_NOT_FOUND
  • AUDIENCE_SEGMENT_TYPE_NOT_SUPPORTED
  • DUPLICATE_AUDIENCE_SEGMENT
  • TOO_MANY_SEGMENTS
  • TOO_MANY_DIMENSIONS_OF_SAME_TYPE
  • IN_USE

Batch Jobs

• Added BatchJobOperation.remove to support removing batch jobs in the PENDING state.

Campaigns

• Added support for retrieving, creating, and updating Discovery campaigns, their ad groups, and their ads.
  • Enums:
    • AdvertisingChannelType.DISCOVERY
    • AdType.DISCOVERY_CAROUSEL
    • AdType.DISCOVERY_MULTI_ASSET
    • AssetType.DISCOVERY_CAROUSEL_CARD
• Added support for retrieving, creating, and updating campaign groups:
  • Resource: CampaignGroup
  • Service: CampaignGroupService
  • Fields in other resources:
    • Campaign.campaign_group
    • GoogleAdsRow.campaign_group
  • Enums:
    • CampaignGroupStatus
• Local Services campaigns, previously in Beta, are now in generally availability
• Added legacy support for the following dimensions to ListingDimensionInfo for Display campaigns only:
  • ProductGroupingInfo
  • ProductLabelsInfo
  • ProductLegacyConditionInfo
  • ProductTypeFullInfo

Change History

• Added the following values to ChangeEventResourceType:
  • ASSET_SET
  • ASSET_SET_ASSET
  • CAMPAIGN_ASSET_SET

Conversions

• Added ConversionTrackingSetting.google_ads_conversion_customer, used to determine which Google Ads account is managing your account's conversions.
• Added ClickConversion.conversion_environment to support reporting the environment on which a conversion was recorded. This feature is available to allowlisted accounts only.
• Added support for metrics.all_conversions_value and metrics.all_conversions in conversion_action.
• Added ConversionValueRuleSetError.UNSUPPORTED_CONVERSION_ACTION_CATEGORIES.
• Added ConversionAdjustmentUploadError.MISSING_ORDER_ID_FOR_WEBPAGE.
• Added ConversionUploadError.CUSTOMER_NOT_ACCEPTED_CUSTOMER_DATA_TERMS.

Criteria

• Added CriterionError.CANNOT_TARGET_CUSTOMER_MATCH_USER_LIST.

Experiments

• Added ExperimentError.STATUS_TRANSITION_INVALID.

Hotel Ads

• Added support for getting hotel_center_id through AccountLink.hotel_center.

Planning

• Added KeywordPlanIdeaService.GenerateKeywordHistoricalMetrics. It returns the historical metrics for a given list of keywords without asking for any plan, campaigns, or ad groups.
• Added KeywordPlanHistoricalMetrics.average_cpc_micros which is the average cost per click in micros of a given keyword.
  • Added a new field HistoricalMetricsOption.include_average_cpc, which is used in GenerateKeywordIdeasRequest.historical_metrics_options as an option to request KeywordPlanHistoricalMetrics.average_cpc_micros to be included in the response. The default value if not specified is false.
• Added GenerateKeywordIdeaResult.close_variants which is the list of close variants from the requested keywords that are combined into this GenerateKeywordIdeaResult.

Reporting

• segments.click_type now returns CROSS_NETWORK for Performance Max and Discovery campaigns.
• Added the following fields for SKAdNetwork conversion segments, available when fetching the data of customer or campaign:
  • metrics.sk_ad_network_conversions
  • segments.sk_ad_network_attribution_credit
• Made metrics.absolute_top_impression_percentage and metrics.top_impression_percentage compatible with segments.geo_target_region and segments.geo_target_city.

Video

• Added VideoResponsiveAdInfo.breadcrumb1 and VideoResponsiveAdInfo.breadcrumb2.

10.0 (2022-02-09)

The functionality and changes below were added in v10.0.

All Services

The get method and any services that exclusively had a get method have been removed. Retrieve objects with Search and SearchStream from GoogleAdsService.

Account Management

• Added Customer.status and CustomerClient.status, whose type is CustomerStatus, to show the status of the account.
• customer_client contains inactive accounts in addition to active and test accounts.

Ads

• Renamed Video TrueView Discovery Ad format to In-Feed Video Ad:
  • VideoTrueViewDiscoveryAdInfo is renamed to InFeedVideoAdInfo.
  • AdType.VIDEO_TRUEVIEW_DISCOVERY_AD is renamed to AdType.IN_FEED_VIDEO_AD.
• Renamed MutateOperation.customizer_customizer_operation to MutateOperation.customer_customizer_operation.

Assets

• Added support for ad_group_ad_asset_combination_view for responsive search ads.
• Added support for reporting the performance of App pre registration ads in ad_group_ad_asset_view.
• For Image and Media Bundle assets (Asset that has image_asset and media_bundle_asset set, respectively):
  • Made name required.
  • Added support for auto-renaming the asset names on creation. If an asset exists with the same name but different content, it is renamed by appending the specified name with a timestamp and a counter.
• For the following asset types, if an asset with a different name having the same content already exists then the asset uploaded will be silently dropped.
  • Image
  • Media Bundle
  • Text
  • Call to Action
  • Book on Google
• Added the following values related to asset sets to ResourceLimitType:
  • PAGE_FEED_ASSET_SETS_PER_CUSTOMER
  • DYNAMIC_EDUCATION_FEED_ASSET_SETS_PER_CUSTOMER
  • ASSET_PER_PAGE_FEED_ASSET_SET
  • ASSET_PER_DYNAMIC_EDUCATION_FEED_ASSET_SET
• Added the following values to AssetError:
  • MOBILE_APP_INVALID_APP_ID
  • MOBILE_APP_INVALID_FINAL_URL_FOR_APP_DOWNLOAD_URL
  • NAME_REQUIRED_FOR_ASSET_TYPE

Audiences

• Added support for Audience used to create a targeting based on created dimensions, such as demographics or memberships in user lists and user interests:
  • Resource: Audience
  • Service: AudienceService
  • Fields in other resources:
    • GoogleAdsRow.audience
    • Campaign.audience_setting
    • AdGroup.audience_setting
    • AdGroupCriterion.audience
  • Enums:
    • AudienceError
    • CriterionType.AUDIENCE

Bidding

• Removed support for creating seasonality adjustments on manager accounts.
• Added the following values to BiddingError:
  • BIDDING_STRATEGY_AND_BUDGET_MUST_BE_ALIGNED
  • BIDDING_STRATEGY_AND_BUDGET_MUST_BE_ATTACHED_TO_THE_SAME_CAMPAIGNS_TO_ALIGN
  • BIDDING_STRATEGY_AND_BUDGET_MUST_BE_REMOVED_TOGETHER

Campaigns

• Smart campaigns have exited open beta and entered general availability.
• Added support for Local Services Ads campaigns as open beta.
  • They have AdvertisingChannelType as LOCAL_SERVICES.
  • Added support for retrieving these campaigns using Search and SearchStream.
  • Added support for updating their status and amount_micros of their associated CampaignBudget objects.
• Performance Max Campaigns now support asset group signals which advertisers can use to tell the campaign who's most likely to convert.
• Added Campaign.use_vehicle_inventory for Smart Shopping campaigns.

Conversions

• Added the following fields to the conversion_tracking_setting attribute of Customer:
  • conversion_tracking_status indicates whether the customer is using conversion tracking, and who is the conversion tracking owner.
  • accepted_customer_data_terms indicates if the conversion tracking owner has accepted the customer data terms.
  • enhanced_conversions_for_leads_enabled indicates if the customer has opted into enhanced conversions for leads.
• Made ConversionAction.primary_for_goal optional to support setting the value to false during create operations.
• Made ConversionValueRuleSet.attachment_type immutable.
• Added ConversionValueRuleSet.conversion_action_categories and ValueRuleSetDimension.NO_CONDITION to support conversion value rules for store visits and store sales.
• Added the following values to ConversionValueRuleSetError:
  • INELIGIBLE_CONVERSION_ACTION_CATEGORIES
  • DIMENSION_NO_CONDITION_USED_WITH_OTHER_DIMENSIONS
  • DIMENSION_NO_CONDITION_NOT_ALLOWED
• Removed LEAD from the ConversionActionCategory enum and replaced with the following new values:
  • QUALIFIED_LEAD
  • CONVERTED_LEAD
• Added ExternalConversionSource.DISPLAY_AND_VIDEO_360_FLOODLIGHT.

Experiments

• Added a new ExperimentService with a set of new resources, which is a replacement for campaign experiments.
  • Creating a new experiment and experiment arm through GoogleAdsService.Mutate() is not supported yet.

Hotel Ads

• Added hotel_reconciliation.campaign and added support for the following metrics:
  • metrics.hotel_commission_rate_micros
  • metrics.hotel_expected_commission_cost

Recommendations

• Added support for returning ResponsiveSearchAdAssetRecommendation.
• Added support for returning UseBroadMatchKeywordRecommendation.

Reporting

• Fixed inconsistencies where rows with zero metrics were returned when segments were selected in some reports. All reports will now follow the expected behavior of ignoring zero-metric rows in reports that select metrics and segments.
• Added a new meta parameter omit_unselected_resource_names. When set to true, the response from GoogleAdsService will only return resource name fields that you explicitly request in the SELECT clause of your query.
• When retrieving Campaign.start_date and Campaign.end_date, the date returned will always be formatted based on the time zone of the customer specified as customer_id of SearchGoogleAdsRequest or SearchGoogleAdsStreamRequest. Previously, the returned date could vary based on the time zone of the manager account specified in login-customer-id.
• Added support for metrics.absolute_top_impression_percentage and metrics.top_impression_percentage
  • in geographic_view
  • with segments.hour
• Added support for the following segments for metrics.sk_ad_network_conversions (SKAdNetwork conversions), which is available when fetching the data of customer or campaign:
  • segments.sk_ad_network_user_type
  • segments.sk_ad_network_ad_event_type
  • segments.sk_ad_network_source_app.sk_ad_network_source_app_id
• Added metrics.biddable_app_install_conversions and metrics.biddable_app_post_install_conversions.

RMF

• Added new requirements for Performance Max and Smart campaigns. We are also documenting the required minimum functionality for other developer tools such as shopping, hotel and app campaigns, and simplifying standard shopping campaigns to align with full service campaigns.

9.0 (2021-11-03)

The functionality and changes below were added in v9.0.

Account Management

• Added the following errors:
  • ManagerLinkError.CREATING_ENABLED_LINK_NOT_ALLOWED
  • ManagerLinkError.CUSTOMER_CANNOT_MANAGE_SELF

Ads

• Added support for ad customizers for Responsive Search Ads through the following services:
  • CustomizerAttributeService
  • CustomerCustomizerService
  • CampaignCustomizerService
  • AdGroupCustomizerService
  • AdGroupCriterionCustomizerService
• Added support for pre-registration ads which helps in pre-registering the app or game from the Play store to help gauge interest before an app or a game is available to install. For more information, see App campaigns for pre-registration.
• Added the following enums to AdError:
  • CALL_AD_VERIFICATION_URL_FINAL_URL_DOES_NOT_HAVE_SAME_DOMAIN
  • CALL_AD_FINAL_URL_AND_VERIFICATION_URL_CANNOT_BOTH_BE_EMPTY
  • CUSTOMIZER_TYPE_FORBIDDEN_FOR_FIELD
  • INVALID_CUSTOMIZER_ATTRIBUTE_NAME

Assets

• Added the following asset types, which will be available in all accounts by the end of 2021:
  • Added price_asset to Asset to support price assets.
  • Added hotel_callout_asset to Asset to support hotel callout assets.
  • Added mobile_app_asset to Asset to support mobile app assets.
  • Added call_asset to Asset to support call assets.
  • Added call_to_action to Asset to support call to action assets.
• Added support for asset groups for Performance Max:
  • Added AssetGroupService to allow for removing AssetGroup, which represents a bunch of assets. Use GoogleAdsService.mutate to create or update an AssetGroup. An asset group is used in a Performance Max campaign to group assets, a final URL, and audience signals. The asset group and the conversion goals are pulled together to create a campaign.
  • Added AssetGroupAssetService to allow for adding/updating/removing AssetGroupAsset, which is a link between an asset and an asset group.
  • Added AssetGroupListingGroupFilterService to allow for adding/updating/removing AssetGroupListingGroupFilter, which represents a listing group filter tree node in an asset group.
  • Added asset_group_product_group_view, for retrieving product groups in an asset group. At the time of the release, requests for this view will return an error. The view will start returning data at a later date.
• Added support for asset sets:
  • Added AssetSetService to allow for adding/updating/removing AssetSet, which represents a collection of assets, which will eventually replace the FeedService. AssetSetType represents feed types that are currently supported.
  • Added AssetSetAssetService to allow for adding/updating/removing AssetSetAsset, which represents a link between an asset and an asset set.
  • Added CampaignAssetSetService to allow for adding/updating/removing CampaignAssetSet, which represents a link between a campaign and an asset set.
• Added support for reporting the performance of the following ad types in ad_group_ad_asset_view:
  • App engagement ads
  • Responsive search ads
• Added AssetLinkError.YOUTUBE_VIDEO_DURATION_NOT_DEFINED.
• Added FeedError.LEGACY_EXTENSION_TYPE_READ_ONLY for extension types migrated to Asset.
• TextAsset is now read/write.
• Added values to AssetError:
  • CALL_CARRIER_SPECIFIC_SHORT_NUMBER_NOT_ALLOWED
  • CALL_CUSTOMER_CONSENT_FOR_CALL_RECORDING_REQUIRED
  • CALL_DISALLOWED_NUMBER_TYPE
  • CALL_INVALID_CONVERSION_ACTION
  • CALL_INVALID_COUNTRY_CODE
  • CALL_INVALID_DOMESTIC_PHONE_NUMBER_FORMAT
  • CALL_INVALID_PHONE_NUMBER
  • CALL_PHONE_NUMBER_NOT_SUPPORTED_FOR_COUNTRY
  • CALL_PREMIUM_RATE_NUMBER_NOT_ALLOWED
  • CALL_VANITY_PHONE_NUMBER_NOT_ALLOWED
  • PRICE_HEADER_SAME_AS_DESCRIPTION

Audiences

• Added support for warnings for OfflineUserDataJobService through AddOfflineUserDataJobOperationsRequest.enable_warnings. When enable_warnings is set to true and the request succeeds, any non-blocking errors relating to operation failures will be returned as AddOfflineUserDataJobResponse.warning. No warnings are returned if the request fails. Learn more.
• Added CreateOfflineUserDataJobRequest.enable_match_rate_range_preview. When it's set to true, the match rate range for the uploaded offline user data job will be calculated and returned as OfflineUserDataJobMetadata.match_rate_range, which you can retrieve using the newly added OfflineUserDataJob.operation_metadata field.
  • match_rate_range shows the range of the match rate (efficacy) of your Customer Match uploads, which is the number of matched user data rows divided by the total number of Customer Match uploaded rows.
• Added UserAttribute.shopping_loyalty to allow for sending loyalty-related data with UserAttribute.
• Added OfflineUserDataJobError.INVALID_ITEM_ID.

Bidding

• Added the following fields for MaximizeConversions and MaximizeConversionValue portfolio bidding strategies:
  • MaximizeConversions.cpc_bid_ceiling_micros
  • MaximizeConversions.cpc_bid_floor_micros
  • MaximizeConversionValue.cpc_bid_ceiling_micros
  • MaximizeConversionValue.cpc_bid_floor_micros
• Removed support for CampaignCriterionSimulation for Shopping campaigns.
• Removed support for AdGroupSimulation for Video campaigns.

Billing

• Added the following errors:
  • BillingSetupError.FUTURE_START_TIME_PROHIBITED
  • InvoiceError.BILLING_SETUP_NOT_ON_MONTHLY_INVOICING
  • InvoiceError.NON_SERVING_CUSTOMER

Campaigns

• Added support for Performance Max campaigns, which is a new campaign type that provides a unified buying service to virtually all Google Ads inventory.

• Changes in Smart campaigns:

  • Smart campaigns have entered open beta and users no longer need to be allowlisted to use them.

  • Added SmartCampaignSuggestService.SuggestKeywordThemes to generate keyword theme suggestions for Smart campaigns based on the business details provided.

    This provides more comprehensive suggestions than SuggestKeywordThemeConstants, and is now the recommended way to generate keyword themes for a Smart campaign.

  • Improved error handling and additional user-facing error codes.

Conversions

• Added support for conversion goals to help you more easily optimize towards your advertising objects.
• Changes related to ConversionAdjustmentUploadService:
  • Moved gclid_date_time_pair and order_id out of the oneof field of ConversionAdjustment.
    • If adjustment_type is ENHANCEMENT, order_id is required. We recommend advertisers to set gclid_date_time_pair to GclidDateTimePair.conversion_date_time. GclidDateTimePair.gclid is optional.
    • If ConversionAdjustmentType is of other types, only one of order_id and gclid_date_time_pair can be set. Otherwise, a GCLID_DATE_TIME_PAIR_AND_ORDER_ID_BOTH_SET error is thrown.
• Changes related to ConversionUploadService:
  • Changed CartData.merchant_id from string to int64.
  • Added ClickConversion.gbraid and ClickConversion.wbraid fields as click identifiers for iOS devices.
• Made UserIdentifier.user_identifier_source optional.
• Improved ConversionUploadService and ConversionAdjustmentService to report an error if the ClickConversion, CallConversion, or ConversionAdjustment in a mutate operation already exists or is a duplicate to another one in the same mutate operation. Prior to v9, the Google Ads API would silently ignore such operations. The error returned by each service will be as follows:
  • For ConversionUploadService:
    • For a click conversion: a ConversionUploadError with CLICK_CONVERSION_ALREADY_EXISTS or DUPLICATE_CLICK_CONVERSION_IN_REQUEST
    • For a call conversion: a ConversionUploadError with CALL_CONVERSION_ALREADY_EXISTS or DUPLICATE_CALL_CONVERSION_IN_REQUEST
  • For ConversionAdjustmentService:
    • For a restatement: a ConversionAdjustmentUploadError with RESTATEMENT_ALREADY_EXISTS or DUPLICATE_ADJUSTMENT_IN_REQUEST
    • For an enhancement: a ConversionAdjustmentUploadError with CONVERSION_ALREADY_ENHANCED or DUPLICATE_ENHANCEMENT_IN_REQUEST
• Removed INVALID_USER_IDENTIFIER_SOURCE from ConversionAdjustmentUploadError and ConversionUploadError.

Feeds

• Deprecated extension setting services:

  • AdGroupExtensionSettingService
  • CampaignExtensionSettingService
  • CustomerExtensionSettingService
  • ExtensionFeedItemService

• Deprecated most use cases of feed service in favor of assets:

  • All extensions apart from location extensions should migrate to assets.
  • DSA page feed should migrate to assets.
  • Dynamic remarketing for education should migrate to assets. Other dynamic remarketing types will follow in a release.
  • Ad customizers are the only non-deprecated use case for feeds.

Hotel Ads

• Added support for retrieving hotel_reconciliation resources, which contain booking information to reconcile bookings from commission campaigns.
• Removed HOTEL_ADS_COMMISSION from BudgetType.

Mutates

• Added MutateError.OPERATION_DOES_NOT_SUPPORT_PARTIAL_FAILURE, thrown when MutateGoogleAdsRequest.partial_failure is set to true but MutateGoogleAdsRequest.mutate_operations[] contains mutate operations that don't support partial failure.

Planning

• Added PlannableLocation.location_type which contains the location's type (COUNTRY, STATE, etc.).
• Added PlannableLocation.country_code which contains the ISO-3166-1 alpha-2 code associated with the location.
• Added CampaignDuration.date_range which allows the duration of a planning campaign to be specified as a date range.

Reporting

• A value for any of the following date-related segments in the WHERE clause must be the start of the field's period:

  Fields	Allowed filter values
  segments.week	YYYY-MM-DD where DD is the date that is Monday and YYYY and MM are valid year and month values, respectively.
  segments.month	YYYY-MM-01 where YYYY and MM are valid year and month values, respectively.
  segments.quarter	YYYY-01-01 or YYYY-04-01 or YYYY-07-01 or YYYY-10-01.

  Failing to set the correct values will result in a MISALIGNED_DATE_FOR_FILTER error.

• segments.sk_ad_network_conversion_value now supports distinguishing between 0 conversion value and conversion value missing from the postback received from Apple. Note that this feature will only be available for SKAdNetwork conversions received after September 20th, 2021.

• Published the phone_calls, phone_impressions, and phone_through_rate metric fields in the following resources:

  • ad_group_asset
  • asset_field_type_view
  • campaign_asset
  • customer_asset

RMF

• RMF requirements have been considerably simplified.

Video

• Added VideoTrueViewDiscoveryAdInfo.thumbnail.
• Added VideoNonSkippableInStreamAdInfo.action_button_label and VideoNonSkippableInStreamAdInfo.action_headline.
• Removed the optional keyword from the following fields to be consistent with their behaviors, since null and the default values of those fields (empty strings) have the same meaning for the Google Ads API:
  • VideoOutstreamAdInfo.headline
  • VideoOutstreamAdInfo.description
  • VideoTrueViewDiscoveryAdInfo.headline
  • VideoTrueViewDiscoveryAdInfo.description1
  • VideoTrueViewDiscoveryAdInfo.description2
• Migrated Video ads from using MediaFile to represent videos and images to using assets.
  • Changed the type of the following fields from string to AdImageAsset:
    • VideoBumperInStreamAdInfo.companion_banner
    • VideoNonSkippableInStreamAdInfo.companion_banner
    • VideoTrueViewInStreamAdInfo.companion_banner
  • Replaced VideoAdInfo.media_file (available until v8) with VideoAdInfo.video and changed the type from string to AdVideoAsset.

8.1.0 (2021-08-11)

The functionality and changes below were added in v8.1.0.

Ads

• Added action_items to AdGroupAd to provide you with feedback to improve your ad strength.

Bidding

• Added support for seasonality adjustments and data exclusions, which can be applied to specific campaigns, to all campaigns that belong to specific channel types, or to specific devices:
  • Added BiddingSeasonalityAdjustment to let Smart Bidding apply conversion rate adjustments for future events such as promotions or sales.
  • Added BiddingDataExclusion to let Smart Bidding exclude data from specific dates when there are issues with an account's conversion tracking.
• Added BiddingStrategyType.INVALID to indicate a campaign does not have a bidding strategy and cannot serve. This can occur if a campaign was previously using a manager-owned bidding strategy before being unlinked from the manager account. In this case, the campaign would transition to the INVALID bidding strategy type.

Campaigns

• Added SmartCampaignSuggestService.SuggestSmartCampaignAd() to get suggestions for up to three headlines and two descriptions for Smart campaign ads based on information such as the landing page and keyword themes provided.

Change History

• Added the following resource types to ChangeEventResourceType:
  • AD_GROUP_ASSET
  • ASSET
  • CAMPAIGN_ASSET
  • CUSTOMER_ASSET
• Added the following new resource types to ChangeStatusResourceType:
  • AD_GROUP_ASSET
  • ASSET
  • CAMPAIGN_ASSET
  • CAMPAIGN_SHARED_SET
  • CUSTOMER_ASSET
  • SHARED_SET

Conversions

• Added ConversionValueRule and ConversionValueRuleSet resources to adjust values of conversion events based on conditions like geographic location, device and audiences, and better express the value of conversions as they relate to your business.
• Added ClickConversion.user_identifiers to support uploading conversions with enhanced conversions for leads data
• Added ENHANCEMENT to ConversionAdjustmentType and the following fields to support uploading enhancements to existing conversions:
  • ConversionAdjustment.user_identifiers
  • ConversionAdjustment.user_agent
  • OfflineUserAddressInfo.hashed_street_address
• Added the following values to ConversionUploadError:
  • CLICK_NOT_FOUND
  • INVALID_USER_IDENTIFIER
  • EXTERNALLY_ATTRIBUTED_CONVERSION_ACTION_NOT_PERMITTED_WITH_USER_IDENTIFIER
  • UNSUPPORTED_USER_IDENTIFIER
  • INVALID_USER_IDENTIFIER_SOURCE
• Added the following values to ConversionAdjustmentUploadError:
  • CUSTOMER_NOT_ACCEPTED_CUSTOMER_DATA_TERMS
  • CONVERSION_ACTION_NOT_ELIGIBLE_FOR_ENHANCEMENT
  • INVALID_USER_IDENTIFIER
  • INVALID_USER_IDENTIFIER
  • INVALID_USER_IDENTIFIER_SOURCE

Criteria

• Added CriterionError.BROAD_MATCH_MODIFIER_KEYWORD_NOT_ALLOWED.

Planning

• Added Forecast.effective_frequency_breakdowns to show a list of effective frequency forecasts. Effective frequency forecasts include the on-target and total number of unique people reached for a given effective frequency.
• Added GenerateReachForecastRequest.effective_frequency_limit which is used to create effective_frequency_breakdowns of the generated Forecast. effective_frequency_limit is the highest minimum effective frequency (the number of times a person was shown the ad).

8.0 (2021-06-09)

The functionality and changes below were added in v8.0.

Account Management

• Added CustomerClient.applied_labels to show the labels applied to customers managed by the requesting manager customer.

Ads

• CallOnlyAdInfo is replaced with CallAdInfo.
• Added CANNOT_UPDATE_DEPRECATED_ADS to AdGroupAdError.

Asset

• Set response_content_type to MUTABLE_RESOURCE as a request parameter to return all the fields mutated in a mutate request for CustomerAssetService, CampaignAssetService and AdGroupAssetService.
• Added support for the following metrics for CustomerAsset, CampaignAsset and AdGroupAsset:
  • absolute_top_impression_percentage
  • all_conversions
  • all_conversions_from_interactions_rate
  • all_conversions_value
  • average_cost
  • average_cpc
  • average_cpe
  • average_cpm
  • average_cpv
  • clicks
  • conversions
  • conversions_from_interactions_rate
  • conversions_value
  • cost_micros
  • cost_per_all_conversions
  • cost_per_conversion
  • cross_device_conversions
  • ctr
  • engagement_rate
  • engagements
  • interactions
  • interaction_event_types
  • interaction_rate
  • impressions
  • top_impression_percentage
  • value_per_all_conversions
  • value_per_conversion
  • video_view_rate
  • video_views
• Added segments.asset_interaction_target for CustomerAsset, CampaignAsset and AdGroupAsset to indicate if the interactions are on the asset itself.
• Added AssetFieldTypeViewService to support retrieving metrics for each asset field type when the asset is used as extension.
• Updated the following values of LeadFormFieldUserInputType:
  • Replaced GIVEN_NAME with FIRST_NAME.
  • Replaced FAMILY_NAME with LAST_NAME.
• Asset-based extensions
  • SitelinkAsset, CalloutAsset, StructuredSnippetAsset, which were available for test accounts in v7, will be enabled for production accounts two weeks after this release.

Audiences

• Added TransactionAttribute.item_attribute to support associate information about a sold item with a transaction.
• Added the following fields to UserAttribute:
  • last_purchase_date_time
  • average_purchase_count
  • average_purchase_value_micros
  • acquisition_date_time
• Added the following values to OfflineUserDataJobError:
  • FUTURE_TIME_NOT_ALLOWED
  • LAST_PURCHASE_TIME_LESS_THAN_ACQUISITION_TIME

Bidding

• Updated Maximize_conversion_value.target_roas to support an optional Target ROAS setting on the Maximize Conversion Value portfolio and standard bidding strategies for Search campaigns. This field will become mutable for all customers at a future date. We will post a notification on the Google Ads Developer blog when developers can update this field.
• Updated Maximize_conversions.target_cpa to support an optional Target CPA setting on the Maximize Conversions portfolio and standard bidding strategies for Search campaigns. This field will become mutable for all customers at a future date. We will post a notification on the Google Ads Developer blog when developers can update this field.
• Added support for creating and managing cross-account bidding strategies in manager accounts, and the ability to attach them to campaigns in customer accounts:
  • Added BiddingStrategy.currency_code for bidding strategies in manager customers, which can be set on creation and defaults to the manager customer's currency. For serving customers, this field cannot be set; all strategies in a serving customer implicitly use the serving customer's currency. In all cases the effective_currency_code field returns the currency used by the strategy.
  • Added AccessibleBiddingStrategy to represent a view of all BiddingStrategies owned by and shared with the customer.
  • Added AccessibleBiddingStrategyService to read accessible bidding strategies.
  • Added Campaign.accessible_bidding_strategy for retrieving the fields of the portfolio bidding strategy identified by bidding_strategy.When a campaign uses a cross-account bidding strategy, this will be a subset of the properties normally defined for a bidding strategy, since certain properties are only accessible by a bidding strategy’s owner.

Campaigns

• Replaced CampaignError.PAYMENT_MODE_NOT_COMPATIBLE_WITH_VIEW_THROUGH_CONVERSION with CampaignError.NOT_COMPATIBLE_WITH_VIEW_THROUGH_CONVERSION_OPTIMIZATION. Reports incompatibilities with view through conversions setup.
• Added support for Smart campaigns:
  • Added new enum values to support Smart campaigns:
    • BudgetTypeEnum.SMART_CAMPAIGN
    • AdGroupTypeEnum.SMART_CAMPAIGN_ADS
  • Added SmartCampaignSetting and SmartCampaignSettingService to configure Smart campaigns.
  • Added KeywordThemeConstantService and SmartCampaignSuggestService to retrieve suggestions for Smart campaign budgets and keyword themes.
  • Added smart_campaign_search_term_view to retrieve performance metrics for Smart campaigns.

Conversions

• Added ClickConversion.cart_data to support uploading conversions with shopping cart information.
• Added CONVERSION_NOT_COMPLIANT_WITH_ATT_POLICY to ConversionUploadError.

Criteria

• Added DetailedDemographicService to retrieve UserInterest with DetailedDemographic as the TaxonomyType.

Feeds

• Added DYNAMIC_FILTER_INVALID_CHAIN_IDS to FeedItemSetError.

Recommendations

• Added support for the following fields for Customer and Campaign resources.
  • segments.recommendation_type
  • metrics.optimization_score_url
  • metrics.optimization_score_uplift

7.0 (2021-04-28)

The functionality and changes below were added in v7.0.

Account Management

• Updated CustomerService.CreateCustomerClient, CustomerClientLinkService.MutateCustomerClientLink, CustomerManagerLinkService.MutateCustomerManagerLink, CustomerManagerLinkService.MoveManagerLink, MerchantCenterLinkService.MutateMerchantCenterLink to enable setting validate_only.
• Added AccessInvitationError.EMAIL_DOMAIN_POLICY_VIOLATED.

Ads

• Added AdGroupAd.labels to allow for easier selection and filtering with labels.
• Updated AdService.MutateAds to enable setting partial_failure.
• Updated AdGroupAd.policy_summary.policy_topic_entries of type FULLY_LIMITED to return an approval status of DISAPPROVED rather than UNKNOWN.
• Updated MediaUploadError to include the value DIMENSIONS_NOT_ALLOWED.
• Updated AdService.MutateAds to enable setting validate_only.

Assets

• Added CustomerAssetService and AdGroupAssetService to support adding new asset types.
• Added promotion_asset, final_mobile_urls, tracking_url_template, url_custom_parameters, and final_url_suffix to Asset to support promotion assets.
• Added assets for Test accounts only:
  • Added callout_asset to Asset to support callout assets.
  • Added structured_snippet_asset to Asset to support structured snippet assets.
  • Added sitelink_asset to Asset to support sitelink assets.
• Updated AssetService.MutateAssets to enable setting partial_failure.
• Added values to AssetError:
  • DUPLICATE_ASSETS_WITH_DIFFERENT_FIELD_VALUE
  • PROMOTION_CANNOT_SET_PERCENT_OFF_AND_MONEY_AMOUNT_OFF
  • PROMOTION_CANNOT_SET_PROMOTION_CODE_AND_ORDERS_OVER_AMOUNT
  • SCHEDULES_CANNOT_OVERLAP
  • TOO_MANY_DECIMAL_PLACES_SPECIFIED
• Added INVALID_EXCLUDED_PARENT_ASSET_FIELD_TYPE to AdGroupError and CampaignError.
• Added excluded_parent_asset_field_types to Campaign and AdGroup.
• Updated AssetService.MutateAssets to enable setting validate_only.
• Added INVALID_STATUS to AssetLinkError.
• Added PAUSED to AssetLinkStatus.
• Updated CampaignAsset.status to be mutable. Updates are now allowed for CampaignAsset.
• Updated AdGroupAsset.status to be mutable. Updates are now allowed for AdGroupAsset.

Audiences

• Updated OfflineUserDataJobService.CreateOfflineUserDataJob, OfflineUserDataJobService.RunOfflineUserDataJob, and OfflineUserDataJobService.AddOfflineUserDataJobOperations to enable setting validate_only.

Batch Jobs

• Set response_content_type to MUTABLE_RESOURCE as a request parameter to return all the fields mutated in a mutate request for BatchJobService.

Bidding

• Added BiddingStrategySimulationService and CampaignSimulationService to support the management of shared bidding strategy simulations and campaigns simulations.
• Set response_content_type to MUTABLE_RESOURCE as a request parameter to return all the fields mutated in a mutate request for BiddingStrategyService.

Campaigns

• Added CampaignError.PAYMENT_MODE_NOT_COMPATIBLE_WITH_VIEW_THROUGH_CONVERSION to report incompatibilities with view through conversions setup.

Campaign Drafts and Experiments

• Updated CampaignDraftService.PromotCampaignDraft to enable setting validate_only.
• Updated CampaignExperimentService.GraduateCampaignExperiment, CampaignExperimentService.PromoteCampaignExperiment, CampaignExperimentService.EndCampaignExperiment, CampaignExperimentService.CreateExperiment to enable setting validate_only.

Conversions

• Added ConversionCustomVariableService to support adding and updating custom variables while uploading offline conversions.
• Added CallConversion.custom_variables and ClickConversion.custom_variables with ConversionUploadError.CUSTOM_VARIABLE_NOT_ENABLED and ConversionUploadError.CUSTOM_VARIABLE_VALUE_CONTAINS_PII to support uploading custom variables with an offline call conversion.
• Set response_content_type to MUTABLE_RESOURCE as a request parameter to return all the fields mutated in a mutate request for ConversionActionService.

Criteria

• Added AdGroupCriterion.labels to allow for easier selection and filtering with labels.
• Added AdGroupCriterion.display_name and CampaignCriterion.display_name.
• Added coverage_percentage and sample to WebpageInfo.
• Added WebpageViewService to support retrieving webpage criterion metrics.
• Added LifeEventService to retrieve UserInterest with LifeEvent as the TaxonomyType.

Feeds

• Updated FeedItemTargetService.MutateFeedItemTargets to enable setting partial_failure.
• Updated FeedItemTargetService.MutateFeedItemTargets to enable setting validate_only.
• Set response_content_type to MUTABLE_RESOURCE as a request parameter to return all the fields mutated in a mutate request for CustomerExtensionSettingService.
• Set response_content_type to MUTABLE_RESOURCE as a request parameter to return all the fields mutated in a mutate request for CampaignExtensionSettingService.

Hotel Ads

• Added hotel_check_in_date_range to AdGroupBidModifier. By setting the range of dates, the bid will be modified if the user's check-in date falls within the range.

Planning

• KeywordPlanIdeaService
  • Added GenerateKeywordIdeasRequest.keyword_annotation field to request annotation data for keywords.
    • Added KeywordPlanKeywordAnnotation.KEYWORD_CONCEPT to retrieve the keyword concepts for each generated keyword idea.
      • Concepts are available in the Google Ads UI under Keyword Planner.
      • A concept group is a cluster of related concepts. The KeywordPlanConceptGroupType of the concept group identifies the type of classification performed to generate the concepts.
      • A concept is a semantic grouping of keywords within the concept group.
      • Each keyword can belong to multiple concept groups, but only one concept within a concept group.
    • When keyword_annotation is requested, the annotations are returned in GenerateKeywordIdeaResult.keyword_annotations.
      • When KEYWORD_CONCEPT is requested, the concepts are returned in GenerateKeywordIdeaResult.keyword_annotations.concepts.
  • Added HistoricalMetricsOptions.year_month_range in GenerateKeywordIdeasRequest.historical_metrics_options field to select the custom date range for the search volume. The default value if not specified is the last 12 months.
  • Added KeywordPlanAggregateMetrics.aggregate_metrics_types to GenerateKeywordIdeasRequest.aggregate_metrics to request aggregate metrics for the generated keyword ideas.
    • Added KeywordPlanAggregateMetricType.DEVICE to request device breakdown of the average monthly search volume metrics for all the keyword ideas.
    • The device breakdown will be returned in the GenerateKeywordIdeaResponse.aggregate_metric_results.device_searches.
• KeywordPlanService
  • Added HistoricalMetricsOptions.year_month_range in GenerateHistoricalMetricsRequest.historical_metrics_options field to select the custom date range for the search volume. This year_month_range affects both keyword level and aggregate level metrics.
  • Added KeywordPlanAggregateMetrics.aggregate_metrics_types to GenerateHistoricalMetricsRequest.aggregate_metrics to request aggregate metrics for the keywords in the keyword plan.
    • Added KeywordPlanAggregateMetricType.DEVICE to request device breakdown of the search volume metrics for all the keywords in the keyword plan.
    • The device breakdown will be returned in the GenerateHistoricalMetricsResponse.aggregate_metric_results.device_searches.
• ReachPlanService
  • Added Forecast.viewable_impressions and PlannedProductForecast.viewable_impressions which contain the number of times the ad's impressions were considered viewable.

Protos

• Updated the method comments in the proto library to include a list of possible errors that can be thrown for each method.

Recommendations

• Added Recommendation.marginal_roi_campaign_budget_recommendation. This recommendation suggests adjusting a campaign's budget if we predict that its ROI will go up.

Reporting

• Added support for querying SKAdNetwork metrics with segments.sk_ad_network_conversion_value and metrics.sk_ad_network_conversions.
  • The segments.sk_ad_network_conversion_value field is only selectable with other date segments on Customer and Campaign resources.
  • The metrics.sk_ad_network_conversions field can only be segmented by segments.sk_ad_network_conversion_value and other date segments on Customer and Campaign resources.
• Added click_view.keyword and click_view.keyword_info, which contains information about the keyword associated with the GCLID if one is available.
• Included request-id in the GoogleAdsService.SearchStream response and GoogleAdsFailure details.

Resources

• Added support for returning errors that specifically say which resources has exceeded the limit when ResourceCountLimitExceededError.RESOURCE_LIMIT is returned:
  • Added ResourceLimitTypeEnum to include which resource limit was exceeded.
  • Added resource_count_details to ErrorDetails to include details of the maximum limit of the resource and the current count of the resource type in the account.

Tools

• Updated the reporting reference documentation to include a new and improved interactive Google Ads Query Language query builder.

Video

• Added VIDEO_EFFICIENT_REACH to AdGroupType.

6.1.0 (2021-02-10)

The functionality and changes below were added in v6.1.0.

Account Management

• Added CustomerUserAccessInvitationService to manage access invitations extended to users for a Google Ads account.
• Added AuthorizationError.ACCESS_DENIED_FOR_ACCOUNT_TYPE.

Ads

• Added AdOperation.policy_validation_parameter to support specifying how policies are validated, similar to AdGroupAdOperation.policy_validation_parameter.
• Added YoutubeVideoAsset.youtube_video_title.
• Added the following errors to AssetLinkError:
  • IMAGE_NOT_WITHIN_SPECIFIED_DIMENSION_RANGE
  • INVALID_PINNED_FIELD
  • MEDIA_BUNDLE_ASSET_FILE_SIZE_TOO_LARGE
  • NOT_ENOUGH_AVAILABLE_ASSET_LINKS_FOR_VALID_COMBINATION
  • NOT_ENOUGH_AVAILABLE_ASSET_LINKS_WITH_FALLBACK
  • NOT_ENOUGH_AVAILABLE_ASSET_LINKS_WITH_FALLBACK_FOR_VALID_COMBINATION
  • YOUTUBE_VIDEO_REMOVED
  • YOUTUBE_VIDEO_TOO_LONG
  • YOUTUBE_VIDEO_TOO_SHORT

Campaigns

• Set response_content_type to MUTABLE_RESOURCE as a request parameter to return all the fields mutated in a mutate request for CampaignBidModifierService.
• Set response_content_type to MUTABLE_RESOURCE as a request parameter to return all the fields mutated in a mutate request for CampaignSharedSetService.
• Added CampaignError.HEC_AGREEMENT_REQUIRED.

Change History

• Added new resource types FEED, FEED_ITEM, CAMPAIGN_FEED, AD_GROUP_FEED, AD_GROUP_AD to ChangeEventResourceType.

Conversions

• Added ThirdPartyAppAnalyticsSettings.provider_name to support linking the third-party app analytics provider to ConversionAction.

Criteria

• Set response_content_type to MUTABLE_RESOURCE as a request parameter to return all the fields mutated in a mutate request for CustomerNegativeCriterionService.
• Set response_content_type to MUTABLE_RESOURCE as a request parameter to return all the fields mutated in a mutate request for SharedCriterionService.
• Added COMBINED_AUDIENCE to the list of possible values for CriterionType.

Feeds

• Added support for FEED_ITEM_SET_ID in MatchingFunction.function_string.
• Set response_content_type to MUTABLE_RESOURCE as a request parameter to return all the fields mutated in a mutate request for FeedMappingService.

Hotel Ads

• Added the values LOWEST_UNIQUE and ONLY_PARTNER_SHOWN to HotelPriceBucket in preparation for the upcoming changes to Hotel Ads pricing buckets. These values will not be returned from the API until the date listed in the blog post, but you can start development preparing for this change now.

Recommendations

• Added support for ResponsiveSearchAdRecommendation.

Reporting

• Added the following conversion-related fields:
  • Metrics.all_conversions_value_by_conversion_date
  • Metrics.all_conversions_by_conversion_date
  • Metrics.conversions_value_by_conversion_date
  • Metrics.conversions_by_conversion_date
  • Metrics.value_per_all_conversions_by_conversion_date
  • Metrics.value_per_conversions_by_conversion_date
• Updated the following fields to be selectable with Segments.hour.
  • Metrics.all_conversions
  • Metrics.all_conversions_from_interactions_rate
  • Metrics.all_conversions_value
  • Metrics.cost_per_all_conversions
  • Metrics.value_per_all_conversions
• Added the call_view resource for reporting on call extensions and call only ads. This view provides equivalent functionality to the CALL_METRICS_CALL_DETAILS_REPORT in the AdWords API.

Resources

• Improved an error message thrown when a malformed resource name is passed by also showing the correct form. For example, customers/{customer_id}/customerUserAccesses/{user_id} instead of customers/{part_1}/customerUserAccesses/{part_2}.

6.0.0 (2020-11-05)

The functionality and changes below were added in v6.0.0.

Account Management

• Added CustomerUserAccess to support managing users in a Google Ads account.
• Added support for updates in AccountLinkService.

Ads

• Added ExtensionFeedItem.image_feed_item to support image extensions.
• Added ResponsiveDisplayAdInfo.control_spec.
• Added AdAsset.asset_performance_label and AdAsset.policy_summary_info to be used with responsive search ads.
• Added AssetFieldType.LEAD_FORM to support lead form extensions.
• Added Asset.policy_summary.
• Added MediaUploadError.MEDIA_UPLOAD_ERROR_CUSTOM_EXIT_NOT_ALLOWED.

Audiences

• Added UserList.match_rate_percentage for Customer Match user lists.
• Added UserData.user_attributes, UserIdentifier.user_identifier_source, and OfflineUserDataJobType.CUSTOMER_MATCH_WITH_ATTRIBUTES to support Customer Match with user attributes uploads.
• Added CombinedAudience to create the audience with AdGroupCriterion.combined_audience and CampaignCriterion.combined_audience for targeting.
• Added CustomAudience with AdGroupCriterion.custom_audience and CampaignCriterion.custom_audience for targeting.
• Uploading STORE_SALES_UPLOAD_THIRD_PARTY data with OfflineUserDataJobService will require user_identifier_source to specify whether a user identifier is first-party or third-party.

Bidding

• Added BiddingStrategy.maximize_conversion_value and BiddingStrategy.maximize_conversions to support these bidding strategies as portfolio bidding strategies.
• Added MaximizeConversions.target_cpa.

Billing

• Added the following fields to Invoice:
  • adjustments_subtotal_amount_micros
  • adjustments_tax_amount_micros
  • adjustments_total_amount_micros
  • regulatory_costs_subtotal_amount_micros
  • regulatory_costs_tax_amount_micros
  • regulatory_costs_total_amount_micros
• Removed Invoice.invoice_level_adjustment_micros.

Campaigns

• Added segment:
  • segments.ad_destination_type

Change History

• Added the resource ChangeEvent to retrieve the Change History of a Google Ads account. This is similar to Change History in the UI, including retrieving what interface made the change and who made the change.

Client libraries

• The API finished moving towards using field presence such as optional string and optional double instead of wrapper types such as StringValue and DoubleValue. Your code will be easier to use and more concise with payloads that are significantly smaller. Approximately half of our resources have been updated in this release; the other half was updated in v5. The full list is in the migration guide, and our code examples have been updated.
• Added a separator (~) for compound IDs in resource name patterns. For example, in ad_group_ad.proto, customers/{customer}/adGroupAds/{ad_group_ad} changed to customers/{customer_id}/adGroupAds/{ad_group_id}~{ad_id}.

Criteria

• Added support for feed item sets in location criterion with:
  • LocationGroupInfo.feed_item_sets
  • LocationGroupRadiusUnits.MILLI_MILES
  • CriterionError.CANNOT_SET_GEO_TARGET_CONSTANTS_WITH_FEED_ITEM_SETS, CriterionError.INVALID_LOCATION_GROUP_RADIUS, CriterionError.INVALID_LOCATION_GROUP_RADIUS_UNIT
• Display names have been updated for some constants. The following fields are affected. See the migration guide for details:
  • CarrierConstant.name
  • MobileDeviceConstant.name
  • OperatingSystemVersionConstant.name
• Added CriterionError.CANNOT_TARGET_PLACEMENTS_FOR_SEARCH_CAMPAIGNS.

Feeds

• Set response_content_type to MUTABLE_RESOURCE as a request parameter to return all the fields mutated in a mutate request for FeedItemTargetService.

Planning

• Added ProductMetadata.plannable_product_name which contains the name of the product.
• Replaced ReachForecast.forecasted_product_allocations with ReachForecast.planned_product_reach_forecasts; planned_product_reach_forecasts contains budget allocations and forecasts for each product.

Recommendations

• Added Customer.optimization_score_weight. This is only available for non-manager accounts and is used to determine the overall optimization score of the manager account. Retrieve the optimization score and optimization score weight of sub-accounts and multiply them (Customer.optimization_score * Customer.optimization_score_weight) to determine the overall optimization score.
• Added support for the recommendation type FORECASTING_CAMPAIGN_BUDGET.

Reporting

• Updated Metrics.conversions_value_per_cost to be selectable with KeywordView.

5.0.0 (2020-08-26)

The functionality and changes below were added in v5.0.0.

Account Management

• Replaced AccountLinkOperation.create with AccountLinkService.CreateAccountLink. Added ThirdPartyAppAnalyticsLinkService.RegenerateShareableLinkId. This is for customers on an allowlist. Added the following to support this feature:
  • AccountLinkStatus.REQUESTED
  • AccountLinkStatus.PENDING_APPROVAL
  • LinkedAccountType.DATA_PARTNER
  • LinkedAccountType.GOOGLE_ADS
  • AccountLink.data_partner
  • AccountLink.google_ads
• Added errors:
  • AccountLinkError
  • ThirdPartyAppAnalyticsLinkError
• Renamed the following errors:
  • AuthorizationError.DEVELOPER_TOKEN_NOT_WHITELISTED to AuthorizationError.DEVELOPER_TOKEN_NOT_ON_ALLOWLIST.
  • FieldError.BLACKLISTED_VALUE to FieldError.BLOCKED_VALUE
  • NotWhitelistedError to NotAllowlistedError.
  • NotWhitelistedError.CUSTOMER_NOT_WHITELISTED_FOR_THIS_FEATURE to NotAllowlistedError.CUSTOMER_NOT_ALLOWLISTED_FOR_THIS_FEATURE.

Ads

• Updated AdGroupAd.policy_summary to make subfields selectable and to make non-repeated subfields filterable.
• Added MediaImage.full_size_image_url and MediaImage.preview_size_image_url.
• Added MediaBundle.url.
• Updated AdGroupAdAssetView to return removed assets.
• Renamed AssetError.CUSTOMER_NOT_WHITELISTED_FOR_ASSET_TYPE to AssetError.CUSTOMER_NOT_ON_ALLOWLIST_FOR_ASSET_TYPE.
• Added errors:
  • AssetLinkError.UNSUPPORTED_FIELD_TYPE
  • AssetLinkError.FIELD_TYPE_INCOMPATIBLE_WITH_ASSET_TYPE
  • AssetLinkError.FIELD_TYPE_INCOMPATIBLE_WITH_CAMPAIGN_TYPE
  • MediaUploadError.ANIMATED_VISUAL_EFFECT
  • MediaUploadError.ANIMATION_TOO_LONG
  • MediaUploadError.ASPECT_RATIO_NOT_ALLOWED
  • MediaUploadError.AUDIO_NOT_ALLOWED_IN_MEDIA_BUNDLE
  • MediaUploadError.CMYK_JPEG_NOT_ALLOWED
  • MediaUploadError.FLASH_NOT_ALLOWED
  • MediaUploadError.FRAME_RATE_TOO_HIGH
  • MediaUploadError.GOOGLE_WEB_DESIGNER_ZIP_FILE_NOT_PUBLISHED
  • MediaUploadError.IMAGE_CONSTRAINTS_VIOLATED
  • MediaUploadError.INVALID_MEDIA_BUNDLE
  • MediaUploadError.INVALID_MEDIA_BUNDLE_ENTRY
  • MediaUploadError.INVALID_MIME_TYPE
  • MediaUploadError.INVALID_PATH
  • MediaUploadError.LAYOUT_PROBLEM
  • MediaUploadError.MALFORMED_URL
  • MediaUploadError.MEDIA_BUNDLE_NOT_ALLOWED
  • MediaUploadError.MEDIA_BUNDLE_NOT_COMPATIBLE_TO_PRODUCT_TYPE
  • MediaUploadError.MEDIA_BUNDLE_REJECTED_BY_MULTIPLE_ASSET_SPECS
  • MediaUploadError.TOO_MANY_FILES_IN_MEDIA_BUNDLE
  • MediaUploadError.UNSUPPORTED_GOOGLE_WEB_DESIGNER_ENVIRONMENT
  • MediaUploadError.UNSUPPORTED_HTML5_FEATURE
  • MediaUploadError.URL_IN_MEDIA_BUNDLE_NOT_SSL_COMPLIANT
  • MediaUploadError.VIDEO_FILE_NAME_TOO_LONG
  • MediaUploadError.VIDEO_MULTIPLE_FILES_WITH_SAME_NAME
  • MediaUploadError.VIDEO_NOT_ALLOWED_IN_MEDIA_BUNDLE

Audiences

• Renamed the following errors:
  • OfflineUserDataJobError.NOT_WHITELISTED_FOR_USER_ID to OfflineUserDataJobError.NOT_ON_ALLOWLIST_FOR_USER_ID
  • OfflineUserDataJobError.NOT_WHITELISTED_FOR_STORE_SALES_DIRECT to OfflineUserDataJobError.NOT_ON_ALLOWLIST_FOR_STORE_SALES_DIRECT
  • OfflineUserDataJobError.NOT_WHITELISTED_FOR_UNIFIED_STORE_SALES to OfflineUserDataJobError.NOT_ON_ALLOWLIST_FOR_UNIFIED_STORE_SALES
  • UserListError.ADVERTISER_NOT_WHITELISTED_FOR_USING_UPLOADED_DATA to UserListError.ADVERTISER_NOT_ON_ALLOWLIST_FOR_USING_UPLOADED_DATA

Batch jobs

• Removed BatchJobOperation.remove as jobs in a PENDING state will automatically be removed after 1 day.
• Added BatchJobMetadata.start_date_time.

Bidding

• Added BiddingStrategy.effective_currency_code.
• Added campaign_bid_modifier to GoogleAdsService.Search and GoogleAdsService.SearchStream.
• Added support for Percent CPC in simulations:
  • Added PERCENT_CPC_BID to SimulationType.
  • Added percent_cpc_bid_point_list to AdGroupCriterionSimulation.
• Updated AdGroupBidModifier.criterion to be required on creation.
• Updated CampaignBidModifier.criterion to be required on creation.

Campaigns

• Added the ability to select segments.budget_campaign_association_status with campaign_budget. The campaign_id will always be returned in queries to the campaign_budget resource.
• Updated DynamicSearchAdsSetting.feeds to be settable.
• Updated Campaign.start_date and Campaign.end_date to be filterable.
• Added BudgetPeriod.CUSTOM_PERIOD.

Client libraries

• The API is moving towards using field presence such as optional string and optional double instead of wrapper types such as StringValue and DoubleValue. Your code will be easier to use and more concise with payloads that are significantly smaller. Approximately half of our resources have been updated in this release. The full list is in the migration guide, and our code examples have been updated. The rest of the resources will change to field presence in a future release.

Constants

• Added GeoTargetConstant.parent_geo_target.

Conversions

• Added ConversionActionError.UPDATE_NOT_SUPPORTED.

• Added the following values to ConversionActionTypeEnum.ConversionActionType:

  • ANDROID_APP_PRE_REGISTRATION
  • ANDROID_INSTALLS_ALL_OTHER_APPS
  • FLOODLIGHT_ACTION
  • FLOODLIGHT_TRANSACTION
  • GOOGLE_HOSTED
  • LEAD_FORM_SUBMIT
  • SALESFORCE
  • SEARCH_ADS_360
  • SMART_CAMPAIGN_AD_CLICKS_TO_CALL
  • SMART_CAMPAIGN_MAP_CLICKS_TO_CALL
  • SMART_CAMPAIGN_MAP_DIRECTIONS
  • SMART_CAMPAIGN_TRACKED_CALLS
  • STORE_VISITS

  More information about these conversion action types is available in the additional conversion action types guide.

Feeds

• Added ExtensionSettingError.DISALLOWED_TEXT.
• Renamed the following errors:
  • ExtensionFeedItemError.CUSTOMER_NOT_WHITELISTED_FOR_CALLTRACKING to ExtensionFeedItemError.CUSTOMER_NOT_ON_ALLOWLIST_FOR_CALLTRACKING
  • ExtensionSettingError.CUSTOMER_NOT_WHITELISTED_FOR_CALLTRACKING to ExtensionSettingError.CUSTOMER_NOT_ON_ALLOWLIST_FOR_CALLTRACKING
  • FeedItemValidationError.CUSTOMER_NOT_WHITELISTED_FOR_CALLTRACKING to FeedItemValidationError.CUSTOMER_NOT_ON_ALLOWLIST_FOR_CALLTRACKING

Hotel Ads

• Added a new service CampaignAssetService with AssetFieldType.BOOK_ON_GOOGLE and AssetLinkStatus to create Hotel Ads BOOK_ON_GOOGLE links.

Limits

• Added more detailed errors when a developer is exceeding either the account rate limits or the developer token rate limits. The error will include if it was the account or the developer token with details on the limit that was reached.

Planning

• Added KeywordPlanKeywordHistoricalMetrics.close_variants[] to return the close variant keywords that have been merged to compute the historical metrics.
• Added KeywordPlanService.GenerateForecastTimeSeries that returns the weekly forecast trend for Keyword Plan for the next 52 weeks.

Recommendations

• Added Recommendation TargetRoasOptInRecommendation.

Reporting

• Added ClickView.campaign_location_target and ClickView.user_list.

Request Parameters

• Set response_content_type to MUTABLE_RESOURCE as a request parameter to return all the fields mutated in a mutate request. This was added to some services including GoogleAdsService.Mutate. By default only the resource name is returned on a mutate.

Resources

• Added the feature to return metrics for entities that are not formally supported in the API such as Discovery campaigns. These entities will have type UNKNOWN returned in enum types. These are the fields that are affected:
  • AccountLink.type
  • Ad.type
  • AdGroupCriterion.type
  • Asset.type
  • Campaign.advertising_channel_sub_type
  • Campaign.advertising_channel_type
  • ChangeStatus.resource_type
  • ConversionAction.type
  • CustomInterest.type
  • DetailPlacementView.placement_type
  • GroupPlacementView.placement_type
  • MobileDeviceConstant.type
  • OfflineUserDataJob.status
  • SharedSet.type
  • UserList.type

Shopping

• Updated LandingPageView to include shopping metrics.

Video

• Added AdvertisingChannelSubType.VIDEO_SEQUENCE for video sequence campaigns.
• Added VideoResponsiveAdInfo for video responsive ads.
• Renamed the following metrics:
  • metrics.video_quartile_100_rate -> metrics.video_quartile_p100_rate
  • metrics.video_quartile_75_rate -> metrics.video_quartile_p75_rate
  • metrics.video_quartile_50_rate -> metrics.video_quartile_p50_rate
  • metrics.video_quartile_25_rate -> metrics.video_quartile_p25_rate

4.0.0 beta (2020-07-08)

The functionality and changes below were added in v4.0.0.

Account Management

• Added ThirdPartyAppAnalyticsLinkService and AccountLinkService. This lets users create a link between a third-party app and Google Ads. A user can use these links to import data and view metrics to manage campaigns.
• Added linked-customer-id to the request header. This header is only required for methods that update the resources of an entity when permissioned using Linked Accounts in the Google Ads UI (AccountLink resource in the Google Ads API). Set this value to the customer ID of the data provider that updates the resources of the specified customer ID. It should be set without dashes, for example 1234567890 instead of 123-456-7890. Learn more about Linked Accounts.
• Added CreateCustomerClientResponse.invitation_link, which is a link for inviting users to access the created customer. This is accessible to allowlisted customers only, and the allowlist is currently closed.

Ads

• Changed the format of AdGroupAdAssetView.resource_name from customers/{id}/adGroupAdAssets/{id} to customers/{id}/adGroupAdAssetViews/{id}.
• Added support for local ads with AdType.LOCAL_AD and Ad.local_ad.

Audiences

• Added support to remove user data by adding UserDataOperation.remove to UserDataService.
• Changed OfflineUserDataJob fields to have the correct annotation of Immutable:
  • external_id
  • type
  • customer_match_user_list_metadata
  • store_sales_metadata
• Added error values to OfflineUserDataJobError:
  • CUSTOM_KEY_DISABLED
  • CUSTOM_KEY_NOT_PREDEFINED
  • CUSTOM_KEY_NOT_SET
  • NOT_WHITELISTED_FOR_UNIFIED_STORE_SALES

Batch Jobs

• Renamed MutateJobService to BatchJobService. This service is not yet available for general use, but you can start coding against the service.

Bidding

• Added support for Target ROAS in simulations:
  • Added TARGET_ROAS to SimulationType.
  • Added target_roas_point_list to AdGroupSimulation.
• Updated AdGroup, AgeRangeView, KeywordView, and ParentalStatusView to be selectable with BiddingStrategy.

Billing

• Added CANNOT_CREATE_BUDGET_THROUGH_API to AccountBudgetProposalError.

Campaigns

• Added support for Local Campaigns. Create a local campaign by setting the Campaign.advertising_channel_type to LOCAL, Campaign.advertising_channel_sub_type to LOCAL_CAMPAIGN, Campaign.local_campaign_setting.location_source_type to GOOGLE_MY_BUSINESS, and Campaign.optimization_goal_setting to a value. You currently cannot filter on location when creating a Local campaign. Use the Google Ads UI or Google Ads Editor to do location filtering.
• Added SETTING_VALUE_NOT_COMPATIBLE_WITH_CAMPAIGN to SettingError.
• Added support to retrieve Smart campaigns with Campaign.advertising_channel_type set to SMART.

Conversions

• Added new values to ConversionActionType to include:
  • FIREBASE_ANDROID_FIRST_OPEN
  • FIREBASE_ANDROID_IN_APP_PURCHASE
  • FIREBASE_ANDROID_CUSTOM
  • FIREBASE_IOS_FIRST_OPEN
  • FIREBASE_IOS_IN_APP_PURCHASE
  • FIREBASE_IOS_CUSTOM
  • STORE_SALES
  • STORE_SALES_DIRECT_UPLOAD
  • THIRD_PARTY_APP_ANALYTICS_ANDROID_FIRST_OPEN
  • THIRD_PARTY_APP_ANALYTICS_ANDROID_IN_APP_PURCHASE
  • THIRD_PARTY_APP_ANALYTICS_ANDROID_CUSTOM
  • THIRD_PARTY_APP_ANALYTICS_IOS_FIRST_OPEN
  • THIRD_PARTY_APP_ANALYTICS_IOS_IN_APP_PURCHASE
  • THIRD_PARTY_APP_ANALYTICS_IOS_CUSTOM
• Added CREATION_NOT_SUPPORTED to ConversionActionError.

Criteria

• Added disapproval_reasons to AdGroupCriterion.
• Added income_range_view to retrieve income range metrics.

Hotel Ads

• Added support for booking on Google assets with AssetType.BOOK_ON_GOOGLE and Asset.book_on_google_asset.
• Added metrics.hotel_eligible_impressions.

Planning

• KeywordPlanIdeaService
  • Keyword ideas returned per query will generally be more relevant and fewer. We now try only to return keyword ideas that are more specific than the search term. Some examples:
    • A search for "jacket" returns "denim jacket" and "black windbreaker" but not "clothing".
    • A search for "vacuum" returns "lightweight vacuum" and "robot vacuum" but not "cleaning products".
    • A search for "dogs" returns "corgi" and "german shepherd" but not "animal".
    • If the keywords we return are too specific, try searching for a more general term.
  • Added fields for historical metrics in keyword plan ideas:
    • KeywordPlanHistoricalMetrics.monthly_search_volumes
    • KeywordPlanHistoricalMetrics.competition_index
    • KeywordPlanHistoricalMetrics.low_top_of_page_bid_micros
    • KeywordPlanHistoricalMetrics.high_top_of_page_bid_micros
  • Added GenerateKeywordIdeasRequest.include_adult_keywords so adult keyword ideas can be requested.
  • Added GenerateKeywordIdeasRequest.site_seed so keyword ideas can be generated for the site.
  • Added paging support to the GenerateKeywordIdeas method.
• KeywordPlanService
  • Added fields for historical metrics in keyword plans:
    • KeywordPlanHistoricalMetrics.monthly_search_volumes
    • KeywordPlanHistoricalMetrics.competition_index
    • KeywordPlanHistoricalMetrics.low_top_of_page_bid_micros
    • KeywordPlanHistoricalMetrics.high_top_of_page_bid_micros
  • Added KeywordPlanService.GenerateForecastCurve to generate a forecast curve for a plan. Curve provides forecast metrics for the keyword plan at different cost per click (CPC) bid points.
• Added KeywordPlanAdGroupKeywordService to manage keyword plan ad group keywords.
  • Both ad group positive and negative keywords are supported.
• Added KeywordPlanCampaignKeywordService to manage keyword plan campaign keywords.
  • Only campaign negative keywords are supported.
• Removed KeywordPlanKeywordService. The replacement is KeywordPlanAdGroupKeywordService.
• Removed KeywordPlanNegativeKeywordService. The replacement is either KeywordPlanAdGroupKeywordService or KeywordPlanCampaignKeywordService.
• Added errors:
  • KeywordPlanCampaignKeywordError
  • KeywordPlanAdGroupKeywordError
• Added GenerateReachForecastRequest.cookie_frequency_cap_setting to allow specifying a frequency cap time unit other than month to ReachPlanService.

Recommendations

• Added Customer.optimization_score.

Reporting

• Starting in v4, segments.date, segments.week, segments.month, segments.quarter, and segments.year will function as follows:
  • These segments can be filtered in the WHERE clause without being required in the SELECT clause.
  • If any of these segments are in the SELECT clause, at least one of these segments should have a finite date range specified in the WHERE clause.

Shopping

• Moved errors from AdGroupCriterionError to CriterionError:
  • INVALID_LISTING_GROUP_HIERARCHY
  • LISTING_GROUP_UNIT_CANNOT_HAVE_CHILDREN
  • LISTING_GROUP_SUBDIVISION_REQUIRES_OTHERS_CASE
  • LISTING_GROUP_REQUIRES_SAME_DIMENSION_TYPE_AS_SIBLINGS
  • LISTING_GROUP_ALREADY_EXISTS
  • LISTING_GROUP_DOES_NOT_EXIST
  • LISTING_GROUP_CANNOT_BE_REMOVED
  • INVALID_LISTING_GROUP_TYPE
  • LISTING_GROUP_ADD_MAY_ONLY_USE_TEMP_ID
• Renamed the following errors inside CriterionError:
  • PRODUCT_FILTER_TOO_LONG -> LISTING_SCOPE_TOO_LONG
  • PRODUCT_SCOPE_TOO_MANY_DIMENSIONS -> LISTING_SCOPE_TOO_MANY_DIMENSIONS
  • PRODUCT_PARTITION_TOO_LONG -> LISTING_GROUP_TOO_LONG
  • PRODUCT_PARTITION_TOO_MANY_DIMENSIONS -> LISTING_GROUP_TREE_TOO_DEEP
  • INVALID_PRODUCT_DIMENSION -> INVALID_LISTING_DIMENSION
  • INVALID_PRODUCT_DIMENSION_TYPE -> INVALID_LISTING_DIMENSION_TYPE
• Merged the following errors in CriterionError:
  • INVALID_PRODUCT_FILTER and INVALID_PRODUCT_DIMENSION -> INVALID_LISTING_DIMENSION
  • PRODUCT_SCOPE_TOO_LONG and PRODUCT_FILTER_TOO_LONG -> LISTING_SCOPE_TOO_LONG

3.1.0 beta (2020-04-29)

The functionality and changes below were added in v3.1.0.

Account Management

• Added errors:
  • ManagerLinkError.INVALID_CHANGE
  • ManagerLinkError.INVALID_STATUS_CHANGE

Ads

• Added errors:
  • AssetLinkError
  • MutateError.RESOURCE_READ_ONLY
  • MutateError.RESOURCE_DOES_NOT_SUPPORT_VALIDATE_ONLY

Audiences

• Added a new service OfflineUserDataJobService which supports asynchronous upload of Customer Match data and store sales (direct upload) data. These features have restricted access.
• Added a new service UserDataService for uploading small batches of Customer Match data concurrently. This feature has restricted access.

Billing

• Added support for retrieving the paying manager customer with PaymentsAccount.paying_manager_customer when making a request to PaymentsAccountService.ListPaymentsAccounts.
• Added errors:
  • AccountBudgetProposalError.OVERLAPS_EXISTING_BUDGET
  • CampaignBudgetError.TOTAL_BUDGET_AMOUNT_MUST_BE_UNSET_FOR_BUDGET_PERIOD_DAILY

Conversions

• Added new values to ConversionActionCategory to include:
  • ADD_TO_CART
  • BEGIN_CHECKOUT
  • BOOK_APPOINTMENT
  • CONTACT
  • ENGAGEMENT
  • GET_DIRECTIONS
  • IMPORTED_LEAD
  • OUTBOUND_CLICK
  • PHONE_CALL_LEAD
  • REQUEST_QUOTE
  • STORE_SALE
  • STORE_VISIT
  • SUBMIT_LEAD_FORM
  • SUBSCRIBE_PAID

Criteria

• Added errors:
  • CriterionError.CANNOT_SET_BIDS_ON_LISTING_GROUP_SUBDIVISION
  • CriterionError.DUPLICATE_LISTING_DIMENSION_TYPE
  • CriterionError.DUPLICATE_LISTING_DIMENSION_VALUE
  • CriterionError.LISTING_SCOPE_IN_OPERATOR_NOT_SUPPORTED
  • CriterionError.LISTING_SCOPE_TOO_MANY_DIMENSION_TYPES
  • CriterionError.LISTING_SCOPE_TOO_MANY_IN_OPERATORS

Hotel Ads

• AdGroupType.PROMOTED_HOTEL_ADS ad groups are now enabled for only allowlisted customers.

Recommendations

• Added support for retrieving campaign optimization score in Campaign.optimization_score.

Reporting

• Added support to segment metrics.content_impression_share by segments.hour.

Video

• Added support for retrieving video responsive ads.
  • Added AdGroupType.VIDEO_RESPONSIVE.
  • Added AdType.VIDEO_RESPONSIVE_AD.

3.0.0 beta (2020-02-27)

The functionality and changes below were added in v3.0.0.

Account Management

• Added errors:
  • CustomerManagerLinkError.TEST_ACCOUNT_LINKS_TOO_MANY_CHILD_ACCOUNTS
  • ManagerLinkError.CLIENT_OUTSIDE_TREE
• Added support for moving a client customer to a new manager customer with CustomerManagerLinkService.MoveManagerLink.
• Added support for returning test customers in CustomerClient. Filter out test accounts using the CustomerClient.test_account field.

Ads

• Added errors:
  • AdError.AD_CUSTOMIZERS_MAY_NOT_BE_ADJACENT
  • AdError.PLACEHOLDER_CANNOT_HAVE_EMPTY_DEFAULT_VALUE
  • AdError.PLACEHOLDER_COUNTDOWN_FUNCTION_CANNOT_HAVE_DEFAULT_VALUE
  • AdError.PLACEHOLDER_DEFAULT_VALUE_MISSING
  • AdError.UNEXPECTED_PLACEHOLDER_DEFAULT_VALUE
  • AdError.UPDATING_AD_WITH_NO_ENABLED_ASSOCIATION
  • ImageError.IMAGE_CONSTRAINTS_VIOLATED
  • MediaUploadError.EXTERNAL_URL_NOT_ALLOWED
  • MediaUploadError.INVALID_URL_REFERENCE
  • MediaUploadError.MISSING_PRIMARY_MEDIA_BUNDLE_ENTRY
  • StringLengthError.EMPTY

Billing

• Updated PaymentsAccountService.ListPaymentsAccounts to return PaymentsAccountError.NOT_SUPPORTED_FOR_MANAGER_CUSTOMER when making a request to a manager account.
• Added errors:
  • BillingSetupError.PAYMENTS_ACCOUNT_INELIGIBLE_CURRENCY_CODE_MISMATCH
  • TimeZoneError

Campaigns

• Removed BiddingStrategy.page_one_promoted.
• Removed BiddingStrategy.target_outrank_share.
• Removed the following unused errors:
  • CampaignError.MISSING_UNIVERSAL_APP_CAMPAIGN_SETTING
  • SettingError.UNIVERSAL_APP_CAMPAIGN_SETTING_DUPLICATE_DESCRIPTION
  • SettingError.UNIVERSAL_APP_CAMPAIGN_SETTING_DESCRIPTION_LINE_WIDTH_TOO_LONG
  • SettingError.UNIVERSAL_APP_CAMPAIGN_SETTING_APP_ID_CANNOT_BE_MODIFIED
  • SettingError.TOO_MANY_YOUTUBE_MEDIA_IDS_IN_UNIVERSAL_APP_CAMPAIGN
  • SettingError.TOO_MANY_IMAGE_MEDIA_IDS_IN_UNIVERSAL_APP_CAMPAIGN
  • SettingError.MEDIA_INCOMPATIBLE_FOR_UNIVERSAL_APP_CAMPAIGN
  • SettingError.TOO_MANY_EXCLAMATION_MARKS
• Added errors:
  • CampaignError.SENSITIVE_CATEGORY_APP
  • BiddingError.BIDDING_STRATEGY_TYPE_INCOMPATIBLE_WITH_SHARED_BUDGET
  • InternalError.DEADLINE_EXCEEDED
• Updated TargetingSetting to include TargetingSetting.target_restriction_operations, which enables updating specific TargetingSetting.target_restrictions values.
• Removed the following unused enum values:
  • BudgetPeriod.CUSTOM
  • BudgetPeriod.FIXED_DAILY

Constants

• Added CurrencyConstantService to retrieve currency constants.

Conversions

• Added errors:
  • ConversionAdjustmentUploadError.TOO_MANY_ADJUSTMENTS
  • ConversionAdjustmentUploadError.TOO_MANY_ADJUSTMENTS_IN_REQUEST

Criteria

• Removed GAME from ContentLabelType.
• Added CriterionError.CANNOT_TARGET_USER_LIST_FOR_SMART_DISPLAY_CAMPAIGNS.

Feeds

• Added FeedItemTarget.status.
• Added errors:
  • CampaignFeedError.NO_EXISTING_LOCATION_CUSTOMER_FEED
  • ExtensionFeedItemError.CONCRETE_EXTENSION_TYPE_REQUIRED
  • ExtensionFeedItemError.SCHEDULE_END_NOT_AFTER_START
  • FeedError.CANNOT_HAVE_LOCATION_AND_AFFILIATE_LOCATION_FEEDS
  • FeedError.GMB_ACCESS_ERROR
  • FeedMappingError.ATTRIBUTE_FIELD_MAPPING_MISSING_FIELD

Hotel Ads

• Added PaymentMode.GUEST_STAY for Hotel commission campaign to allow creating and editing hotel pay per stay campaigns. This mode is only supported by campaigns with AdvertisingChannelType.HOTEL, BiddingStrategyType.COMMISSION, and BudgetType.HOTEL_ADS_COMMISSION.
• Added AdGroupType.PROMOTED_HOTEL_ADS to support the promoted hotels feature.

Reach Forecasting

• Added Network Type to the Targeting settings you can use in GenerateReachForecastRequest.

Reporting

• Streaming

  • Added the support of streaming results as GoogleAdsService.SearchStream. Compared with paging, where you need to send requests for every page you want to retrieve, streaming lets you send one request to the server that returns a stream to read a sequence of messages back.

• Querying

  • Introduced returning total results count when retrieving data from GoogleAdService.Search by setting return_total_results_count to true in the request; previous versions always returned the total result count. Setting this to true will incur a performance penalty.
  • Introduced multiple ways of returning summaries in results when retrieving data from GoogleAdService.Search by setting summary_row_setting. Previous versions had the setting return_summary_row, which has been removed in this version.
  • Added DatabaseError.REQUEST_TOO_LARGE to indicate that the request needs to be split into smaller requests.

• View - Dynamic Search Ads Search Term

  • Added fields to DynamicSearchAdsSearchTermView:
    • has_negative_keyword
    • has_matching_keyword
    • has_negative_url

• View - Geographic

  • Added segments.geo_target_country to geographic_view.

• View - Hotel Group

  • Added metric metrics.search_click_share to hotel_group_view.

• View - Hotel Performance

  • Added metric metrics.search_click_share to hotel_performance_view.

• View - User Location

  • Added segments.geo_target_country to user_location_view.

Shopping

• Renamed shopping objects and fields containing listing to product including:
  • ListingBrandInfo to ProductBrandInfo
  • ListingCustomAttributeInfo to ProductCustomAttributeInfo
  • ListingCustomAttributeIndex to ProductCustomAttributeIndex

Video

• Added error YoutubeVideoRegistrationError.VIDEO_NOT_ELIGIBLE.

2.2.0 beta (2019-09-25)

The functionality and changes below were added in v2.2.0.

Billing

• Added a restricted-access InvoiceService for retrieving information about monthly invoices for a specified billing setup. This service is currently not open for sign-ups.

Reporting

• Segments
  • segments.interaction_on_this_extension and segments.placeholder_type are now selectable with:
    • ad_group
    • ad_group_ad
    • campaign
  • segments.month_of_year is now selectable with:
    • ad_group
    • campaign
    • segments.ad_network_type
    • segments.day_of_week
• View - Genders
  • Added the ability to segment by segments.date in gender_view.
• View - Hotel Performance
  • Added the ability to segment by segments.hotel_price_bucket in hotel_performance_view.
• View - Shared Sets
  • Added the ability to select bidding_strategy and user_list resources when using shared_set as the main resource in GoogleAdsService.Search.
• View - User Locations
  • Added the ability to filter by resource_name in user_location_view.

2.1.0 beta (2019-08-08)

The functionality and changes below were added in v2.1.0.

Account Management

• Added time_zone, test_account, manager, descriptive_name, currency_code, and id to CustomerClient to make it easier to retrieve customers in an account hierarchy.

Ads

• Added ExpandedDynamicSearchAd.description2 to create and retrieve the second part of the ad description.

Audiences

• Added custom_affinity to CampaignCriterion to target Custom Affinity audiences.

Hotel Ads

• Added the ability to select metrics.hotel_price_difference_percentage.

Labels

• Added the ability to select campaign.labels with other compatible resources in GoogleAdsService.Search.

Reach Forecasting

• Introduced a restricted access ReachPlanService, which lets users accurately forecast the commercial reach of video campaigns on YouTube and Google Video Partner inventory. For more details, refer to the Reach Forecasting guide.

Reporting

Querying

• Added the ability to select campaign and campaign_shared_set when using shared_set as the main resource in GoogleAdsService.Search.
• Added the ability to select the bidding_strategy resource in
  • ad_group_audience_view
  • campaign_audience_view
  • display_keyword_view
  • gender_view
  • managed_placement_view
  • topic_view in GoogleAdsService.Search
• Added the ability to select the user_list resource in ad_group_audience_view and campaign_audience_view in GoogleAdsService.Search.
• Added the ability to segment by segments.date in campaign_audience_view.
• Added the ability to select segments.ad_network_type and segments.device in distance_view.

2.0.0 (2019-06-26)

The functionality and changes below were added in v2.0.0. This release contains breaking changes. For breaking changes, see the migration guide.

Account Management

• Updated CustomerService to allow users to add roles and emails on account creation. This is for allowlisted customers only and is not currently open for any new customers.

Ads

• Introduced AdService for updating existing ads that were created using AdGroupAdService. Updating ads maintains existing metrics. The ads that can be updated include:
  • ExpandedTextAdInfo
  • CallOnlyAdInfo
  • ResponsiveDisplayAdInfo
  • ResponsiveSearchAdInfo
  • ShoppingComparisonListingAdInfo
  • AppAdInfo
  • AppEngagementAdInfo
  • DisplayUploadAdInfo

Bidding

• For simulations (equivalent to Bid Landscapes in the AdWords API):
  • Added parent_required_budget_micros to BidModifierSimulationPoint.
  • Added views to CpvBidSimulationPoint.
  • Added support for SHOPPING campaigns in CampaignCriterionSimulation. All fields that are not compatible with shopping campaigns are noted in the comments.
  • Added support for SHOPPING and DISPLAY simulation in AdGroupCriterionSimulation.

Campaigns

• Added PRESENCE_OR_INTEREST to NegativeGeoTargetType and PositiveGeoTargetType.
• Renamed LOCATION_OF_PRESENCE to LOCATION in NegativeGeoTargetType and PositiveGeoTargetType.
• Updated the Campaign GeoTargetingType to default to PRESENCE_OR_INTEREST for NegativeGeoTargetType and PositiveGeoTargetType.

Criteria

• Added SOCIAL_ISSUES to ContentLabelType.

Feeds

• Introduced targeted_keyword in ExtensionFeedItem.
• Introduced PlaceholderType, and renamed FeedItemPlaceholderPolicyInfo.placeholder_type to placeholder_type_enum, using the enum rather than an integer.
• Updated ExtensionFeedItemService to support partial failure.
• Removed review extensions by removing ExtensionType REVIEW. This was already deprecated in AdWords API.

Hotel Ads

• Introduced segments.geo_target_country in the HotelPerformanceView.

Labels

• Added the ability to retrieve all label resource names associated with the AdGroup resource using AdGroup.labels.

Reporting

• Metrics
  • Introduced call metrics with reports including ExtensionFeedItem:
    • metrics.message_chats
    • metrics.message_impressions
    • metrics.message_chat_rate
  • Removed:
    • metrics.average_position
    • metrics.impression_reach
    • For other metrics to use, see this blog post.
  • Updated segments.click_type to NOT be compatible with:
    • metrics.view_through_conversions
  • Updated segments.device to be compatible with:
    • metrics.search_exact_match_impression_share
  • Updated segment.month_of_year to be compatible with:
    • metrics.cross_device_conversions
    • metrics.gmail_forwards
    • metrics.gmail_saves
    • metrics.gmail_secondary_clicks
• Querying
  • Introduced summary rows when retrieving data from GoogleAdService.Search() by setting return_summary_row to true in the request.
  • For GoogleAdsFieldService, the page size that can be passed in must be 1 to 10000 inclusive. Any other number now results in an INVALID_PAGE_SIZE error.
• Views - Ad Assets
  • Introduced the AdGroupAdAssetView resource for querying ad asset metrics.
• Views - Clicks
  • Updated ClickView to include ad group ad attributes.
• Views - Distance
  • Introduced the DistanceView resource (equivalent to the User Ad Distance Report in the AdWords API).
• Views - Geographic
  • Introduced the UserLocationView resource (equivalent to the Geo Performance Report where isTargetingLocation is false in the AdWords API).
  • Replaced country_geo_target_constant with country_criterion_id in GeographicView.

Video

• Introduced companion_banner in VideoBumperInStreamAdInfo and VideoNonSkippableInStreamAdInfo. Note that this is a breaking change for some people as this introduced a new field in an empty object.

1.3.0 (2019-05-22)

The functionality and changes below were added in v1.3.0.

Bidding

• When updating bidding strategies, you are no longer required to set required fields when updating non-required fields.

Campaign drafts and experiments

• Added support for campaign drafts and experiments with the CampaignDraft and CampaignExperiment resources (equivalent to Campaign Drafts and Experiments in the AdWords API).

Conversions

• Added the ability to turn on validation only for the methods UploadClickConversions, UploadCallConversions, and UploadConversionAdjustments.

Criteria

• Added CONNECTED_TV to Device.

Feeds

• Added campaign (targeted_campaign), ad group (targeted_ad_group), and location (targeted_geo_target_constant) targeting to ExtensionFeedItem.

Hotel Ads

• Added the following segments:
  • segments.hotel_rate_rule_id
  • segments.hotel_rate_type

Labels

• Added the ability to retrieve all label resource names associated with the Campaign resource using Campaign.labels.

Shopping

• Added support for Comparison Listing Ads:
  • SHOPPING_COMPARISON_LISTING_ADS campaign advertising channel sub type
  • SHOPPING_COMPARISON_LISTING_ADS ad group type
  • SHOPPING_COMPARISON_LISTING_AD ad type
  • COMPARISON_LISTING_AD click type
• Access is restricted to Comparison Shopping Service customers.

1.2.0 (2019-04-29)

The functionality and changes below were added in v1.2.0.

Ads

• Added AppEngagementAdInfo for managing App Campaigns for Engagement.
• Added DisplayUploadAdInfo for retrieving and managing ads of the following types:
  • HTML5_UPLOAD_AD
  • DYNAMIC_HTML5_EDUCATION_AD
  • DYNAMIC_HTML5_FLIGHT_AD
  • DYNAMIC_HTML5_HOTEL_RENTAL_AD
  • DYNAMIC_HTML5_JOB_AD
  • DYNAMIC_HTML5_LOCAL_AD
  • DYNAMIC_HTML5_REAL_ESTATE_AD
  • DYNAMIC_HTML5_CUSTOM_AD
  • DYNAMIC_HTML5_TRAVEL_AD
  • DYNAMIC_HTML5_HOTEL_AD
• Added the ability to select AdParameter in GoogleAdsService.
• Added TextAsset for retrieving text assets in ads.
• Added FULLY_LIMITED to PolicyTopicEntryType.

Campaigns

• Create App Campaigns for engagement by creating a Campaign and setting the advertising_channel_type to MULTI_CHANNEL and the advertising_channel_sub_type to APP_CAMPAIGN_FOR_ENGAGEMENT. This feature is currently allowlisted.

Bidding

• Added the ability to use pay-per-conversion bidding with PaymentMode.CONVERSIONS.
• Added simulations (equivalent to Bid Landscapes in the AdWords API) for:
  • Campaign criteria: CampaignCriterionSimulation.
  • Ad group criteria: AdGroupCriterionSimulation.
  • Ad groups: AdGroupSimulation.

Criteria

• Added display name to MobileApplicationInfo criteria (equivalent to MobileApplication.displayName in the AdWords API).
• Added LocationGroupInfo criteria (equivalent to LocationGroups in the AdWords API).

Feeds

• Added ad_schedules and device to ExtensionFeedItem.
• Added month_of_year, day_of_week, and cross_device_conversion segmentation to ExtensionFeedItem and FeedItem.
• Added the ability to select AdGroupAd with FeedItem.
• Added LocationFeedItem and AffiliateLocationFeedItem for read-only retrieval.
• Updated PromotionFeedItem.redemption_start and PromotionFeedItem.end_time to make them selectable in a flat ExtensionFeedItem.

Hotel Ads

• Added segment segments.hotel_user_set_dates to CampaignAudienceView and AdGroupAudienceView.
• Added the commission bidding strategy for hotel campaigns. In order to use this bidding strategy, you will need to set up a hotel Campaign with the following fields:
  • campaign_budget being the resource name for CampaignBudget of type HOTEL_ADS_COMMISSION
  • payment_mode set to CONVERSION_VALUE
  • commission defining the commission rate

Parameters in Google Ads Query Language

• A new component called PARAMETERS has been added to the Google Ads Query Language grammar. In this version, users can include campaign drafts when creating a query by including the parameter include_drafts. An example would be:
  • SELECT campaign.name, campaign.experiment_type, FROM campaign PARAMETERS include_drafts = true

Recommendations

• Added new Recommendations:
  • CallExtensionRecommendation
  • CalloutExtensionRecommendation
  • SitelinkExtensionRecommendation

Reporting

• Local Campaigns - Per store report
  • Added metrics for Local Campaigns known as the Per Store Report in the Locations tab of the UI. This report has conversion metrics for feed items; used for location and affiliate location feed items.
  • Added the following metrics for Campaign, Customer, and ExtensionFeedItem:
    • metrics.all_conversions_from_click_to_call
    • metrics.all_conversions_from_directions
    • metrics.all_conversions_from_menu
    • metrics.all_conversions_from_order
    • metrics.all_conversions_from_other_engagement
    • metrics.all_conversions_from_store_visit
    • metrics.all_conversions_from_store_website
• Views - Feed Placeholder View
  • Added the ability to select AdGroupAd, AdGroup, and Campaign with FeedPlaceholderView.
• Views - Geographic
  • Added the ability to select segments.geo_target_city, segments.geo_target_metro, and segments.geo_target_region with segments.date.
  • Added segments:
    • segments.geo_target_airport
    • segments.geo_target_county
    • segments.geo_target_district
    • segments.geo_target_most_specific_location
    • segments.geo_target_postal_code
    • segments.geo_target_state
• Views - Location View
  • Added segments to LocationView:
    • segments.month_of_year
    • segments.average_cpe
    • segments.engagement_rate
    • segments.engagements
• Views - Landing Pages
  • Added new LandingPageView and ExpandedLandingPageView resources (enhanced version of Landing Page Report in the AdWords API) along with related metrics:
    • metrics.mobile_friendly_clicks_percentage
    • metrics.speed_score
    • metrics.valid_accelerated_mobile_pages_clicks_percentage
• View - Search Terms
  • Added a new PaidOrganicSearchTermView resource (equivalent to Paid Organic Query Report in the AdWords API), along with the following new metrics and segments intended for use with this resource:
    • Segments:
      • segments.search_engine_results_page_type
    • Metrics:
      • metrics.combined_clicks
      • metrics.combined_clicks_per_query
      • metrics.combined_queries
      • metrics.organic_clicks
      • metrics.organic_clicks_per_query
      • metrics.organic_impressions
      • metrics.organic_impressions_per_query
      • metrics.organic_queries
  • The SearchTermView resource can now be segmented by the AdGroupAd resource.
  • segments.search_term_match_type is now compatible with segments.keyword.ad_group_criterion, segments.keyword.info.match_type, and segments.keyword.info.text.

1.1.0 (2019-03-27)

The functionality and changes below were added in v1.1.0.

Ads

• Introduced AssetService for managing assets for asset-based ads.
• Added ResponsiveDisplayAdInfo (equivalent to MultiAssetResponsiveDisplayAd in AdWords API).
• Added AppAdInfo (equivalent to UniversalAppAd in AdWords API).
• Added headline1 and headline2 fields to CallOnlyAdInfo.

Campaigns

• Create App Campaigns (equivalent to UniveralAppCampaignInfo in AdWords API) by creating a Campaign and setting the advertising_channel_type to MULTI_CHANNEL and the advertising_channel_sub_type to APP_CAMPAIGN.
• Create search dynamic ad groups by creating an ad group of type SEARCH_DYNAMIC_ADS.

Conversions

• Adjust conversions with the new ConversionAdjustmentUploadService.
• Upload call conversions with the UploadCallConversionsRequest in the ConversionUploadService.

Criteria

• AdGroupCriterion now includes exempt_policy_violation_keys for exemption requests.
• AdGroupCriterion now includes approval_status.
• SharedCriterion, CampaignCriterion, and AdGroupCriterion now include support for mobile_application.

Hotel Ads

• Added conversion metrics into HotelPerformanceView and HotelGroupView, including:
  • all_conversions
  • all_conversions_from_interactions_rate
  • all_conversions_from_interactions_value_per_interaction
  • all_conversions_value
  • all_conversions_value_per_cost
  • conversions
  • conversions_from_interactions_rate
  • conversions_from_interactions_value_per_interaction
  • conversions_value
  • conversions_value_per_cost
  • cost_per_all_conversions
  • cost_per_conversion
  • cross_device_conversions
  • value_per_all_conversions
  • value_per_conversion
• Added impression share metrics into HotelPerformanceView and HotelGroupView, including:
  • search_absolute_top_impression_share
  • search_budget_lost_absolute_top_impression_share
  • search_budget_lost_impression_share
  • search_budget_lost_top_impression_share
  • search_impression_share
  • search_rank_lost_absolute_top_impression_share
  • search_rank_lost_impression_share
  • search_rank_lost_top_impression_share
  • search_top_impression_share

Recommendations

• Added 2 Recommendation types:
  • MoveUnusedBudgetRecommendation
  • KeywordMatchTypeRecommendation

Reporting

• Segments
  • segments.device is now selectable with:
    • metrics.content_budget_lost_impression_share
    • metrics.content_impression_share
    • metrics.content_rank_lost_impression_share
  • CampaignBudget is now selectable with the following conversion segments:
    • segments.conversion_action
    • segments.conversion_action_category
    • segments.conversion_action_name
    • segments.external_conversion_source
• Views - Geographic
  • Added segments:
    • segments.geo_target_airport
• Views - Keywords
  • The metrics.cross_device_conversions field is now selectable with KeywordView.
  • DisplayKeywordView can now be segmented by segments.month_of_year.
• View - Placements
  • GroupPlacementView can now be segmented by segments.month_of_year.
  • GroupPlacementView now includes ad_network_type and engagement metrics including metrics.engagements and metrics.engagement_rate.
• View - Search Terms
  • DynamicSearchAdsSearchTermView can now be segmented by segments.webpage.
  • SearchTermView can now be segmented by segments.keyword.ad_group_criterion, segments.keyword.info.match_type, and segments.keyword.info.text.

1.0.0 (2019-02-27)

The functionality and changes below were added in v1.0.0.

Terms of Service

• The Terms and Conditions has changed. You'll need to accept the new Terms and Conditions and update your contact information in the API center. If you don't, you will get an error when trying to access v1.

  1. Sign in to the manager account where you have your developer token at ads.google.com.
  2. Click TOOLS & SETTINGS at the top of the page.
  3. Under SETUP, select API Center.
  4. Scroll down to API contact email, and update it.
  5. Scroll down to Principal place of business, accept the new conditions, and click Save.

Resource Names

• The delimiter separating IDs in all resource names has changed from underscore _ to tilde ~. When parsing resource names, update your code to take into account the new delimiter.

Account Management

• Added support for Labels.
  • The new LabelService lets developers add, modify, remove, and view labels.
  • Labels can be applied to and removed from resources using the AdGroupAdLabelService, AdGroupCriterionLabelService, AdGroupLabelService, CampaignLabelService, and CustomerLabelService.
• Introduced MerchantCenterLinkService for management of links between Google Ads and Google Merchant Center.

Ads

• Added Responsive Search Ads with ResponsiveSearchAdInfo.
• Renamed ResponsiveDisplayAdInfo to LegacyResponsiveDisplayAdInfo. Check out the recent blog post on Display ads for more details.
• Removed DynamicSearchAdInfo. If you are using DynamicSearchAdInfo, migrate your ads to ExpandedDynamicSearchAdInfo by March 6, 2019.
• Added product_images and product_videos to GmailAdInfo.
• Added ad_id_to_copy_image_from to ImageAdInfo.
• Added ad_strength to AdGroupAd.
• Added ad.system_managed_entity_source to AdGroupAd.

Audiences

• Introduced the CustomInterestService.

Batch Jobs

• Access to the batch jobs feature is currently restricted. We have released the services so you can start coding against this interface. Subscribe to the Google Ads API blog for updates when this feature will be available.
• Added MutateJobService to support submitting and monitoring asynchronous jobs containing large numbers of operations. Operations that are supported in the new service are documented in MutateOperation.

Bidding

• Added support for the Target Impression Share bidding strategy. This is a new BiddingStrategy that is available only in the Google Ads API.
• Added BiddingStrategy.status.

Billing

• The proposal_type field in the AccountBudgetProposal resource now returns a value for resources that previously returned UNKNOWN.
• The AccountBudgetProposalService no longer returns errors if a valid billing setup resource name is specified for operations that mutate an existing budget.

Campaigns

• Introduced DomainCategory to retrieve categories for a website.
• Added geo_target_type_setting to Campaign.

Change History

• ChangeStatusService now provides support for AdGroupBidModifier, AdGroupFeed, and CampaignFeed resources.

Conversions

• Introduced ConversionUploadService to enable uploading conversions from clicks.
• Added metrics.conversion_or_adjustment_lag_bucket and metrics.conversion_lag_bucket.

Criteria

• Introduced CustomerNegativeCriterionService.
• The AdGroupCriterion resource now has final_mobile_urls, final_url_suffix, and system_serving_status. This makes the system_serving_status available with the keyword_view.
• Added support for mobile_device in CampaignCriterion.
• Introduced the LanguageConstant.targetable field.
• Introduced support for CustomIntent and CustomAffinity criteria.

Feeds

• Introduced the CustomerExtensionSettingService, CampaignExtensionSettingService, and AdGroupExtensionSettingService to manage app, call, callout, message, price, promotion, review, sitelink, and structured snippet extensions.
• Introduced the ExtensionFeedItemService.
• Introduced the FeedItemTargetService.
• Introduced support for managing matching functions using structured objects/protos instead of strings in CustomerFeed, CampaignFeed, and AdGroupFeed.
• Campaign.dynamic_search_ad_setting.feed_ids was changed to campaign.dynamic_search_ads_setting.feeds so that feed IDs can be replaced by feed resources.
• FeedItemValidationError.extra_information was renamed to FeedItemValidationError.extra_info.
• In FeedItem, the type of the price_value field was changed from Price to Money.

Hotel Ads

• Added Hotel Ads click types to segments.click_type: HOTEL_PRICE, HOTEL_BOOK_ON_GOOGLE_ROOM_SELECTION.

Reporting

• Query Grammar
  • Changed the meaning of metrics and segments in GoogleAdsFieldService. These are now only returned for artifacts of category RESOURCE and they only contain the metrics and segments that are selectable when the given resource is in the FROM clause.

• Segments

  • Added segments.click_type.

  • Added segments for conversions:

    • segments.conversion_action
    • segments.conversion_action_category
    • segments.conversion_action_name
    • segments.conversion_adjustment
    • segments.external_conversion_source

  • Added ability to segment ads by keyword criteria with segments.keyword.info.match_type and segments.keyword.info.text for AdGroupAd.

  • Added segments.interaction_on_this_extension for FeedItem.

• Views - Ads

  • A new ClickView resource has been added. This is the equivalent of the Click Performance Report in the AdWords API. Consistent with the Click Performance Report, requests including the ClickView resource must specify a filter on a single day in the past 90 days.
  • Introduced the DynamicSearchAdsSearchTermView resource (equivalent to Keywordless Query Report in the AdWords API).

• Views - Bidding

  • Introduced the DetailPlacementView (equivalent to URL Performance Report in the AdWords API) and GroupPlacementView.
  • Added campaign_count and non_removed_campaign_count to bidding_strategy (equivalent to Bid Goal Performance Report in the AdWords API).

• Views - Feeds

  • Introduced the FeedPlaceholderView (equivalent of the Placeholder Report in the AdWords API).
  • Added more metrics and segments in FeedItem.
  • Added metrics for ExtensionFeedItem.

• Views - Geographic

  • Introduced the GeographicView resource (equivalent to the Geo Performance Report where isTargetingLocation is true OR there is no predicate on isTargetingLocation in the AdWords API).
  • Introduced the LocationView resource (equivalent to Campaign Location Target Report in the AdWords API).

• Zero Rows

  • Search queries that include at least one segment will no longer return rows where all selected metrics equal zero. Queries that don't include any segments are unchanged and will continue to return rows where all metrics equal zero. Unlike the existing AdWords API, there is no way to disable this behavior.

Shopping

• Added ProductBiddingCategoryConstantService (equivalent to Shopping Performance Report in the AdWords API).
• Bidding Categories are now supported in ListingDimensionInfo as a part of ListingGroups and ListingScopes.
• Added the ShoppingPerformanceView resource (equivalent to Shopping Performance Report in the AdWords API) which includes the following metrics and segments:
  • Metrics:
    • all_conversions
    • all_conversions_from_interactions_rate
    • all_conversions_value
    • average_cpc
    • clicks
    • conversions
    • conversions_from_interactions_rate
    • conversions_value
    • cost_micros
    • cost_per_all_conversions
    • cost_per_conversion
    • cross_device_conversions
    • ctr
    • impressions
    • search_absolute_top_impression_share
    • search_click_share
    • search_impression_share
    • value_per_all_conversions
    • value_per_conversion
  • Segments:
    • ad_group (resource)
    • ad_network_type
    • campaign (resource)
    • click_type
    • conversion_action
    • conversion_action_category
    • conversion_action_name
    • date
    • day_of_week
    • device
    • external_conversion_source
    • month
    • product_aggregator_id
    • product_bidding_category_level1
    • product_bidding_category_level2
    • product_bidding_category_level3
    • product_bidding_category_level4
    • product_bidding_category_level5
    • product_brand
    • product_channel
    • product_channel_exclusivity
    • product_condition
    • product_country
    • product_custom_attribute0
    • product_custom_attribute1
    • product_custom_attribute2
    • product_custom_attribute3
    • product_custom_attribute4
    • product_item_id
    • product_language
    • product_merchant_id
    • product_store_id
    • product_title
    • product_type_l1
    • product_type_l2
    • product_type_l3
    • product_type_l4
    • product_type_l5
    • quarter
    • week
    • year

Video

• Updated MediaVideo.ad_duration_millis to have millisecond precision as the precision used to only be out to the second while ending in 000.
• Added more metrics and segments compatible with Video (equivalent to Video Performance Report in the AdWords API).
• For reporting, added video types for Ad and MediaVideo.
• Added the ability to report on target CPM bidding strategies.

0.7.0 (2019-01-30)

The functionality and changes below were added in v0.7.0.

Ads

• Support for managing ad parameters with the AdParameterService.

Audiences

• Added support for the targeting setting in campaigns and ad groups.
• Added support for rule based, logical, and basic user lists.
• Added support for managing remarketing actions for a basic user list.

Billing

• Support for retrieving account-level budget proposals that were previously cancelled or rejected.

Campaigns

• CampaignGroups has been removed.

Change History

• Support for FEED and FEED_ITEM resources.

Client Accounts

• Introduced signal to identify if a customer is a test account.
• Introduced signal to identify if a customer is a manager account.
• Exposed conversion tracking settings of a customer.

Conversions

• Added support for retrieving current model attributed conversion metrics.
• Added support for retrieval of conversion actions using GoogleAdsService.Search.
• Added support for segmenting your conversion data by conversion_attribution_event_type.

Criteria and Location

• Added ability to create criterion with CriterionType MOBILE_APP_CATEGORY, WEBPAGE, OPERATING_SYSTEM_VERSION, and APP_PAYMENT_MODEL to identify when and where to show ads.
• Added ability to retrieve the canonical_name from the GeoTargetConstant.

Feeds

• Ad customizer stats are now returned with FeedItem stats.

Manager Accounts

• CustomerClientLink
  • Added `MutateCustomerClientLink() method, which modifies the customer client link in the manager account tree. These combinations are possible:
    • CustomerClientLinkOperation.create + ManagerLinkStatus.PENDING: Customer extends an invitation to a client.
    • CustomerClientLinkOperation.update + ManagerLinkStatus.CANCELED: Manager rescinds invitation.
    • CustomerClientLinkOperation.update + ManagerLinkStatus.INACTIVE: Manager terminates links.
    • CustomerClientLinkOperation.update + ManagerLinkStatus.ACTIVE with hidden field set to true: This makes an ACTIVE link hidden.
• CustomerManagerLink
  • Added MutateCustomerManagerLink method, which modifies the customer manager link in the manager account tree. These combinations are possible:
    • CustomerManagerLinkOperation.update + ManagerLinkStatus.ACTIVE: Client accepts invitation.
    • CustomerManagerLinkOperation.update + ManagerLinkStatus.REFUSED: Client declines invitation.
    • CustomerManagerLinkOperation.update + ManagerLinkStatus.INACTIVE: Client terminates invitation.

Request Parameters

• Set validate_only to true as a request parameter to only validate the request, but not perform it. This was added to all services including GoogleAdsService.Mutate.
• Set partial_failure to true as a mutate parameter to continue on failure and commit valid operations even if other operations in the same request failed.

Reporting

• All segment fields are now in a segments, which means all queries must be updated to include segments. before the segment field name.
• Additional metrics were added for ad groups, campaigns, budgets, campaign negative keywords, keywords, shared set criteria, campaign ad schedule targets, and bid goals including: absolute_top_impression_percentage, active_view_cpm, active_view_ctr, active_view_impressions, active_view_measurability, active_view_measurable_cost_micros, active_view_measurable_impressions, active_view_viewability, average_frequency, average_page_views, average_time_on_site, benchmark_average_max_cpc, cost_per_current_model_attributed_conversion, current_model_attributed_conversions, current_model_attributed_conversions_from_interactions_rate, current_model_attributed_conversions_from_interactions_value_per_interaction, current_model_attributed_conversions_value, current_model_attributed_conversions_value_per_cost, gmail_forwards, gmail_saves, gmail_secondary_clicks, historical_creative_quality_score, historical_landing_page_quality_score, historical_quality_score, historical_search_predicted_ctr, impression_reach, interaction_types, search_budget_lost_absolute_top_impression_share, search_click_share, search_rank_lost_absolute_top_impression_share, search_rank_lost_top_impression_share, search_top_impression_share, top_impression_percentage, and value_per_current_model_attributed_conversion.

Shopping

• Retrieve metrics.benchmark_average_max_cpc in Product Group View (previously known as Product Partition Report in the AdWords API).

Video

• Query standard campaigns with target_cpm_micros set in an AdGroup.
• Retrieve TrueView for Reach metrics.
• Retrieve video_brand_safety_suitability in a Campaign.
• Retrieve metrics.active_view_ctr.

0.6.0 (2018-11-29)

The functionality and changes below were added in v0.6.0.

Account Management

• CustomerClient resource
  • Returns the list of clients managed by the selected customer.
• CustomerService
  • Added `CreateCustomerClient() method, which creates a new client under the selected customer.
• CustomerService now supports mutates.
• New fields available in the [Customer](/google-ads/api/reference/rpc/v22/Customer) arefinal_url_suffixandtracking_url_template`.
• Descriptive name, currency, time_zone, final_url_suffix, tracking_url_template, auto_tagging_enabled, call_reporting_setting are now mutable.

Ads

• Create ads of type GMAIL_AD in AdGroupAdService.
• Create ads of type IMAGE_AD in AdGroupAdService.

Audiences

• Create audiences using UserListService.

Billing

• PaymentsAccountService (read-only service)
  • View a list of all billing accounts (refer to the BillingSetupService to designate a billing account to a billing setup).

Conversions

• Conversion actions return AMP tag snippets.

Criteria

• You can now create criteria with CriterionType LANGUAGE, CARRIER, USER_LIST, USER_INTEREST, and IP_BLOCK.

Feeds

• Manage feeds and retrieve feed metrics with AdGroupFeedService, CustomerFeedService, FeedService, CampaignFeedService, and FeedMappingService.

Hotel Ads

• Made following derived metrics compatible with the existing HotelGroupView resource:
  • average_cpc
  • average_cpm
  • ctr
• Added the HotelPerformanceViewService.
• Added the HotelPerformanceView resource
  • Note that the resource name for HotelPerformanceView is customers/<customer_id>/hotelPerformanceView

• Made HotelPerformanceView compatible with following metrics:

  • average_cpc
  • average_cpm
  • average_position
  • clicks
  • cost_micros
  • ctr
  • impressions
  • hotel_average_lead_value_micros

  These metrics can be segmented by

  • ad_network_type
  • date
  • day_of_week
  • device
  • hotel_booking_window_days
  • hotel_center_id
  • hotel_check_in_date
  • hotel_check_in_day_of_week
  • hotel_city
  • hotel_class
  • hotel_country
  • hotel_date_selection_type
  • hotel_length_of_stay
  • hotel_state
  • hour
  • month
  • partner_hotel_id
  • quarter
  • week
  • year

  The above metrics can also be segmented by the campaign and ad group resources. For example:

  select campaign.id, metrics.clicks from hotel_performance_view
  select ad_group.id, metrics.impressions from hotel_performance_view
  

Keyword Planning

• Published improved and extended version of Keyword Planning services keeping parity with Keyword Planner.

  • In order to accomplish this, we have introduced the Keyword Plan as a key concept. As with Keyword Planner, API users will be able to create Keyword Plans that can be accessed and modified at a later time. A Keyword Plan is much like any other Google Ads entity. As such, it is structured similarly to a standard serving campaign (KeywordPlan > KeywordPlanCampaign > KeywordPlanAdGroup > KeywordPlanKeyword).

    Much like campaigns, the full set of Keyword Plan entities need to be created in order to get Forecasted Metrics or Historical Metrics (Search Volume Data).

• KeywordPlanService.GenerateForecastMetrics

  • This service replaces the AdWords API's TrafficEstimatorService.get. It returns forecast metrics for all the keywords present in your KeywordPlan. It returns consistent forecast data with Keyword Planner offering forecast metrics at the keyword, ad group or campaign level.

• KeywordPlanService.GenerateHistoricalMetrics

  • This service replaces the AdWords API's TargetingIdeaService.get with RequestType=STATS; it returns historical metrics for all the canonicalized keywords present in your Keyword Plan. This means that if multiple KeywordPlanKeyword items are close variants of the same canonical keyword, a single version of the KeywordPlanKeyword will be returned along with historical metrics. This is consistent with Keyword Planner.

• [KeywordPlanIdeaService.GenerateKeywordIdeas](/google-ads/api/reference/rpc/v22/KeywordPlanService#generatekeywordideas`

  • This service replaces TargetingIdeaService.get with RequestType=IDEAS; it returns canonicalized keyword suggestions along with historical metrics. These keywords can be added to your Keyword Plans for forecasting or obtaining overall historical metrics for your plan. This is the only service which does not require a Keyword Plan to be created because it provides keyword suggestions to assist with plan creation.

Mutates

• Pass in multiple kinds of operations with GoogleAdsService.Mutate.

Recommendations

• Added the `DismissRecommendation() method to the RecommendationService, so that users can dismiss a recommendation.

Reports

• SearchTermView (known as Search Query Performance Report in the AdWords API).
  • The accompanying SearchTermMatchType segmentation was also added.

Shopping

• Standard Shopping Campaigns
  • CampaignCriterionService
    • Added support for ListingScopes ("product filters").
      • All dimensions except Bidding Category are available.
• Product Group View (known as Product Partition Report in the AdWords API).
  • Added benchmark_ctr metric.
  • Added search_absolute_top_impression_share metric.

Video

• The average_cpv metric is now available for tracking video stats.

0.5.0 (2018-10-31)

The functionality and changes below were added in v0.5.0.

Account Management

• CustomerService.ListAccessibleCustomers
  • Service for managing Google Ads accounts.

Billing

• BillingSetupService
  • Create a new billing setup.
  • Cancel an approved billing setup that is scheduled to start in the future.
  • Cancel a pending billing setup that is not yet approved.
• AccountBudgetService
  • View all approved account-level budgets, including budget adjustments.
  • View currently pending account-level budget proposals (if any).
• AccountBudgetProposalService
  • Create account-level budget proposal to update a budget or create a new budget.
  • View all account-level budget proposals. All approved values and proposed budget values are visible. Approved values are prefixed with approved_.

Campaigns

• Create campaigns with AdvertisingChannelSubType DISPLAY_GMAIL_AD for Gmail Ad campaigns and DISPLAY_SMART_CAMPAIGN for Smart Display campaigns.
• Query more Metrics for accounts, campaigns, ad groups, keywords, and bidding strategies.

Change history

• ResourceTypeEnum was renamed to ChangeStatusResourceTypeEnum.

Creatives

• MediaFileService
  • A service to upload media to be used in ads.
• Create call-only ads with CallOnlyAdInfo.
• Set and create the ad rotation mode on an ad group.
• Query Metrics such as impressions, clicks, cost, conversions, and average position for ads.

Conversion tracking

• Lets you measure the performance of your advertising against your business goals.
• Conversion actions
  • Set up and edit the settings associated with your conversion actions, including website tracking and call conversion tracking.

Hotel Ads

• Use Google Ads Query Language to query hotel group stats. For each hotel group:
  • Read the corresponding listing group case value.
  • Read direct child listing groups' types.
  • Read the parent listing group ID.
  • Read the listing group path, which contains the case value from the root node of the hotel group tree to the current hotel group.

Location, Demographics, and Criteria

• `GeoTargetConstantService
  • A service for retrieving geo constants and suggesting geo constants based on input.
• Create criterion with CriterionType AGE_RANGE, GENDER, INCOME_RANGE, PARENTAL_STATUS, PLACEMENT, PROXIMITY, TOPIC, YOUTUBE_CHANNEL, and YOUTUBE_VIDEO to identify when and where to show ads.
• Define placement in SharedCriterion.
• Retrieve Metrics for audiences, age ranges, display keywords, gender, parental status, and display topics.

Shopping

• `ProductGroupView resource
  • Supported metrics
    • all_conversions_from_interactions_rate
    • all_conversions
    • all_conversions_value
    • average_cpc
    • average_cpm
    • benchmark_average_max_cpc
    • clicks
    • conversions_from_interactions_rate
    • conversions
    • conversions_value
    • cost_micros
    • cost_per_all_conversions
    • cost_per_conversion
    • cross_device_conversions
    • ctr
    • impressions
    • search_click_share
    • search_impression_share
    • value_per_all_conversions
    • value_per_conversion
    • view_through_conversions
  • Supported segments
    • ad_network_type
    • date
    • day_of_week
    • device
    • month
    • month_of_year
    • quarter
    • week
    • Year

0.4.0 (2018-09-21)

The functionality and changes below were added in v0.4.0.

Allowlist removed

The allowlist for API access has been removed. All API users who have an existing developer token in the AdWords API can use that developer token for the Google Ads API.

Billing

• BillingSetupService

  • Designate the business entity responsible for an account's accrued costs.
  • Each billing setup is associated with a Payments account. All billing setups pointing to the same Payments account will appear on a single monthly invoice.
  • You can cancel a pending or future approved billing setup. Note that not all settable fields are exposed yet, including the billing setup's start and end times.
  • Note that creating or changing billing setups is not supported yet.

• AccountBudgetProposalService

  • Create new budgets and make changes to existing budgets, including:
    • edit existing budgets
    • end a currently running budget
    • remove a budget (approved to start in the future)
  • Cancel proposals that are still pending.
  • There are some fields that are currently settable, but are not yet selectable.
  • Approved values (where there is a discrepancy between the proposed budget value and the approved value) will be exposed as fields prefixed with approved_ in a future version.
  • Reads for account-level budgets managed by these proposals will be supported in a future version. Use BudgetOrderService until then.

Campaigns

• GoogleAdsService
  • Retrieve shared sets.
  • Retrieve campaign shared sets.

Change history

• ChangeStatus in GoogleAdService.Search
  • Retrieves the current status of resources that have changed since a requested time.
  • Supported resources are:
    • AD_GROUP
    • AD_GROUP_AD
    • AD_GROUP_CRITERION
    • CAMPAIGN
    • CAMPAIGN_CRITERION

Creatives

• The field policy_validation_parameter has been added to the AdGroupAdOperation. It enables setting policy topics that should be ignored so the ad can be saved despite having policy validations.
• The field policy_summary has been added to AdGroupAd to display the current approval status of an ad (including any policy violations ignored).
• The fields ad.added_by_google_ads and ad.device_preference were added in AdGroupAd.

Conversion tracking

Conversion tracking lets you measure the performance of your advertising against your business goals. The API will allow you to set up and edit your conversion tracking setup.

• With ConversionAction, you can set up and edit the settings associated with your conversion actions including website tracking and call conversion tracking.

Shopping

• Standard Shopping Campaigns
  • CampaignService
    • Create standard Shopping campaigns with SHOPPING.advertising_channel_type.
    • Supported bidding strategy types: MANUAL_CPC, TARGET_SPEND, TARGET_ROAS.
  • BiddingStrategyService
    • Create portfolio bidding strategy of types ENHANCED_CPC, TARGET_SPEND, TARGET_ROAS.
  • AdGroupService
    • Create ad groups of type SHOPPING_PRODUCT_ADS.
  • AdGroupAdService
    • Create ads of type SHOPPING_PRODUCT_AD.
  • AdGroupCriterionService
    • Subdivide product offers through listing groups, which represent product groups.
    • Supported listing dimension types:
      • Product Condition
      • Product Type
      • Listing Brand
      • Custom Attribute (L0-4)
      • Product Channel
      • Product Channel Exclusivity
      • Product Offer Id

Video

• GoogleAdsService
  • Retrieve information about your video campaigns from GoogleAdsService.Search.
• Video Ads
  • Video specific metrics
    • Video views, video view rate
    • Video quartiles
    • View-through conversions
• Video creatives
• ManualCPV bidding strategy

0.3.0 (2018-08-29)

Campaigns

The following were added or changed.

• CampaignService, AdGroupService
  • Create Display campaigns.
  • Set advertising_channel_type as it is now required.
• CampaignCriterionService
  • Set a campaign's ad schedule using CampaignCriterion.
• CampaignSharedSetService, SharedSetService, SharedCriterionService
  • Share negative keywords across campaigns.
• CampaignBidModifierService
  • Set campaign bid modifiers for CALL interaction types.
• AdGroupBidModifierService
  • Set ad group bid modifiers for criteria types:
    • HotelDateSelectionTypeInfo
    • HotelAdvanceBookingWindowInfo
    • HotelLengthOfStayInfo
    • HotelCheckInDayInfo
    • DeviceInfo

Creatives

• For ad disapproval error handling, PolicyFindingDetails replaces PolicyViolationDetails for expanded text ads.

Hotel Ads

• The parent_criterion_id (int64) in ListingGroupInfo has been replaced with parent_criterion. The new field is a string that contains the resource name of the parent criterion.

Queries

• GoogleAdsService
  • Filter by resource name in GoogleAdService.Search.
  • Segment by month_of_year.
  • Strings in queries must be quoted.

Recommendations

• Recommendations added:
• MaximizeConversionsOptInRecommendation
• EnhancedCpcOptInRecommendation
• MaximizeClicksOptInRecommendation
• SearchPartnersOptInRecommendation
• OptimizeAdRotationRecommendation
• The dismissed field was added to Recommendation resource to allow you to search, get, and apply dismissed recommendations.

Shopping

• Smart Shopping Campaigns
  • CampaignService
    • Create campaigns with advertising_channel_sub_type SHOPPING_SMART_ADS.
    • Supported bidding strategy type: MAXIMIZE_CONVERSION_VALUE.
  • AdGroupService
    • Create ad groups of type SHOPPING_SMART_ADS.
  • AdGroupAdService
    • Create ads of type SHOPPING_SMART_AD.
  • AdGroupCriterionService
    • Subdivide product offers through listing groups, which represent product groups.
      • Supported listing dimension types:
        • Product Condition
        • Product Type
        • Listing Brand
        • Custom Attribute (L0-4)

0.2.0 (2018-06-14)

Hotel Ads

• Added support for the PercentCpc bidding strategy. Check out the updated Hotel Ads guides for details.

0.1.0 (2018-06-05)

Campaigns

Search Campaigns

• CampaignCriterionService
  • Set bid modifiers for platforms.
  • Set bid modifiers and targeting for locations.
  • Configure Location and Platform criteria.
• GeoTargetConstantService
  • Query of geo targets.

Hotel Ads

• CampaignService, AdGroupService, AdGroupAdService
  • Create hotel campaigns linking to hotel center accounts.
• CampaignCriterionService
  • Set bid modifiers for platforms.
  • Set bid modifiers and targeting for locations.
• AdGroupBidModifierService
  • Set bid modifiers for itineraries:
    • Date selection
    • Advance booking window
    • Length of stay
    • Check-in day
• AdGroupCriterionService
  • Manipulate Hotel groups (listing groups).
• GeoTargetConstantService
  • Query geo targets needed for hotel ads.

Recommendations

• Recommendations include:
  • Keyword
  • CampaignBudget
  • TextAd (expanded text ads)
  • TargetCpaOptIn
• GoogleAdsService.Search
  • Search for Recommendations supports filtering and selecting with ad group, campaign, or campaign budget (depending on the Recommendation).
• RecommendationService
  • Apply Recommendations applies the recommendation as-is or overrides and applies the recommendation.
  • GetRecommendation retrieves one recommendation at a time and is meant for exploratory use rather than the retrieval of multiple recommendations. To retrieve multiple campaigns in one call, use GoogleAdsService.

Customer

• Customer.has_partners_badge is available for verifying if this customer has a Partners program badge.

0.0.0 (2018-04-23)

GoogleAdsFieldService

• GoogleAdsFieldService provides a catalog of all queryable fields. The metadata on these fields includes descriptions, types, and compatibility with other fields. Learn more.

GoogleAdsService

• GoogleAdsService is meant for retrieving multiple resources in a single query. Queryable resources include:

  • Customer
  • Campaign
  • AdGroup
  • AdGroupAd
  • CampaignBudget
  • BiddingStrategy

• Metrics such as impressions and clicks can also be retrieved using GoogleAdsService for these resources:

  • Customer
  • Campaign
  • AdGroup
  • AdGroupAd
  • CampaignBudget
  • BiddingStrategy
  • KeywordView (Keyword)

• GoogleAdsService segments by fields, such as date fields. Learn more.

Services for resources

CampaignService

• MutateCampaigns creates, updates, or removes search campaigns. It can also configure network settings and bidding strategies.

• GetCampaign retrieves one campaign at a time. It is meant for exploratory use rather than for retrieval of multiple campaigns. To retrieve multiple campaigns in a single call, use GoogleAdsService. Learn more.

CampaignBudgetService

• MutateCampaignBudgets creates, updates, or removes campaign budgets.

• GetCampaignBudget is meant for exploratory use rather than for retrieval of multiple campaign budgets. To retrieve multiple campaign budgets, use GoogleAdsService. Learn more.

AdGroupService

• MutateAdGroups creates, updates, or removes ad groups under search campaigns. It can also set bids on ad groups.

• GetAdGroup retrieves one ad group at a time. It is meant for exploratory use rather than for retrieval of multiple ad groups. To retrieve multiple ad groups, use GoogleAdsService. Learn more.

AdGroupAdService

• MutateAdGroupAds creates, updates, or removes ads in search campaigns. Supported ads are listed in AdType and include:

  • TEXT_AD
  • EXPANDED_TEXT_AD
  • DYNAMIC_SEARCH_AD
  • CALL_ONLY_AD
  • EXPANDED_DYNAMIC_SEARCH_AD

• GetAdGroupAd retrieves one ad at a time. It is meant for exploratory use rather than for retrieval of multiple ads. To retrieve multiple ads, use GoogleAdsService. Learn more.

BiddingStrategyService

• MutateBiddingStrategies creates, updates, or removes search campaign bidding strategies. Both standard and portfolio bidding strategies are supported.

• GetBiddingStrategy retrieves one bidding strategy at a time. It is meant for exploratory use rather than for retrieval of multiple bidding strategies. To retrieve multiple bidding strategies, use GoogleAdsService. Learn more.

CampaignCriterionService and AdGroupCriterionService

• MutateCampaignCriteria and MutateAdGroupCriteria create, update, or remove keyword criteria in search campaigns.

• GetCampaignCriterion and GetAdGroupCriterion retrieve one criterion at a time. They are meant for exploratory use rather than for retrieval of multiple criteria. To retrieve multiple criteria, use GoogleAdsService. Learn more.

CustomerService

• GetCustomer retrieves specific details about an account.