Tag Archives: adwords_api

Target Spend Migration for Maximize Clicks Bid Strategies

Starting January 18, 2021, we will start migrating Maximize Clicks bid strategies that still utilize the deprecated target_spend setting to use campaign daily budget pacing instead. This follows last year’s sunset of the target_spend field for Maximize Clicks. After that sunset went into effect, Google Ads has prevented users from creating any new Maximize Clicks strategies that have a target_spend setting.

What’s changing

As part of this migration, any Maximize Clicks bid strategies that still use the target_spend setting may have their maximum CPC bid limit lowered to minimize the performance impact that may result from this change. This would affect the following API fields:

Fields whose values may be lowered as part of the January 18, 2021, migration:
AdWords API Google Ads API
TargetSpendBiddingScheme.bidCeiling TargetSpend.cpc_bid_ceiling_micros

What you can do

You can avoid the above changes by removing the target spend setting on your campaigns’ bidding strategies before January 18, 2021. To do so, unset the following field (set its value to 0) on any existing Maximize Clicks bid strategies:

Fields to unset (set to 0) to avoid the migration:
AdWords API Google Ads API
TargetSpendBiddingScheme.spendTarget TargetSpend.spend_target_micros

If you have any questions or need additional help, contact us via the forum or at [email protected].

 Adam Ohren, Google Ads API Team

Google Ads and AdWords APIs upgrading authorization scope to "sensitive"

As of October 1, 2020, any Google Cloud app used to obtain credentials for the Google Ads API or AdWords API scope (https://www.googleapis.com/auth/adwords) in its projects (i.e. any new AdWords API or Google Ads API developers) will need to undergo a Google OAuth verification to avoid an unverified app screen for its users. An app, in this context, is defined as a unique OAuth 2.0 Client ID in Google Cloud. This verification is independent and in addition to any reviews conducted as part of the developer token approval process.

There is no cost for the Google verification, which typically completes in 3 to 5 business days. Information on how this process fits in the larger task of authorizing requests can be found in our guide. The verification status of a given app can be viewed at the OAuth consent screen of a Google Cloud Project.

Apps already using the Google Ads API or AdWords API scope prior to October 1, 2020 are not currently affected by this policy. However, this policy will be applied to all apps at a later date in 2021, and it is recommended that all apps undergo the Google OAuth verification process at their earliest convenience to avoid any business interruptions.

If you have any questions or need additional help, contact us via the forum or at [email protected].
- Devin Chasanoff, on behalf of the Google Ads API Team

Announcing the Google Ads API is out of beta

We are excited to announce that the Google Ads API is now generally available. This means you can use the Google Ads API for your production applications with confidence that prior performance issues have all been addressed. Batch processing is now available to everyone.

The AdWords API will continue to be supported. We will announce a deprecation schedule at a later date. We will continue to add more features in upcoming releases to reach full parity with the AdWords API.

Where can I learn more?
Get started with the following resources: If you have any questions or need additional help, contact us via the forum or at [email protected].
Nadine Wang, on behalf of the Google Ads API Team

Conversion Category Changes in AdWords API, Google Ads API, and Google Ads scripts

Since May 2020, when you sign in to your Google Ads account you may be prompted to upgrade each of your conversion actions to the new conversion categories. The updated conversion categories provide more granularity to describe the conversion actions that are the most meaningful for your business. More details can be found in this Google Ads Help Center article.

Starting October 15th 2020, these suggestions will be automatically applied if you haven’t already accepted them. Google Ads API, AdWords API and Google Ads Scripts users will see the following changes:

If you are using the Google Ads API, the new conversion categories are already available in ConversionActionCategoryEnum. No further action is needed.

If you are using the AdWords API, since we are not releasing a new version for the AdWords API, the new conversion category types will be translated to the existing ConversionTracker.Category enum values, based on the mapping below:
New Conversion Category ConversionTracker.Category
Add to cart LEAD
Begin checkout LEAD
Purchase PURCHASE
Subscribe (paid) PURCHASE
Subscribe (free) SIGNUP
Phone call leads LEAD
Offline lead LEAD
Submit lead form LEAD
Book appointment LEAD
Request quote LEAD
Get directions LEAD
Outbound click LEAD
Contact LEAD
Download DOWNLOAD
View key page PAGE_VIEW
Engagement DEFAULT
Store visit DEFAULT
Store sale PURCHASE
Other DEFAULT
Therefore, if you are using the AdWords API to retrieve conversion category types (via reports or services), you will still see existing conversion category types being returned based on the mapping above, which will be different from the migrated new types in Google Ads UI.

AdWords API users can still create conversion actions using the existing category types. The AdWords API will automatically translate the created conversions to new category types, based on machine learning models. You can find code examples on how to set category type for conversion actions on the AdWords API developer site.

If you are using Google Ads scripts, when you select or filter on the report field ConversionCategoryName, you will see the same existing category types as the ones used in AdWords API, based on the mapping in the above table.

If you have any questions or need additional help, contact us via the forum.
- Fei Xiang, Google Ads API Team

Announcing v5 of the Google Ads API beta

Today, we’re announcing the v5 release of the Google Ads API beta. To use the v5 features, you will need to upgrade your client libraries and client code. The updated client libraries and code examples will be published next week. For more information on breaking changes, see the migration guide.

Here are the highlights:
  • Return metrics for entities not formally supported in the API, such as Discovery campaigns, are now available. These entities will show UNKNOWN enum values returned. See the release notes for more details.
  • New request parameter to opt into returning all mutable fields in the response during a mutate.
  • 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 simplifies the API 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.
  • Subfields of AdGroupAd.policy_summary are now selectable. Non-repeated subfields of AdGroupAd.policy_summary are now filterable.
  • Support for Keyword Planner:
Where can I learn more?
The following resources can help you get started: 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

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

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

Update on the Google Ads API Beta

Since our last announcement in July, we've made several updates to improve the performance of the Google Ads API. Your feedback was essential to us in making these improvements and will continue to be throughout the remainder of the Beta.

What has been fixed?
Over the past several months, we've rolled out performance improvements to Google Ads API read and mutate functionality. Some of these updates are visible in recent versions of the API, such as the launch of GoogleAdsService.SearchStream() in v3_0, while other improvements have sped up the response times of existing services and methods.

What's next for the Google Ads API Beta?
It is our top priority to get the Google Ads API ready for general availability. This involves rolling out features for key user journeys, for example: a service for asynchronous batch updates. If you have any feedback on the API's readiness to address your tool's requirements, we'd like to hear from you!

Which API should I use?
Throughout the remainder of the Beta, the AdWords API will continue to be the primary API for programmatically accessing and managing Google Ads campaigns. When deciding whether to use the Google Ads API Beta to run production systems, please keep in mind that we may release updates in preparation for general availability. As a reminder, changes will be released in new versions of the Google Ads API Beta. They will not affect your existing code unless announced otherwise on this blog.

If you have any feedback or questions regarding the performance, feature availability and overall usability of the Google Ads API Beta, please contact us at [email protected].
-- The Google Ads API team

Reminder about sunset, creation of target spend field for Maximize Clicks strategies in Ads APIs

On July 31st, 2019 we began to sunset the target spend field for Maximize Clicks bidding strategies. At the time, the feature was only removed from the UI, and the Google Ads APIs were not impacted.

Starting on June 30th, 2020, we will continue to sunset the target spend field in the Google Ads APIs as per our original blog post. This will affect all versions of both the AdWords API and the Google Ads API. The following behaviors will be blocked:
  • Populating the target spend field on existing standard and portfolio strategies
  • Attaching portfolio strategies that have the deprecated field set to campaigns
Read on to see how this will affect your API usage:
Affected Target Spend Fields
Google Ads API campaign.target_spend.target_spend_micros
bidding_strategy.target_spend.target_spend_micros
AdWords API Campaign.BiddingStrategyConfiguration.TargetSpendBiddingScheme.spendTarget
SharedBiddingStrategy.TargetSpendBiddingScheme.spendTarget

Change Description
Any mutate operations that set a target spend field for the first time will return an error. You will be able to update a target spend field that currently contains a value, but you cannot set previously empty fields to a new value. Additionally, any operation attaching a bidding strategy to a campaign where that bidding strategy has a value set for a target spend field, will throw an error. To manage Target Spend on any new campaigns, we recommend using campaign budget. In each of these cases an error will be thrown.

Performing any of the actions listed above will generate one of the following errors:
  • OPERATION_NOT_PERMITTED_FOR_CONTEXT
  • UNSUPPORTED_FIELD_IS_SET
If you have any questions about this change or any other API feature, please contact us via the forum.
- Cory Liseno, Google Ads API Team