Tag Archives: google_ads_scripts

Beta Support for search in Google Ads scripts

Today, we are announcing beta support for a new search method in Google Ads scripts. This method is backed by the Google Ads API and supports most queries supported by that API. Please see the documentation page for the AdsApp.search method for more information.

Additionally, we are adding beta support for the Google Ads Query Language to our existing AdsApp.report method. When using the report method, Google Ads scripts will automatically determine the correct reporting engine (either AdWords API or Google Ads API) to use based on the FROM clause in your query.

The key difference between the report and search methods is in how the results are returned.
  • The report method will return a Report object, as it always has. Each row will be a map of column names to values.
  • The search method will return an iterator of rows, and each row will be analogous to a GoogleAdsRow in the Google Ads API.
For example, the campaign.name column would be accessed using row['campaign.name'] if you use report, and row.campaign.name if you use search. The flat format from report can be useful for exporting to a spreadsheet or CSV. The object format from search is useful for programmatically processing results. Additionally, handling repeated fields is more intuitive since they will be returned as true arrays in the object format rather than concatenated together into a single string.

To help you build queries for your search, check out our query builder tool. If you have any questions, concerns, or feedback on the new beta features, please contact us via our forum.

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:

Google Ads conversion reporting issues starting April 9

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


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

Responsive Display Ads in Google Ads Scripts

Today we are adding support for new responsive display ads in Google Ads scripts. Starting last year, you could no longer create legacy responsive display ads, but you could still fetch your existing ads.

These new responsive display ads have added support for multiple text, image, and video assets in the same ad. The ResponsiveDisplayAd object gained new methods to support the new associated fields, and you can begin adding new responsive display ads in your scripts.

The new and legacy responsive display ads are both represented via the same ResponsiveDisplayAd object. Make sure to read the full object documentation to check which methods are relevant for legacy ads or new ads. We also have a short guide demonstrating some of the key changes.

If you have any questions or concerns, please don't hesitate to contact us via the forum.

Complete sunset of accelerated budget delivery

Last October, we announced the sunset of accelerated budget delivery for use with Search campaigns, Shopping campaigns, and shared budgets. These campaigns have since been made unavailable for use with accelerated budget delivery.

Later this year, accelerated budget delivery will also be sunset for all other remaining campaign types for both shared and non-shared budgets. This includes Display, App, video campaigns, and others, and this sunset will affect budgets in all versions of the AdWords API, Google Ads API, and Google Ads scripts.

Starting at the end of April, 2020, scripts and both APIs will prevent campaigns from using new and existing budgets with the ACCELERATED delivery method.
  • Creating a new budget with its delivery method field set to ACCELERATED will no longer be allowed.
  • Changing an existing budget from STANDARD to ACCELERATED delivery method will no longer be allowed.
  • Setting a campaign to use a pre-existing budget with an ACCELERATED delivery method will no longer be allowed.
Any of the above operations will result in errors from the APIs and scripts, according to the following:
AdWords API
Service Field Value Error
BudgetService deliveryMethod: ACCELERATED OperationAccessDenied.ACTION_NOT_PERMITTED
CampaignService budget*
[*]only if set to accelerated delivery
OperationAccessDenied.ACTION_NOT_PERMITTED

Google Ads API
Service Field Value Error
CampaignBudgetService delivery_method: ACCELERATED OperationAccessDenied.ACTION_NOT_PERMITTED
CampaignService campaign_budget*
[*] only if set to accelerated delivery
OperationAccessDenied.ACTION_NOT_PERMITTED

Google Ads scripts
Method Error
AdsApp.​Budget.setDeliveryMethod(“ACCELERATED”) “Action not permitted”

Making changes to existing ACCELERATED budgets (e.g., updating amount or status fields in the API, or using their corresponding AdsApp.​Budget methods in scripts) will still be allowed until May 2020, after which any modification to these budgets will also result in analogous errors.

Future versions of the Google Ads API and Google Ads scripts may remove support for the accelerated budget delivery option altogether.

Please don’t hesitate to reach out to us on the AdWords API / Google Ads API forum or the Google Ads scripts forum if you have any questions about this change.

Upcoming sunset of message extensions in in AdWords and Google Ads APIs and Google Ads scripts

On January 27, 2020, message extensions will be sunset in AdWords and Google Ads APIs and Google Ads scripts. After the sunset date:
  • All existing message extensions will no longer serve.
  • You will not be able to create new message extensions or update existing extensions.
  • You will still be able to retrieve data for existing message extensions until the end of 2020.
  • You will also be able to remove the existing message extensions until the end of 2020.
What will happen when you try to create or update message extensions after the sunset date?
If you try to create or update a message extension, you will see the following errors:

Google Ads API
  • Trying to create or update a TextMessageFeedItem will result in the ExtensionSettingError.INVALID_FEED_TYPE error.
  • Trying to create or update a message extension via FeedMapping with placeholder_type set to MESSAGE will result in the FeedMappingError.INVALID_PLACEHOLDER_TYPE error.

AdWords API
  • Trying to create or update a MessageFeedItem will result in the ExtensionSettingError.INVALID_FEED_TYPE error.
  • Trying to create or update a message extension via FeedMapping using placeholder type ID 31 will result in the FeedMappingError.INVALID_PLACEHOLDER_TYPE error.

Google Ads scripts
Trying to execute the following operations will result in the error, “Cannot operate on deprecated placeholder type” (translated to the language based on your locale):
What do you need to do?
  • Retrieve all the data from your existing message extensions that you need. All message extension data will be deleted at the end of 2020.
  • Ensure that your programs don’t contain any code trying to create or update message extensions after the sunset date.
As always, if you have any questions, feel free to reach out to us on the Google Ads API forum.

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.

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.

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

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.