Category Archives: Ads Developer Blog

The official blog for information about the AdWords, AdSense, DoubleClick and AdMob APIs and SDKs

Stricter Validation For DCM/DFA Reporting and Trafficking API

On July 14th, 2020, we will begin enforcing stricter validation for requests to the DCM/DFA Reporting and Trafficking API. This change will initially be introduced for 5% of API traffic during the week of July 14, 10% the week of July 21, 30% the week of July 28, and all requests by August 7th, 2020. 
As a result, your requests might begin returning additional errors. Please update your requests, as needed. 

The following list includes the error codes that you might see, as well as the recommended solutions:
  • "Invalid value - Enum" - Ensure you are using valid enum values. For more information, see the API Reference.
  • "Invalid value - Bool" - Ensure boolean fields in the request are set to true/false, rather than empty string.
  • "Invalid value - Integer ####.0" - Ensure integer fields in the request are set to valid integers.
  • "Invalid JSON Payload - NaN" - Ensure NaN does not appear in the request payload.
  • "Invalid JSON payload received. - not repeating" - Do not use arrays for non-array fields.
Method specific errors:
  • dfareporting.reports.run: "Invalid JSON payload received. Unexpected end of string. Expected a value" - Ensure the request body is completely empty.
  • dfareporting.reports.list: "Request contains an invalid argument." - Ensure that empty fields in the response contain a valid value. For example, empty array fields must be specified by an empty array, rather than an empty string or object.
  • dfareporting.files.get and dfareporting.reports.files.get: "OAuth token was passed in the query parameter. Please send it in Authorization header instead." - Requests must use the HTTP header Authorization: Bearer [ACCESS_TOKEN] to pass OAuth credentials.

Why is this changing?
Stricter validation helps ensure that problematic requests are not silently ignored, and aligns the behavior of the DCM API with that of other Google APIs.
- Evan Chou, DCM API Team

Stricter Validation For DCM/DFA Reporting and Trafficking API

On July 14th, 2020, we will begin enforcing stricter validation for requests to the DCM/DFA Reporting and Trafficking API. This change will initially be introduced for 5% of API traffic during the week of July 14, 10% the week of July 21, 30% the week of July 28, and all requests by August 7th, 2020. 
As a result, your requests might begin returning additional errors. Please update your requests, as needed. 

The following list includes the error codes that you might see, as well as the recommended solutions:
  • "Invalid value - Enum" - Ensure you are using valid enum values. For more information, see the API Reference.
  • "Invalid value - Bool" - Ensure boolean fields in the request are set to true/false, rather than empty string.
  • "Invalid value - Integer ####.0" - Ensure integer fields in the request are set to valid integers.
  • "Invalid JSON Payload - NaN" - Ensure NaN does not appear in the request payload.
  • "Invalid JSON payload received. - not repeating" - Do not use arrays for non-array fields.
Method specific errors:
  • dfareporting.reports.run: "Invalid JSON payload received. Unexpected end of string. Expected a value" - Ensure the request body is completely empty.
  • dfareporting.reports.list: "Request contains an invalid argument." - Ensure that empty fields in the response contain a valid value. For example, empty array fields must be specified by an empty array, rather than an empty string or object.
  • dfareporting.files.get and dfareporting.reports.files.get: "OAuth token was passed in the query parameter. Please send it in Authorization header instead." - Requests must use the HTTP header Authorization: Bearer [ACCESS_TOKEN] to pass OAuth credentials.

Why is this changing?
Stricter validation helps ensure that problematic requests are not silently ignored, and aligns the behavior of the DCM API with that of other Google APIs.
- Evan Chou, DCM API Team

Announcing v4 of the Google Ads API beta

Today, we’re announcing the v4 release of the Google Ads API beta. To use the v4 features, update your client library. If you are upgrading from v1, v2, or v3, some of your code may require changes when you switch to the new v4 endpoint. For more information on breaking changes, see the migration guide. If you are using v1, upgrade by July 29, 2020.

Here are the highlights:
  • Local campaigns. Local campaigns streamline the process for you, making it easy to promote your stores across Google’s largest properties including the Google Search Network, Maps, YouTube, and the Google Display Network.
  • Support for retrieving and reporting on Smart campaigns.
  • Support for account-level optimization score.
  • Keyword Planning. See the Planning section in the release notes for details.
  • Linking third party app analytics accounts to Google Ads accounts. See the Account Management section in the release notes for details.
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 next week. If you have any questions or need additional help, contact us via the forum.
Nadine Wang, on behalf of the Google Ads API Team

Announcing v4 of the Google Ads API beta

Today, we’re announcing the v4 release of the Google Ads API beta. To use the v4 features, update your client library. If you are upgrading from v1, v2, or v3, some of your code may require changes when you switch to the new v4 endpoint. For more information on breaking changes, see the migration guide. If you are using v1, upgrade by July 29, 2020.

Here are the highlights:
  • Local campaigns. Local campaigns streamline the process for you, making it easy to promote your stores across Google’s largest properties including the Google Search Network, Maps, YouTube, and the Google Display Network.
  • Support for retrieving and reporting on Smart campaigns.
  • Support for account-level optimization score.
  • Keyword Planning. See the Planning section in the release notes for details.
  • Linking third party app analytics accounts to Google Ads accounts. See the Account Management section in the release notes for details.
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 next week. If you have any questions or need additional help, contact us via the forum.
Nadine Wang, on behalf of the Google Ads API Team

Incremental update to Display & Video 360 API v1

We’re launching an incremental update to the Display & Video 360 API v1 today. The update includes:


A more detailed summary of this update can be found on the Display & Video 360 API release notes page. You can take advantage of these additional features by updating your client library to the most recent version.

If you run into issues or need help using this new functionality, please contact us using our support contact form.
- Trevor Mulchay, Display & Video 360 API Team

Announcing Authorized Buyers’ new Real-Time Bidding API

Today we are pleased to announce the release of Authorized Buyers’ Real-Time Bidding API. In addition, we are also announcing that all versions of the Ad Exchange Buyer API are now deprecated, and will sunset by the end of Q1, 2021. With the exception of the Budgets resource that is not being carried over to the new API, we recommend migrating to the Real-Time Bidding API’s equivalent resources well before the sunset to avoid interruptions to your integration. Note that this deprecation does not include the Ad Exchange Buyer II API, which will continue to be supported.

The Real-Time Bidding API currently includes resources for managing creatives and user lists, and will be expanded in Q3 to include resources for managing pretargeting. Additional updates through Q3 and Q4 will add features for managing accounts and billing information, and retrieving performance reports. We recommend reading through the migration guide—which will be updated as new features are added to the Real-Time Bidding API—to learn more about getting started with the new API.

Feel free to reach out to us via the Authorized Buyers API forums if you have questions or feedback concerning the Real-Time Bidding API.

Mark Saniscalchi, Authorized Buyers Developer Relations

Share your feedback about the Ad Manager API

To learn more about what's working well and what could be improved, we're running a developer survey on the Ad Manager API. All questions are optional and your answers will be anonymous. We hope you'll take the opportunity to leave feedback on how we can make managing your network better.

Take the survey



The survey should take about 10 minutes to complete and will close on July 31, 2020. Thanks for helping us continue to improve developer experience for everyone.
 - Chris Seeley, Ad Manager API Team

Google Ads API beta v1 sunset reminder

Google Ads API beta v1 will sunset on July 29, 2020. After this date, all v1 API requests will begin to fail. Please migrate to a newer version prior to July 29, 2020 to ensure your API access is unaffected.

We've prepared various resources to help you with the migration: If you have questions while you’re upgrading, please reach out to us on the forum or at [email protected].
Nadine Wang, Google Ads API Team

Entity IDs as 64-bit in AdWords API, Google Ads API beta, Google Ads scripts, and Content API for Shopping

In the AdWords API, the Google Ads API beta, Google Ads scripts, and the Content API for Shopping, all entity IDs are 64-bit signed integers. They are of type:
  • xsd:long in the AdWords API
  • INT64 in the Google Ads API
  • number or string in Google Ads scripts
  • string in REST and as INT64 for client libraries in Content API for Shopping
Applications that integrate with the API should handle ID values in that range.

Historically, the following IDs were within the maximum value of 32-bit signed integer, but will soon be exceeding this range. Over the years, all of you have been so productive that we need to make sure 64-bit signed integers are available to allow the creation of more entities with unique IDs. This was announced starting in July 2019. To avoid any issues, please make sure your applications handle these IDs within a range of 64-bit signed integer values. Also make sure that your application is ready to support a 64-bit signed integer for any other entity IDs not listed below.

Which IDs are affected in the AdWords API and the Google Ads API beta?
AdWords API Google Ads API beta
Bidding Strategy BiddingStrategyConfiguration.bidding_strategy_id

BiddingStrategyId (multiple reports)		 BiddingStrategy.id
Budget BudgetOrder.id AccountBudget.id

BillingSetup.id
User List UserList.id

CriterionUserList.userListId

CLICK_PERFORMANCE_REPORT.UserListId

AUDIENCE_PERFORMANCE_REPORT.Id		 UserList.id
Shopping Campaigns ServiceLink.serviceLinkId

ShoppingSetting.merchantId

SHOPPING_PERFORMANCE_REPORT.MerchantId

SHOPPING_PERFORMANCE_REPORT.AggregatorId		 MerchantCenterLink.id

ShoppingSetting.merchant_id

segments.product_merchant_id

segments.product_aggregator_id
Conversion Action ConversionTracker.id

ConversionTrackerId (multiple reports)

ConversionTracker.originalConversionTypeId		 ConversionAction.id
Account Conversion Tracking Configuration ConversionTrackingSettings.effectiveConversionTrackingId ConversionTrackingSetting.conversion_tracking_id

ConversionTrackingSetting. cross_account_conversion_tracking_id




Which IDs are affected in Google Ads scripts?
JavaScript can only accurately represent integers up to 53 bits, so it's strongly advised that you begin treating all IDs in Google Ads scripts as string to avoid any possible future errors with high ID numbers.
Google Ads scripts
Bidding Strategy AdsApp.BiddingStrategy.getId()
Budget AdsApp.BillingAccount.getId()

AdsApp.BudgetOrder.getId()
User List AdsApp.Audience.getId()

AdsApp.ExcludedAudience.getId()

AdsApp.UserList.getId()

AdsApp.​ShoppingCampaignAudience.getAudienceId()

AdsApp.ShoppingCampaignAudienceBuilder.withAudienceId()

AdsApp.ShoppingCampaignAudienceSelector.withIds()

getAudienceId() and withAudienceId() for all Targeting -> Audience Search methods.



Which IDs are affected in the Content API for Shopping?
All IDs are returned as string in REST and as INT64 in the client libraries. If you convert IDs to a number in your application, please make sure the application can handle 64-bit signed integers. An example of this is merchant ID that is set in the client library’s configuration or in the REST URL.
Content API for Shopping
Merchant Center AccountIdentifier.merchantId

Order.merchantId

OrdersCustomBatchRequestEntry.merchantId

RegionalinventoryCustomBatchRequestEntry.merchantId

ProductsCustomBatchRequestEntry.merchantId

ProductstatusesCustomBatchRequestEntry.merchantId

AccountsCustomBatchRequestEntry.merchantId

OrderReportDisbursement.merchantId

OrderReportTransaction.merchantId

LocalinventoryCustomBatchRequestEntry.merchantId

ReturnpolicyCustomBatchRequestEntry.merchantId
Shopping Campaign AccountIdentifier.aggregatorId



Where can I get support?
If you have any API questions or need help, you can reach us at:
Nadine Wang, on behalf of the entire Google Ads Team

June update to Display & Video 360 API v1

Today we’re releasing an update to the Display & Video 360 API v1 which includes the following features: More detailed information about this update can be found on the Display & Video 360 API release notes page.

If you run into issues or need help using our new functionality, please contact us using our support contact form.
- Trevor Mulchay, Display & Video 360 API Team