Tag Archives: content_api

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:

Content API for Shopping live webinar on May 31st (Mandarin, Chinese)

We are running a live webinar this Friday, May 31, on the Content API for Shopping. This webinar is for our Chinese-speaking developers that are interested in using the API to manage products and Shopping ads at scale.

The webinar will cover topics on:
  • Content API for Shopping use case
  • Merchant Center setup
  • Content API features
  • Best practices
  • API request/response demo
You will be able to submit questions throughout the live event. We will answer questions during the Q&A session in the webinar.

Note: The webinar content will be delivered in Mandarin, Chinese.

The webinar will begin at 10:00am (China Time, GMT +8) on Friday, May 31, 2019. Please contact us via the Content API forum if you have any questions or need help.

If you’d like to review some of our previous webinars covering the Google Ads API, you can find them at the following links:

Announcing v2.1 of the Content API for Shopping

Today we're announcing the release of v2.1 of the Content API for Shopping. This version has been available as an experimental version since late last year and is now ready for production use by all Content API users.

Highlights
You can find a complete list of changes in the release notes and accompanying migration guide, but here are some highlights:
  • A more consistent product validation experience. Product insert requests no longer report non-fatal warnings or errors. This allows you to insert products and make subsequent updates to resolve issues via feed rules in the Merchant Center UI, just as you would with feeds maintained outside the API.
  • A better experience for managing Shopping Actions. Multiple improvements have been made to the Orders API based on feedback from beta users.
  • More features are on the way! Today's release contains many improvements, but more are on the way, including new ways to supply local inventory data and features to support supplemental feeds.
  • Continued v2 support. While we strongly encourage you to migrate to v2.1, support for v2 will continue at least through the first quarter of 2020. Subscribe to this blog to ensure you receive important updates on Content API releases and deprecations.
Updated client libraries
Updated client libraries with support for v2.1 are now available in multiple languages.

Learn more
Check out the v2.1 API reference documentation to explore the new version of the API, and read through the list of behavior changes and deprecations in the migration guide to help plan your upgrade to v2.1.

If you have any questions or need help with migration, please head over to our support forum.

Subscribe to our RSS feed to get blog posts via email

(If you want to continue getting email updates about our blog posts, read on. If you don't want email updates from this blog, you can skip this post.)

For some products, the Google Ads Developer team has used Google groups as a way to allow API users to subscribe and get new relevant blog posts delivered to their email address. Starting now, the way you can get email updates about blog posts is changing. We will no longer send an email to the Google group for each new blog post. We will continue to use the Google groups for other important updates, however.

For users who still want email updates, we've introduced new FeedBurner links on the right-hand panel of our blog homepage. You can subscribe to the RSS feed by clicking on the link for the product you're interested in, or subscribe by email by clicking on the [+] link to the right of the product name.

If you use any of the APIs that we discuss on this blog, make sure you subscribe to the feed to keep up with the latest news and updates:

Sunset of XML support in the Content API for Shopping

What's changing?
Starting September 1, 2019, the Content API for Shopping will no longer support requests or responses with XML payloads. All requests with an XML payload will fail after the sunset date.

Why is this change happening?
Version 2 of the Content API for Shopping changed the default request and response format from XML to JSON, and version 2.1 of the API (currently marked experimental) will not support XML. The majority of API requests now use JSON, so we've decided to sunset XML support and instead focus on enriching our JSON APIs with new features and functionality.

What should you do?
Prior to the sunset date, identify the components of your application that are using XML payloads for any of the following impacted services: For each case, modify your application to:
  • Send the request body as JSON.
  • Ensure you have removed the alt=xml parameter from the request.
  • Process the response as JSON.
  • Test your updated application using a separate test account.
Tip: The client libraries for .NET, Dart, Go, Java, JavaScript, Node.js, Objective-C, PHP, Python, and Ruby will send JSON requests and parse JSON responses for you. We strongly recommend that you use one of the libraries so you won't have to write marshalling and unmarshalling code in your application.

When converting a given request, you can use the JSON and XML tabs in the Request body section of the documentation for the method. For example, here's a partial screenshot of the XML tab for Inventory.set:

The corresponding JSON tab for that method is:

Compare the two tabs and use that as a guide when converting your request from XML to JSON.

You can find similar JSON and XML information for the response in one of the following locations:
  • Directly in the Response section for the method.
    Example: The productsCustomBatchResponse for Products.custombatch.
  • In the Resource representations section of the documentation for the resource returned in the response.
    Example: The products resource for Products.insert.
If you have any questions or feedback about this change, or any other questions about the Content API for Shopping, please let us know on the forum.

Update on issue reporting changes in the Content API for Shopping

In August, 2018, we announced that we would stop populating the dataQualityIssues field in Productstatus and Accountstatus resources in December of last year. Due to the recent holiday season, we decided to hold off on that change, but it will now be made starting February 25, 2019.

Please review the previous blog post for important details, including how to use the new and improved itemLevelIssues field in your platform's integration with the Content API for Shopping.

If you have any questions or feedback about this change, or any other questions about the Content API for Shopping, please let us know on the forum.

More changes to issue reporting in the Content API for Shopping

What's changed?
There are three major changes being announced in this post: Aggregated product statistics in Accountstatuses
The number of products in a given account can now be retrieved directly from Accountstatuses. Like the Merchant Center, you can retrieve the following aggregated statistics: active products, expiring products, disapproved products, and pending products. These statistics are given separately for each combination of destination, channel, and target country. For example:

"products": [{
"country": "US",
"destination": "Shopping",
"channel": "online",
"statistics": {
"active": "1542",
"expiring": "14",
"disapproved": "152",
"pending": "743"
},
...
}]
Here, there are 1542 active products that target the USA that can be used in online Shopping campaigns, 14 active but expiring products, 152 disapproved products, and 743 pending products.

Product-level issues in Accountstatuses
In addition to the new product statistics, the "products" field also contains an itemLevelIssues field similar to the itemLevelIssues field added to Productstatuses earlier this year. Using the contents of this field, you can now see explicitly whether a given issue is impacting the servability of a product and whether the issue needs your attention or just further processing on Google's part.

Human-readable descriptions in itemLevelIssues
In both Productstatuses and Accountstatuses, the objects in the itemLevelIssues field now have some additional fields, which contain English descriptions and helpful links for issues that are suitable for surfacing to clients. The following fields have been added:
  • description contains a short English description of the issue.
  • detail contains a detailed English description of the issue.
  • documentation contains a URL for a web page that can help resolve the issue.
Here is an example itemLevelIssues object that includes these fields:

{
"attributeName": "image link",
"code": "image_link_pending_crawl",
"description": "Image not retrieved (crawl pending)",
"destination": "Shopping",
"detail": "Wait for the product image to be crawled (up to 3 days)",
"documentation": "https://support.google.com/merchants/answer/160640",
"resolution": "pending_processing",
"servability": "disapproved"
}
What do you need to do?
Now that the human-readable information is available for itemLevelIssues in both systems, we now consider the old dataQualityIssues fields deprecated. We will no longer include them in Productstatus or Accountstatus resources on Dec 1, 2018, therefore you should migrate to the new itemLevelIssues fields as soon as possible.

If you have any questions or feedback about this change, or any other questions about the Content API for Shopping, please let us know on the forum.

A new guide for integrating Google Shopping ads using Google APIs

Good news for developers planning to integrate Google Shopping ads! We have just released a brand new guide explaining how to automate the delivery of Google Shopping on behalf of merchants using Google APIs.

The Shopping Automation Guide covers the steps required to set up new merchants using a combination of the Content API for Shopping and AdWords API. It describes how you can fully automate certain tasks that would otherwise be performed manually using the Merchant Center and AdWords websites.

The guide is for developers interested in feed management, campaign management, or full automation workflow that includes both. The workflows provide detailed explanations of how the different APIs can be used for each stage of the user journey. You can follow the workflow step by step or navigate straight to the article you require using the side panel.

Head over to the developer pages to get started! If you have any questions or need help, please contact us on the relevant forums: If you have any feedback on the guide, please use the “Send Feedback” link at the top right of each page.

We also appreciate any feedback on your experience using the guide. If you would like to share it, please complete this survey.

Content API for Shopping Roundup

There have been some smaller API updates and announcements that we'd like to let you know about!

If you have any questions or feedback about these items or any other questions about the Content API for Shopping, please let us know on the forum.

Onboarding for local inventory ads via the Content API for Shopping

Today, we're announcing the ability to configure your local inventory ads (LIA) settings and link Google My Business (GMB) accounts via the Content API for Shopping. This allows you to onboard accounts for LIA programmatically, instead of needing to manually configure each account separately via the Merchant Center website.

The new Liasettings service lets you perform the following actions via the Content API: In addition, the new googleMyBusinessLink field in the Accounts resource states which business account should be linked. After setting this field, you can provide inventory information for the locations in that business account by uploading product and inventory information either through local product feeds and local product inventory feeds or through the Content API for Shopping with the channel field set to "local".

If you have any questions or feedback about these new features or any other questions about the Content API for Shopping, please let us know on the forum.