Tag Archives: content_api

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.

Announcing service account creation in the Merchant Center

Today we're pleased to announce that you can now create service account keys to access the Content API for Shopping directly in the Merchant Center!

Even if you've already set up service accounts for your solutions, you can still create a new service account key here if you'd like to switch to managing your service account keys directly in the Merchant Center. See the Retrieve a service account key for authentication section of the Get Started guide for more details.

Note: This feature does not remove the other ways to create and manage Content API authentication. If you'd prefer to manage your Google API Console project and service accounts yourself, you can still follow the steps in the Service Accounts guide. If you are accessing others' Merchant Center accounts using OAuth 2.0, you'll still want to follow the steps in the Authorize Requests guide instead of using service accounts.

If you have any questions or feedback about the new service account management in the Merchant Center, or any other questions about the Content API for Shopping, please let us know on the forum.

Changes to issue reporting in the Content API for Shopping

What's changed?
There are two major changes to the resource returned by Productstatuses:
  • a new format for product-level issues
  • changes to the destination-specific statuses for each product
A new format for product-level issues
We've added a new itemLevelIssues field to the productStatus resource. This field contains a sequence of issue entries, similar to the dataQualityIssues field, but each entry contains different information. For now, the Content API returns both fields (see the "What do I need to do?" section for more details).

Here is an example of the same issue in the old format and the new format:
dataQualityIssues

{
"id": "validation/missing_required",
"severity": "critical",
"location": "title",
"detail": "Invalid or missing required attribute: title"
}
itemLevelIssues

{
"code": "item_missing_required_attribute",
"servability": "disapproved",
"resolution": "merchant_action",
"attributeName": "title",
"destination": "Shopping"
}

As shown above, each entry in the itemLevelIssues field contains the following information:
  • code: The issue ID

    Note: This ID may differ from the ID provided for the same issue in the dataQualityIssues field, as in the example above.
  • servability: The serving status of the product based on this issue. May be one of the following string values:
    • "disapproved": This issue has caused the associated product to be disapproved.
    • "unaffected": This issue has not affected the servability of the associated product.
  • resolution: Whether or not the issue requires the merchant to take action. May be one of the following string values:
    • "merchant_action": This issue requires action on the part of the merchant to resolve.
    • "pending_processing": This issue requires further processing from Google to resolve this issue, and you do not need to do anything.
  • attributeName: The name of the product attribute that caused this issue, if applicable. For the "item_missing_required_attribute" issue example above, this field contains the value "title" since the product data triggering this issue did not include a title.
  • destination: The destination to which this issue applies. For example, a given issue may affect the servability of the product for Shopping campaigns (the "Shopping" destination), but not the servability for Display Ads (the "DisplayAds" destination).

    Note: If an issue applies to multiple destinations, then there will be separate issue entries for each destination.
To summarize, the new issue format makes explicit whether a given issue affects the servability of the product and whether or not merchant action is required to resolve the issue.

Note: Currently, an entry in itemLevelIssues does not contain human-readable descriptions of the issue (e.g., the detail field in dataQualityIssues entries). This work is ongoing, and new fields that contain this information will be added in the near future. We will post another blog entry describing those fields when they are available.

Changes to destination-specific product statuses
We have also added a new approvalPending field to the destinationStatuses field. If set to true, then the approvalStatus of the entry may change due to further processing. This corresponds to the pending status of products when viewed in the Merchant Center. The approvalPending field is true only if there are no issues for that product that require action by the merchant.

Here's a concrete example of a destinationStatuses entry for a product that has "Shopping" as an intended destination with approval pending on further processing:

{
"destination": "Shopping",
"intention": "required",
"approvalStatus": "disapproved",
"approvalPending": true
}
In addition, the destinationStatuses field contains only entries for intended destinations. That is, this field will no longer contain statuses for excluded destinations. Due to this, the intention field of these entries will now always contain the value "required".

What do I need to do?
Currently, no action is needed. We do not expect you to transition to the new issue format yet as it is not on par with the old issue format. For now, we are describing the new issue format so that you get a head start on understanding it and to allow you to transition ahead of time if you do not need the currently missing information.

However, note that we plan to drop support for the old dataQualityIssues field on Aug 1, 2018. Once the new issue format has reached parity with the old issue format, we will update the blog with information about the new changes, and you should transition to the new issue format at that time.

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.

Invalid inserted products no longer result in immediate errors

In July, there was a change in how the Content API for Shopping responds when inserting products that contain validation errors due to work related to advanced feed management.

What changed?
Here are the changes in behavior when inserting product information that contains validation errors and would result in an invalid product:

Before After
Inserting new product Error (inserted) Success (inserted)
Updating invalid product Error (inserted) Success (inserted)
Updating valid product Error (not inserted) Error (not inserted)

That is, before the Content API would return an error whenever the new product information contained validation errors. Now, an error is returned only if the product information cannot be updated because it would invalidate the currently valid product.

Note: With this change, the Content API now returns an error response to product insertion only when the returned error response contains the not_inserted error. Since this error is now redundant, we plan to remove it in the future.

Why has this behavior changed?
With the new advanced feed management features, the products inserted via the Content API may be augmented with information from associated supplemental feeds. This means that a product that would normally be invalid from just the information provided by the Content API may become valid when the information is combined with supplemental feeds to produce the final version of a product.

For example, suppose you submit product information via the Content API that lacks needed GTIN information. You then submit the GTIN information for your products separately via a supplemental feed that is connected to the Content API feed in Merchant Center. The products inserted by the Content API are not valid products due to the lack of GTIN information, but once the GTIN information from the supplemental feed is added, the resulting products are valid.

What do I need to do?
If you depend on error responses from Products.insert to detect validation issues, then you should instead also check your Content API feed for validation issues by using either Productstatuses or Accountstatuses. This will catch products that were inserted with invalid information and have not been made valid after insertion via supplemental feeds.

Note: If you are using Productstatuses.list to check all the products in a given account, you'll need to set the includeInvalidInsertedItems parameter to return products with validation errors.

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.