Tag Archives: adwords_api

AdFormat Change in AdWords API and Google Ads scripts Starting January 31, 2020

On January 31, 2020, the AdWords API and Google Ads scripts will start returning UNKNOWN for AdFormat in the Geo Performance Report. All other reports with AdFormat will not be affected. The Google Ads API is not affected as the field does not exist.

Please update your code where it uses these fields:
AdWords API Google Ads API Google Ads scripts
AdFormat in GEO_PERFORMANCE_REPORT NOT AFFECTED AdFormat in GEO_PERFORMANCE_REPORT

If you have any questions while updating your code, please reach out to us on our Google Ads API and AdWords API forum or our Google Ads scripts forum.
Nadine Wang, Google Ads API Team

Video and Channel IDs Change in AdWords API, Google Ads API, and Google Ads Scripts Starting November 15, 2019

On November 15, 2019, AdWords API, Google Ads API, and Google Ads scripts will start returning null ID criteria for YouTube channels and videos that have been deleted, due to changes in our data retention policy. The criteria itself remains for a given ad group, but referencing the video ID or channel ID for that criteria will return null.
  • In the AdWords API v201809, null values are returned as two dashes (--) in reporting.
  • In the Google Ads API, NULL values are returned as NULL values.
  • In Google Ads Scripts, null values are returned as null JavaScript values.
Please update your code where it uses these fields:
AdWords API Google Ads API Google Ads Scripts
YouTubeVideo.videoId YouTubeVideoInfo.video_id YouTubeVideo.getVideoId()
YouTubeChannel.channelId YouTubeChannelInfo.channel_id VideoYouTubeVideo.getVideoId()
Criteria in CAMPAIGN_CRITERIA_REPORT Media.getYouTubeVideoId()
Criteria in CRITERIA_PERFORMANCE_REPORT
Criteria in SHARED_SET_CRITERIA_REPORT

If you have any questions while updating your code, please reach out to us on our forum.
Nadine Sundquist, Google Ads API Team

Python 2 Deprecation in Google Ads API Client Library

On June 11, 2019 we deprecated support for Python 2 in the AdWords/Google Ad Manager client library for Python. As part of our previously announced plans, in mid-November 2019 we will be deprecating support in the Google Ads client library for Python as well.

When version 4.0.0 of the Google Ads client library for Python is released, we will officially end support for Python 2 and versions of Python 3 prior to 3.6.0.

If you use the Google Ads client library for Python, please take note of the following:
  • If you are already using Python version 3.6.0 or later, you can upgrade to Google Ads client library 4.0.0 and no other action is needed. If not, please do not upgrade to version 4.0.0 until you’ve upgraded to Python version 3.6.0 or later.
  • Version 4.0.0 will continue to support previous API versions such as v1_3 but we won't support client library issues related to Python 2 compatibility. For example, we won't release version 4.0.1 to fix a bug that only exists for Python 2 users.

If you have questions about the Python 3 migration, please submit an issue on the Google Ads client library repository’s Issues page, and for general API support please reach out to us on the Google Ads API forum.


Ben Karl, Google Ads API Team

Upcoming sunset of accelerated budget delivery

This is a reminder that, starting October 14, 2019, accelerated budget delivery will no longer be generally available in AdWords API, Google Ads API, and Google Ads scripts for use with shared budgets, search campaigns, and shopping campaigns.

We encourage all developers to review our announcement of the sunset, which has been recently updated to include the most up-to-date information on expected error codes that could be returned after this change goes into effect.

Please don’t hesitate to contact us via the AdWords API and Google Ads API Forum or the Google Ads scripts forum if you have any questions.

Adam Ohren, Google Ads API Team

Restricting Payments account usage across manager account hierarchies

Starting September 9, 2019, we are rolling out a change to prevent the same Payments accounts in the Google Ads API (billing accounts in the AdWords API) from being used across manager account hierarchies. Only valid Payments accounts belonging to the Google Ads manager account hierarchy can be used to create and update billing setups in the Google Ads API.

How does this affect you?
For your authenticated Google Ads client account Therefore, you may get fewer results from those API calls than before.

What do you need to do?
Google Ads API
When creating/updating a new billing setup, you will need to select a valid Payments account returned by PaymentsAccountService.ListPaymentsAccounts(). If you use an invalid Payments account during the above processes, the INVALID_PAYMENTS_ACCOUNT error will be thrown.


AdWords API
When creating a new budget order, you will need to specify a valid billingAccountId (the ID of a valid billing account returned by BudgetOrderService.getBillingAccounts()). If you use an invalid billingAccountId during the above process, the BudgetOrderError.INVALID_BILLING_ACCOUNT error will be thrown.

As always, if you have any questions, feel free to post your questions on the Google Ads API forum.

 - Thanet Knack Praneenararat, Google Ads API Team

Sunsetting accelerated budget delivery

Starting October 1, 2019, accelerated budget delivery will no longer be available for use with search campaigns, shopping campaigns, or shared budgets. This will affect budgets in all versions of the AdWords API, Google Ads API, and Google Ads scripts.

Google Ads will stop respecting the ACCELERATED delivery method setting on any budgets of the above types. Campaigns using such budgets will be automatically switched over to use standard delivery instead.

Note: When a new budget is created using the API or scripts, it is shared by default. Thus, a newly created budget will behave as STANDARD. To explicitly create a budget with ACCELERATED delivery, all of the following conditions will need to be met:
  • The budget’s isExplicitlyShared field is set to false
  • The budget’s delivery method is set to ACCELERATED
  • It is not associated with a search or shopping campaign
Fields and methods affected

Google Ads API campaign_budget.delivery_method
AdWords API Budget.BudgetDeliveryMethod
Google Ads scripts Budget.setDeliveryMethod()
Budget.getDeliveryMethod()

API applications and scripts that set the ACCELERATED delivery method will continue to function and will not return any errors when attempting to set the ACCELERATED fields on budgets. However, the setting will not have any effect for shared budgets, or for any budget attached to a search or shopping campaign; the setting will be defaulted to STANDARD delivery instead. Get or mutate responses from the AdWords API on any affected budgets will show the budgets as STANDARD.

The ACCELERATED delivery method may eventually be removed from future versions of the APIs and scripts for the affected budget and campaign types. We will provide additional details regarding any further changes in a later post.

If you have any questions about this change, please don’t hesitate to contact us via the AdWords API and Google Ads API Forum or the Google Ads scripts forum.

Adam Ohren, Google Ads API Team

Announcing v2_1 of the Google Ads API beta

Today we’re announcing the v2_1 releases of the Google Ads API beta. To use the v2_1 features via the new endpoint, please update update your client libraries. If you are upgrading from v1, some of your code may break when you switch to the new v2 endpoint. Please see the migration guide for more information on breaking changes.

Here are the highlights:
  • Introduced AdService for updating existing ads that were created using AdGroupAdService. Updating ads maintains existing metrics.
  • Introduced summary rows when retrieving data from GoogleAdService.Search() by setting return_summary_row to true in the request. The summary row contains the report totals.
  • Introduced the AdGroupAdAssetView resource for querying ad asset metrics.
  • Introduced the DistanceView resource (equivalent to the User Ad Distance Report in the AdWords API).
  • Introduced the UserLocationView resource (equivalent to the Geo Performance Report where isTargetingLocation is false in the AdWords API).
  • Added the ability to retrieve all label resource names associated with the AdGroup resource using AdGroup.labels and with the Campaign resource using Campaign.labels.
  • 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.
Where can I learn more?
The following resources can help you get going with the Google Ads API: The updated client libraries and code examples will be published by August 16. If you have any questions or need additional help, please contact us via the forum.

Nadine Sundquist, on behalf of the Google Ads API Team

Sunset of the Average Position Metric in AdWords and Google Ads APIs

In the week of September 30, 2019, the average position metric will be sunset. This change was announced this past February in the Google Ads Help Center. The new alternatives were described in this November 2018 blog post. Once the sunset occurs, requests for the average position (AdWords API, Google Ads API) will return NULL values.

In the AdWords API v201809, NULL values are returned as two dashes. In the Google Ads API, NULL values are returned as NullValues.

If you use ValueTrack parameters, we encourage you to remove the ValueTrack parameter {adposition} from your tracking templates. When average position is sunset, the ValueTrack parameter {adposition} will begin returning the empty string.

Note that average position has already been removed from the current beta version of the Google Ads API, but is accessible in the earlier V1_x versions.

In lieu of average position, we recommend you use the new metrics of Impression (Absolute Top) %" and "Impression (Top) %. These are the new metrics:

Absolute Top Metrics
AdWords API Google Ads API
AbsoluteTopImpressionPercentage absolute_top_impression_percentage
SearchAbsoluteTopImpressionShare search_absolute_top_impression_share
SearchBudgetLostAbsoluteTopImpressionShare search_budget_lost_absolute_top_impression_share
SearchRankLostAbsoluteTopImpressionShare search_rank_lost_absolute_top_impression_share


Top Metrics
AdWords API Google Ads API
TopImpressionPercentage top_impression_percentage
SearchTopImpressionShare search_top_impression_share
SearchBudgetLostTopImpressionShare search_budget_lost_top_impression_share
SearchRankLostTopImpressionShare search_rank_lost_top_impression_share


As always, don't hesitate to reach out to us on the developer forum with any questions.
, Google Ads API Team

Campaign IDs and Budget IDs as 64-bit in Google Ads

In the AdWords API and Google Ads API, Campaign IDs and Budget IDs are 64-bit signed integers and are of type xsd:long in the AdWords API and INT64 in the Google Ads API. Applications that integrate with the API should handle ID values in that range.

Historically, Campaign and Budget IDs in Google Ads were within the maximum value of 32-bit signed integer, but will soon be exceeding this range. In order to avoid any issues, please make sure your applications are fully compliant with IDs within a range of 64-bit signed integer values.

If you have any questions or concerns, please don't hesitate to contact us via the forum.
--Stan Grinberg, Google Ads API Team

Upcoming changes to App campaigns

We will be rolling out the improved version of App campaigns in the AdWords API and Google Ads API over the coming months. Please make sure you get your code ready before the migration of all campaigns to the new structure on August 6, 2019.

What's changing
Once this change is rolled out to a given account, all App campaigns for that account will immediately begin using the new fields. You will no longer use a UniversalAppCampaignSetting, which included both information about the app and references to media and descriptions that would be used for ads in that campaign.

Instead, you will specify an AppCampaignSetting in the Google Ads API (UniversalAppCampaignInfo in the AdWords API), which contains only basic details about the app you want to promote through advertising. All the specific ad-level details will be added in the new AppAdInfo in the Google Ads API (UniversalAppAd in the AdWords API). This improved structure allows you to have a single campaign for each app you want to advertise, and offers the flexibility to have a variety of different ads within that campaign.

For reporting, stats at the ad group level will be available in the Google Ads API only.

Update schedule
For this update, we are rolling out the changes in two phases.
  • On June 17, 2019, all test accounts will be updated to use the new App campaign settings. Starting on this date, you can write test code against a test account you own to ensure that your code is ready for the full migration.
  • On August 6, 2019, all Google Ads accounts will be updated to use the new App campaign settings. Make sure that you have tested and deployed your new code to adapt to the changes by this date.
If you have any questions or concerns, please don't hesitate to contact us via our forum.
- Mike Cloonan, Google Ads API Team