Release Notes

1.1.0 (2019-03-27)

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

Ads

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

Criteria

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

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 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

Ads

Audiences

Batch Jobs

  • The batch jobs feature is currently whitelisted. We have released the services so you can start coding against this interface. Please 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

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

Change History

Conversions

Criteria

Feeds

Hotel Ads

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

Reporting

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

0.7.0 (2019-01-30)

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

Ads

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

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

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

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

Video

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
  • CustomerService now supports mutates.
  • New fields available in the Customer are final_url_suffix and tracking_url_template.
  • Descriptive name, currency, time_zone, final_url_suffix, tracking_url_template, auto_tagging_enabled, call_reporting_setting are now mutable.

Ads

Audiences

Billing

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

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

    • 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

Recommendations

Reports

Shopping

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

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

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.

Whitelist removed

The whitelist 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 (i.e., if 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. Please use BudgetOrderService until then.

Campaigns

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

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

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

0.1.0 (2018-06-05)

Campaigns

Search Campaigns

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 allows either applying the recommendation as-is or overriding and applying the recommendation.
    • GetRecommendation allows the retrieval of 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

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 allows segmentation 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.

Send feedback about...

This page
Documentation feedback
Google Ads API
Google Ads API
Product feedback
Need help? Visit our support page.