Tag Archives: google_ads_api

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]

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

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.

Google Ads API v2 sunset reminder

Google Ads API beta v2 will sunset on October 21, 2020. After this date, all v2 API requests will begin to fail. Please migrate to a newer version prior to October 21, 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].

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.

Changes to campaign_bid_modifier reporting in the Google Ads API

Starting on September 1, 2020, we will be making a change to how the Google Ads API reports campaign-level bid modifiers to make the API’s results more consistent with the Google Ads UI.

Currently, Google Ads Query Language queries for campaign_bid_modifier resources only return rows if either of the following conditions are met:
  1. A non-zero bid modifier is set, or
  2. The row’s associated criterion_id has accrued metrics for the CALLS interaction type.
After this change goes into effect, queries for campaign_bid_modifier resources will return rows for all campaigns, more closely matching what a user sees in the Google Ads UI’s Advanced bid adj. > Interactions screen.

Users who wish to keep using a restricted view of their campaign_bid_modifier reports can add a predicate such as “WHERE campaign_bid_modifier.bid_modifier != 1.0" (where a 1.0 value is equivalent to a bid adjustment of ±0%) to their queries to limit reporting to non-zero bid modifier rows.

This change will not affect the behavior of the AdWords API.

If you have any questions about this change, please reach out to us on the forum.

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.

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.

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

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: