Google Ads Developer Blog

Changes to Hotel Ads pricing buckets in the Google Ads API

2021-01-25T08:31:00.000-08:00

On February 23rd, Google Ads API will be changing the way Hotel price buckets returns data by utilizing two new values in the hotel_price_bucket segment. Those new values will be added as enums in v6_1, “Lowest Unique” and “Only partner shown”.

Because there is overlap between the two new values and the existing “Lowest tied” value, after February 23rd developers using API versions earlier than v6_1 will see reports with the “Unknown” value wherever the two new values would be shown. This can result in one or two rows with the “Unknown” value.

Example:
Currently, data for ONLY_PARTER_SHOWN and LOWEST_UNIQUE are not returned, instead data is only shown for LOWEST_TIED.

LOWEST_TIED 12

Once the changes are released on February 23rd, developers on API versions v6_1 and greater will see the two new ONLY_PARTER_SHOWN and LOWEST_UNIQUE values, with the two new price buckets being displayed.

`LOWEST_UNIQUE`	3
`ONLY_PARTER_SHOWN`	4
`LOWEST_TIED`	5

After the changes are released on February 23rd, any developers on API versions lower than v6_1 will see “UNKNOWN” where the new values would have otherwise been shown.

`UNKNOWN`	3
`UNKNOWN`	4
`LOWEST_TIED`	5

If you have any questions about this change or any other API feature, please reach out to your account team directly, or contact us via the forum.
- Cory Liseno, Google Ads API Team

Ad Policy Error Management is evolving in Google Ads API

2021-01-15T13:05:00.000-08:00

On March 1st, 2021, all versions of the Google Ads API will replace policy violations with policy findings for all remaining ad types.

The impact is limited to the creation and update of ads that trigger ad policy errors for the following types:

CALL_ONLY_AD
EXPANDED_DYNAMIC_SEARCH_AD
GMAIL_AD
HTML5_UPLOAD_AD
IMAGE_AD
LEGACY_APP_INSTALL_AD
LOCAL_AD
RESPONSIVE_DISPLAY_AD
RESPONSIVE_SEARCH_AD
VIDEO_RESPONSIVE_AD

If your application is impacted by this change and not upgraded before March 1st, 2021, then the ad policy errors will no longer be recognized and the requested exemptions will not be applied.

What’s Changing
Both AdGroupAdService.MutateAdGroupAds and AdService.MutateAds methods will behave differently:

Request: For each operation, the Google Ads API will only take into account the requested exemptions that are listed in PolicyValidationParameter.ignorable_policy_topics from the field policy_validation_parameter, not in PolicyValidationParameter.exempt_policy_violation_keys.
Response: The Google Ads API will only return ad policy errors as PolicyFindingErrors in the field GoogleAdsError.error_code and provide details as PolicyFindingDetails in the field GoogleAdsError.details, not as PolicyViolationErrors and PolicyViolationDetails.

What’s Not Changing

All the ad policies will remain and all the ad policy checks will still occur.
AdWords API
The ad policy status information AdGroupAdPolicySummary will remain accessible by querying the field AdGroupAd.policy_summary.

What to Do
Before March 1st, 2021, make sure to add the support of policy findings in your management of ad policy errors. To get started, you can refer to our guide and code example that are both dedicated to ad policy error management. We recommend testing with the ad types that already use policy findings: EXPANDED_TEXT_AD and RESPONSIVE_SEARCH_AD.

If you have any questions or need additional help, contact us through the forum or at googleadsapi-support@google.com.
Pierrick Voulet, Google Ads API Team

Update to Customer Match Uploads in the Google Ads API and the AdWords API Starting March 1, 2021

2021-01-12T09:41:00.000-08:00

On March 1, 2021, the Google Ads API and the AdWords API will have a new upload limit for each Customer Match upload request. There is no change to the limit of the overall Customer Match audience list size.

What code do I need to change?
When uploading user identifiers for Customer Match, check that the number of user identifiers you are uploading per request is within the limit.

	Google Ads API	AdWords API
Limit	100,000 per request	500,000 per user list ID per request
Method	`OfflineUserDataJobService.AddOfflineUserDataJobOperations()`	`AdWordsUserListService.mutateMembers()`
Field	`userIdentifiers`	`membersList`
Error on exceeding upload limit	`TOO_MANY_USER_IDENTIFIERS`	`TOO_MANY`

Why is this changing?
In order to make the processing of Customer Match user identifiers more efficient, we needed to set the new upload limit.

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

The google_global_site_tag will no longer be filterable in Google Ads API

2021-01-11T13:51:00.000-08:00

What's changing?
Starting the week of Jan 25, 2021, the customer.remarketing_setting.google_global_site_tag field will no longer be filterable in the Google Ads API. If you use this field in a WHERE clause of a GAQL query in a call to the GoogleAdsService.Search or GoogleAdsService.SearchStream method, you will receive a QueryError.PROHIBITED_FIELD_IN_WHERE_CLAUSE error. Similarly, the GoogleAdsFieldService.SearchGoogleAdsFields method will report this field as non-filterable. This change affects all versions of the Google Ads API.

What should you do?
Before Jan 25, 2021, review and modify your Google Ads API reporting queries to stop using the google_global_site_tag field for filtering purposes.

If you have any questions or need help, please contact us via the forum.
- Anash P. Oommen, Google Ads API Team

Google Ads API v3 sunset reminder

2021-01-07T06:53:00.000-08:00

Google Ads API v3 will sunset on February 10, 2021. After this date, all v3 API requests will begin to fail. Please migrate to a newer version prior to February 10, 2021 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 googleadsapi-support@google.com.

- Thanet Knack Praneenararat, Google Ads API Team

Live Webinar: Website Conversions & Audience Remarketing

2020-12-01T06:32:00.000-08:00

The Google Ads API Developer Relations team will be hosting a live webinar, Website Conversions & Audience Remarketing with the Google Ads API, on December 11 at 10 AM EST (3 PM GMT).

Mark your calendar

Prerequisites
In order to get the most out of this webinar, we suggest you develop a basic understanding of the Google Ads API. In order to learn more, please visit our API Overview documentation or check out this Google Ads API Overview workshop from 2019. In addition, you may find this post useful to learn how conversion tracking works in Google Ads.

Agenda
The webinar will cover the topics below and include code walkthroughs to demonstrate how to perform different actions with the Google Ads API client libraries. We will also be hosting a live Q&A at the end.

What conversion actions are
How to create and utilize conversion actions
How remarketing works in the Google Ads API
How to define different audience types
How to measure audience performance

Reminders
Feel free to add the event to your calendar. In addition, you can set a reminder for the event on YouTube by clicking the “Set reminder” button on the YouTube event page.

We look forward to sharing our knowledge of the Google Ads API with you and answering your questions. If you have any questions or need additional help, contact us via the forum or at googleadsapi-support@google.com.
- Devin Chasanoff, on behalf of the Google Ads API Team

Live Webinar: Intro to Reporting & the Google Ads Query Language

2020-11-18T09:54:00.000-08:00

The Google Ads API Developer Relations team will be hosting a live webinar, Intro to Reporting & the Google Ads Query Language, on December 4 at 10 AM EST (3 PM GMT).

Mark your calendar

Agenda
The webinar will cover the topics below and include code walkthroughs to demonstrate how to perform different actions with the Google Ads API client libraries. We will also host a live Q&A at the end.

Reporting in the Google Ads API vs. the AdWords API
Types of search requests you can perform with the Google Ads API
The syntax and structure of Google Ads Query Language queries
How to discover available fields to construct Google Ads Query Language queries

Prerequisites
In order to get the most out of this webinar, we suggest you develop a basic understanding of the Google Ads API. To learn more, please visit our API Overview documentation or check out this Google Ads API Overview workshop from 2019. In addition, you may find this guide useful to learn about reporting with the Google Ads API, though much of this information will be covered in the webinar.

Reminders
Feel free to add the event to your calendar. In addition, you can set a reminder for the event on YouTube by clicking the “Set reminder” button on the YouTube event page.

We look forward to sharing our knowledge of the Google Ads API with you and answering your questions. If you have any questions or need additional help, contact us via the forum or at googleadsapi-support@google.com.
- Devin Chasanoff, on behalf of the Google Ads API Team

Announcing v6 of the Google Ads API

2020-11-09T07:00:00.000-08:00

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

Here are the highlights:

The API now has Change History similar to the Google Ads UI with ChangeEvent including what interface and who made the changes.
You can now manage user access in your Google Ads account.
Maximize conversion value and maximize conversions are now available as portfolio bidding strategies, which includes Search.
The new Customer.optimization_score_weight helps you calculate your overall optimization score for your manager account.
New audience types are available including CombinedAudience and CustomAudience.

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

Target Spend Migration for Maximize Clicks Bid Strategies

2020-10-29T11:06:00.000-07:00

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 googleadsapi-support@google.com.

Adam Ohren, Google Ads API Team

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

2020-10-15T06:02:00.000-07:00

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 googleadsapi-support@google.com.
- Devin Chasanoff, on behalf of the Google Ads API Team

Announcing the Google Ads API is out of beta

2020-09-21T10:04:00.000-07:00

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 googleadsapi-support@google.com.
Nadine Wang, on behalf of the Google Ads API Team

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

2020-09-08T09:06:00.000-07:00

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

Google Ads API v2 sunset reminder

2020-08-27T12:52:00.000-07:00

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 googleadsapi-support@google.com.
- Thanet Knack Praneenararat, Google Ads API Team

Announcing v5 of the Google Ads API beta

2020-08-26T13:08:00.000-07:00

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:
- Added KeywordPlanKeywordHistoricalMetrics.close_variants to return the close variant keywords that have been merged to compute the historical metrics.
- Added KeywordPlanService.GenerateForecastTimeSeries that returns the weekly forecast trend for Keyword Plan for the next 52 weeks.

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

Changes to campaign_bid_modifier reporting in the Google Ads API

2020-07-10T06:17:00.000-07:00

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:

A non-zero bid modifier is set, or
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.
- Adam Ohren, The Google Ads API team

Announcing v4 of the Google Ads API beta

2020-07-08T14:14:00.000-07:00

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

Google Ads API beta v1 sunset reminder

2020-06-16T11:07:00.000-07:00

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 googleadsapi-support@google.com.
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

2020-06-15T01:30:00.000-07:00

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

	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:

AdWords API and Google Ads API beta forum or googleadsapi-support@google.com.
Google Ads scripts forum.
Content API for Shopping forum.

Nadine Wang, on behalf of the entire Google Ads Team

Update on the Google Ads API Beta

2020-05-26T10:01:00.000-07:00

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 googleadsapi-support@google.com.
-- The Google Ads API team

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

2020-05-18T09:15:00.002-07:00

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

Announcing v3_1 of the Google Ads API beta

2020-04-29T13:00:00.000-07:00

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

Here are the highlights:

Added support for retrieving campaign optimization score in Campaign.optimization_score.
Added new conversion action categories to ConversionActionCategory. See the release notes for details.
Added a new service OfflineUserDataJobService which supports asynchronous upload of Customer Match data and store sales (direct upload) data. These features are whitelisted.
Added support for retrieving the paying manager customer with PaymentsAccount.paying_manager_customer when making a request to PaymentsAccountService.ListPaymentsAccounts().

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, please contact us via the forum.
Nadine Wang, on behalf of the Google Ads API Team

Google Ads conversion reporting issues starting April 9

2020-04-10T18:23:00.000-07:00

Update (April 10, 2020 19:35 PST): Conversion data in all reports has been fixed.

An issue that impacted Google Ads reporting for Search and Shopping conversions occurring between April 9 and April 10 (Pacific Time) for advertisers using non-last click attribution models has been fixed and the data is now correct in all reports.
If you downloaded any of the fields in the table below or any derivative custom columns using the AdWords API, Google Ads API and Google Ads scriptsbetween April 9th 8:00 PM PST and April 10th 7:20 PM PST, you may have incorrect data in your systems. Please re-download the affected fields to ensure accurate conversions reporting.
We appreciate your patience as we worked to resolve this issue as quickly as possible.

AdWords API	Google Ads API beta
Conversions ConversionValue ConversionRate ValuePerConversion CostPerConversion AllConversions AllConversionValue AllConversionRate ValuePerAllConversion CostPerAllConversion CurrentModelAttributedConversions CurrentModelAttributedConversionValue ValuePerCurrentModelAttributedConversion CostPerCurrentModelAttributedConversion	metrics.all_conversions metrics.all_conversions_from_click_to_call metrics.all_conversions_from_interactions_rate metrics.all_conversions_from_interactions_value_per_interaction metrics.all_conversions_value metrics.all_conversions_value_per_cost metrics.conversions metrics.conversions_from_interactions_rate metrics.conversions_from_interactions_value_per_interaction metrics.conversions_value metrics.conversions_value_per_cost metrics.cost_per_all_conversions metrics.cost_per_conversion metrics.cost_per_current_model_attributed_conversion metrics.cross_device_conversions metrics.current_model_attributed_conversions metrics.current_model_attributed_conversions_from_interactions_rate metrics.current_model_attributed_conversions_from_interactions_value_per_interaction metrics.current_model_attributed_conversions_value metrics.current_model_attributed_conversions_value_per_cost metrics.value_per_all_conversions metrics.value_per_conversion metrics.value_per_current_model_attributed_conversion

AdWords API

Google Ads API beta

Conversions
ConversionValue
ConversionRate
ValuePerConversion
CostPerConversion
AllConversions
AllConversionValue
AllConversionRate
ValuePerAllConversion
CostPerAllConversion
CurrentModelAttributedConversions
CurrentModelAttributedConversionValue
ValuePerCurrentModelAttributedConversion
CostPerCurrentModelAttributedConversion

metrics.all_conversions
metrics.all_conversions_from_click_to_call
metrics.all_conversions_from_interactions_rate
metrics.all_conversions_from_interactions_value_per_interaction
metrics.all_conversions_value
metrics.all_conversions_value_per_cost
metrics.conversions
metrics.conversions_from_interactions_rate
metrics.conversions_from_interactions_value_per_interaction
metrics.conversions_value
metrics.conversions_value_per_cost
metrics.cost_per_all_conversions
metrics.cost_per_conversion
metrics.cost_per_current_model_attributed_conversion
metrics.cross_device_conversions
metrics.current_model_attributed_conversions
metrics.current_model_attributed_conversions_from_interactions_rate
metrics.current_model_attributed_conversions_from_interactions_value_per_interaction
metrics.current_model_attributed_conversions_value
metrics.current_model_attributed_conversions_value_per_cost
metrics.value_per_all_conversions
metrics.value_per_conversion
metrics.value_per_current_model_attributed_conversion

On April 9, 2020 at approximately 8pm PST, a bug caused Google Ads Search and Shopping conversions occurring between April 9 12:01 AM PST onwards to be underreported for advertisers using non-last click attribution models. This bug impacts reports in all Google Ads interfaces, including any report data downloaded via the AdWords API, Google Ads API and Google Ads scripts. Google Ads bid strategies are not impacted by this issue.
We are actively working on fixing the bug and correcting the conversion data.

- Josh Radcliff, Google Ads API Team

Updates to the AdWords API and Google Ads API

2020-04-07T06:11:00.000-07:00

As communities respond to COVID-19, we know that this time presents unique challenges for everyone. Below are updates and resources to help you navigate and plan through these challenging times.

How does this impact the APIs?
We realize you are balancing a lot in your life. Here’s what we’re doing to help:

Delaying the sunset of the Google Ads API v1: The Google Ads API’s v1 sunset is delayed until July 29, 2020. The AdWords API will continue to be available for production use.
Giving additional time: Any new changes that require updates in your AdWords API and Google Ads API code will be given additional time or will be deferred.

We will continue releasing new versions of the Google Ads API to get new features to you.

What are some customer resources?
Google Ads has provided the following resources for business and customers:

Where can I get support?
The Google Ads Help Center posted a delay for non-API related support. This delay includes developer token approvals and changes.

If you have any API questions or need help, you can reach us at googleadsapi-support@google.com or on our Google Ads API and AdWords API forum.
Nadine Wang, on behalf of the entire Google Ads API Team

Changing statuses of app and app engagement ads that do not serve

2020-03-27T08:05:00.000-07:00

On April 17, 2020, app ads and app engagement ads that do not serve will have their statuses changed automatically from ENABLED to DISABLED. For each ad group in App campaigns, only the first created ad is ever eligible to serve, so we’re disabling other ads in the same ad group to prevent confusion. This means that you may see some changes in the number of report rows if your queries have a condition that includes ad_group_ad.status for the Google Ads API or AdGroupAdStatus for the AdWords API.

What do you need to do?
If you’re not interested in the disabled ads, you don’t need to take any action. Only beware that the number of report rows returned by your query may change. For example, if your queries have a condition to get only enabled ads, you may see fewer report rows.

If you still wish to see the performance data of the disabled ads, make sure your report queries also include the disabled ads. Note that as they don’t serve anymore, these ads won’t accrue any more performance stats beyond the above-mentioned date.

In case you need more information on reporting, follow the below links:
For the Google Ads API,

For the AdWords API,

As always, if you have any questions, feel free to reach out to us on the AdWords API and Google Ads API forum.
- Thanet Knack Praneenararat, Google Ads API Team

Preventing App engagement campaigns for prohibited apps

2020-03-10T08:51:00.000-07:00

Starting on April 1, 2020, the Google Ads API will prevent the creation of new App engagement campaigns for apps in prohibited categories.

The Google Ads API currently allows you to create App engagement campaigns for any category of app. But if an app from a prohibited category is chosen, those campaigns are prohibited from serving ads. This can lead to confusion among advertisers.

Enabling the API to validate that such campaigns are indeed eligible to serve before their creation will allow developers to take corrective action early on and also ensure client accounts are able to serve their intended ads.

Change details
App engagement campaigns are identified in the API as campaign objects with the following properties.

Once this change goes into effect, API calls to create campaigns of the above type will fail if the campaign’s app_campaign_setting.app_id references an app in a prohibited category.

Versions v3 and later of the API will throw a SENSITIVE_CATEGORY_APP error. Earlier versions of the API will throw a more generic UNKNOWN error, since the error code is not published in those versions. These errors may surface from the following services and operations.

API Version	Service	Operation	Error
v3+	`CampaignService`	`create`	`CampaignError.SENSITIVE_CATEGORY_APP`
v1, v2	`CampaignService`	`create`	`CampaignError.UNKNOWN`

For instances of error code CampaignError.UNKNOWN, the GoogleAdsError’s details.unpublished_error_code field will indicate, “CampaignError.SENSITIVE_CATEGORY_APP”.

Implementation and support
If you create App engagement campaigns with the Google Ads API, please add error handling for apps in prohibited categories. In order to leverage the new SENSITIVE_CATEGORY_APP error, please upgrade to v3 of the Google Ads API first where possible.

If you’re unable to upgrade versions before the change goes into effect, please check for error code CampaignError.UNKNOWN upon campaign creation, and verify that the error’s details.unpublished_error_code string matches the error name documented in the previous section, to indicate a prohibited category may be in use.

For more details on implementing support for App campaigns, see our App Campaigns developer guide for more information. And as always, if you have any questions about this change, don’t hesitate to reach out to us on the Google Ads API developer forum.
Adam Ohren, Google Ads API Team