Content API for Shopping

Managing Client Data Feeds

A structured content datafeed is a file that contains items that the client wants to publish to Google search services using the Content API for Shopping. The following sections describe how to maintain the list of datafeeds for each of your client accounts.

Any time you register, retrieve, update or delete datafeeds, the API URL must specify the account ID for the client account associated with the action in addition to the account ID of the multi-client account.

You can use your multi-client account to register datafeeds for your client accounts but you cannot register datafeeds directly to your multi-client account. Similarly, you can retrieve, update or delete datafeeds for any of your client accounts, but the API will return an error if you try to retrieve, update or delete datafeeds associated directly with your multi-client account.

Contents

  1. Registering a Datafeed for a Client Account
  2. Retrieving a list of Datafeeds for a Client Account
  3. Retrieving Information about a Single Data Feed
  4. Updating Information about a Datafeed
  5. Deleting a Datafeed from a Client Account
  6. Datafeed Attributes Reference

Registering a Datafeed for a Client Account

To register a datafeed for a client account, send an HTTP POST request to the datafeeds URL for that account. The body of your request will be an XML document in the format shown below:

POST  /content/v1/SUB_ACCOUNT_ID/datafeeds/products HTTP/1.1
Host: content.googleapis.com
Content-Type: application/atom+xml
Authorization: GoogleLogin auth=AUTHORIZATION_TOKEN

<?xml version='1.0'?>
<entry xmlns='http://www.w3.org/2005/Atom'
       xmlns:sc='http://schemas.google.com/structuredcontent/2009'>
  <title type="text">ABC Store Electronics products feed</title>
  <sc:feed_file_name>electronics.txt</sc:feed_file_name>
  <sc:target_country>GB</sc:target_country>
  <sc:content_language>en</sc:content_language>
  <sc:attribute_language>en</sc:attribute_language>
  <sc:file_format format='dsv'>
    <sc:delimiter>pipe</sc:delimiter>
    <sc:encoding>utf8</sc:encoding>
    <sc:use_quoted_fields>no</sc:use_quoted_fields>
  </sc:file_format>
  <sc:fetch_schedule>
    <sc:weekday>Monday</sc:weekday>
    <sc:hour timezone="Europe/London">12</sc:hour>
    <sc:fetch_url>ftp://ftp.abc.com/electronics.txt</sc:fetch_url>
  </sc:fetch_schedule>
</entry>

For details about entries and their attributes, see the Datafeed Attributes Reference below.

Note: Any time you register, retrieve, update or delete datafeeds, the API URL must specify the ID for the client account associated with the action. For example, while you can use your multi-client account to register datafeeds for your client accounts, you cannot register datafeeds directly to your multi-client account. Similarly, you can retrieve, update or delete datafeeds for any of your client accounts. However, the API will return an error if you try to retrieve datafeeds associated with your multi-client account.

If Google successfully handles your request to create a data feed, the API will return a 201 HTTP response code. The body of the API response will be an Atom entry that describes the newly created feed as shown in the sample below. Please note that the API response will not contain the <sc:processing_status> tag and its subtags. Since you will have just registered the datafeed, Google will not have begun to process the feed file by the time you receive the API response.

<?xml version='1.0' encoding='UTF-8'?>

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:sc='http://schemas.google.com/structuredcontent/2009'>
  <id>http://content.googleapis.com/content/account/78901/datafeed/products/989898</id>
  <published>2010-06-06T18:35:06.704Z</published>
  <updated>2010-06-06T18:35:09.095Z</updated>
  <title type="text">ABC Store Electronics products feed</title>
  <link rel='edit' type='application/atom+xml'
      href='https://content.googleapis.com/content/v1/78901/datafeeds/989898'/>
  <sc:feed_file_name>electronics.txt</sc:feed_file_name>
  <sc:target_country>GB</sc:target_country>
  <sc:content_language>en</sc:content_language>
  <sc:attribute_language>en</sc:attribute_language>
  <sc:file_format format='auto'/>
  <sc:fetch_schedule>
    <sc:weekday>Monday</sc:weekday>
    <sc:hour timezone="Europe/London">12</sc:hour>
    <sc:fetch_url>ftp://ftp.abc.com/electronics.txt</sc:fetch_url>
  </sc:fetch_schedule>
</entry>

Selecting feed filenames

The following guidelines explain the restrictions for feed filenames:

  • Please note that filenames must be unique across all of your managed accounts. We recommend that you format filenames so that they identify the client account with which they are associated and the country where the items will appear on Google search services. For example, if you manage client accounts ABC and XYZ and each account provides you with a feed of items for the United States and Germany, you might select the following filenames for those feeds:

    • ABC_US_products.txt
    • ABC_DE_products.txt
    • XYZ_US_products.txt
    • XYZ_DE_products.txt
  • RSS and Atom files should end with an .xml extension.

  • Filenames may not contain directories.

Uploading feeds to Google

You can upload registered data feeds to Google using either of the following methods:

  • File Transfer Protocol (FTP). You must use FTP to upload files larger than 20MB.
  • Direct upload using the Merchant Center or Google Base dashboard

Zipping data feeds

You can compress a single feed and send it as a .gz file but do not send multiple feeds in the same zipped file. In other words, each feed must be sent as a distinct file.

Scheduled Fetch

You can submit data feeds via Scheduled Fetch. This results in the Google Merchant Center automatically retrieving a file from a given URL according to the schedule you specify. To specify the schedule use the fetch schedule element provided by the API.

If you are updating a feed file with an existing fetch schedule, but do not include a <sc:fetch_schedule>, the existing schedule will remain unchanged and will be returned in the response. To terminate a scheduled fetch, submit an update with an empty <sc:fetch_schedule/> element.

Retrieving a list of Datafeeds for a Client Account

To retrieve a list of datafeeds for client account, send an HTTP GET request to the datafeeds URL for that account as shown in the following sample request:

GET  /content/v1/SUB_ACCOUNT_ID/datafeeds/products HTTP/1.1
Host: content.googleapis.com
Content-Type: application/atom+xml
Authorization: GoogleLogin auth=AUTHORIZATION_TOKEN

If Google successfully handles your request to retrieve a list of the datafeeds for a particular client account, the API will return a 200 HTTP response code. The body of the API response will be an Atom feed in which each entry describes one of the datafeeds for your client account.

The XML feed below shows a sample response that lists one datafeed.

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom"
    xmlns:app="http://www.w3.org/2007/app"
    xmlns:sc="http://schemas.google.com/structuredcontent/2009"
    xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/">
  <id>http://content.googleapis.com/content/v1/9827661/datafeeds/products</id>
  <updated>2010-12-15T15:48:13.066Z</updated>
  <title>Datafeeds for customer Magic test</title>
  <link rel="alternate" type="text/html" href="http://content.apis.google.com"/>
  <link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="https://content.googleapis.com/content/v1/9827661/datafeeds/products"/>
  <link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml" href="https://content.googleapis.com/content/v1/9827661/datafeeds/products"/>
  <link rel="self" type="application/atom+xml" href="https://content.googleapis.com/content/v1/9827661/datafeeds/products"/>
  <openSearch:totalResults>1</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <entry>
    <id>http://content.googleapis.com/content/account/78901/datafeed/products/989898</id>
    <published>2010-12-15T15:47:37.000Z</published>
    <updated>2010-12-15T15:47:37.000Z</updated>
    <app:edited>2010-12-15T15:47:37.000Z</app:edited>
    <title>xyz</title>
    <link rel="self" type="application/atom+xml" href="https://content.googleapis.com/content/v1/78901/datafeeds/products/989898"/>
    <link rel="edit" type="application/atom+xml" href="https://content.googleapis.com/content/v1/78901/datafeeds/products/989898"/>
    <sc:target_country>US</sc:target_country>
    <sc:content_language>en</sc:content_language>
    <sc:attribute_language>en</sc:attribute_language>
    <sc:feed_file_name>xyz</sc:feed_file_name>
    <sc:feed_type>listings</sc:feed_type>
    <sc:file_format format="auto">
      <sc:use_quoted_fields>no</sc:use_quoted_fields>
    </sc:file_format>
    <sc:fetch_schedule>
      <sc:weekday>Monday</sc:weekday>
      <sc:hour timezone="Europe/London">12</sc:hour>
      <sc:fetch_url>ftp://ftp.abc.com/electronics.txt</sc:fetch_url>
    </sc:fetch_schedule>
    <sc:processing_status status="unprocessed"/>
  </entry>
</feed>

Retrieving Information about a Single Data Feed

To retrieve information about an individual datafeed, send an HTTP GET request to the edit URL for that feed as shown in the following sample request:

GET  /content/v1/SUB_ACCOUNT_ID/datafeeds/products/DATAFEED_ID HTTP/1.1
Host: content.googleapis.com
Content-Type: application/atom+xml
Authorization: GoogleLogin auth=AUTHORIZATION_TOKEN

If Google successfully handles your request to retrieve the datafeed identified by the specified id for a particular client account, the API will return a 200 HTTP response code. The body of the API response will be an Atom entry that describes requested datafeed for your client account.

The XML feed below shows a sample response for a single entry request.

<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom"
    xmlns:app="http://www.w3.org/2007/app"
    xmlns:sc="http://schemas.google.com/structuredcontent/2009">
  <id>http://content.googleapis.com/content/account/78901/datafeed/products/989898</id>
  <published>2010-12-15T15:47:37.000Z</published>
  <updated>2010-12-15T15:47:37.000Z</updated>
  <app:edited>2010-12-15T15:47:37.000Z</app:edited>
  <title>xyz</title>
  <link rel="self" type="application/atom+xml" href="https://content.googleapis.com/content/v1/78901/datafeeds/products/989898"/>
  <link rel="edit" type="application/atom+xml" href="https://content.googleapis.com/content/v1/78901/datafeeds/products/989898"/>
  <sc:target_country>US</sc:target_country>
  <sc:content_language>en</sc:content_language>
  <sc:attribute_language>en</sc:attribute_language>
  <sc:feed_file_name>xyz</sc:feed_file_name>
  <sc:feed_type>listings</sc:feed_type>
  <sc:file_format format="auto">
    <sc:use_quoted_fields>no</sc:use_quoted_fields>
  </sc:file_format>
  <sc:fetch_schedule>
    <sc:weekday>Monday</sc:weekday>
    <sc:hour timezone="Europe/London">12</sc:hour>
    <sc:fetch_url>ftp://ftp.abc.com/electronics.txt</sc:fetch_url>
  </sc:fetch_schedule>
  <sc:processing_status status="unprocessed"/>
</entry>

Updating Information about a Datafeed

To update the metadata associated with a datafeed, send an HTTP PUT request to the edit URL for the datafeed. The body of the API request will be an XML document that has the same format as the XML that you would send to register a datafeed. Currently, Google supports updates to the following field:

  • You can update the value of the <sc:file_format> tag's sc:encoding attribute. The value identifies the file's character encoding scheme to Google. Valid values are UTF8 and Latin1.

The following shows a sample request to update a client account:

PUT  /content/v1/SUB_ACCOUNT_ID/datafeeds/products/DATAFEED_ID HTTP/1.1
Host: content.googleapis.com
Content-Type: application/atom+xml
Authorization: GoogleLogin auth=AUTHORIZATION_TOKEN

<?xml version='1.0'?>
<entry xmlns='http://www.w3.org/2005/Atom'
       xmlns:sc='http://schemas.google.com/structuredcontent/2009'>
  <title type="text">ABC Store Electronics products feed</title>
  <sc:feed_file_name>electronics.txt</sc:feed_file_name>
  <sc:target_country>GB</sc:target_country>
  <sc:content_language>en</sc:content_language>
  <sc:attribute_language>en</sc:attribute_language>
  <sc:file_format format='dsv'>
    <sc:delimiter>pipe</sc:delimiter>
    <sc:encoding>Latin1</sc:encoding>
    <sc:use_quoted_fields>no</sc:use_quoted_fields>
  </sc:file_format>
  <sc:fetch_schedule>
    <sc:weekday>Monday</sc:weekday>
    <sc:hour timezone="Europe/London">12</sc:hour>
    <sc:fetch_url>ftp://ftp.abc.com/electronics.txt</sc:fetch_url>
  </sc:fetch_schedule>
</entry>

If Google successfully handles your request to update a client account, the API will return a 200 HTTP response code. The body of the API response will be an Atom entry that describes the newly updated client account. Please note that the API response will not contain the <sc:processing_status> tag and its subtags. You can retrieve this information by retrieving the datafeeds feed for the client account or by sending a request to retrieve information about the individual feed that you updated.

Deleting a Datafeed from a Client Account

To delete a datafeed, send an HTTP DELETE request to the edit URL for the datafeed, found in the link attribute:

<link rel='edit' type='application/atom+xml'
   href='https://content.googleapis.com/content/v1/SUB_ACCOUNT_ID/datafeeds/products/DATAFEED_ID'>

The following sample API request demonstrates how to delete a datafeed:

DELETE  /content/v1/SUB_ACCOUNT_ID/datafeeds/products/DATAFEED_ID HTTP/1.1
Host: content.googleapis.com
Content-Type: application/atom+xml
Authorization: GoogleLogin auth=AUTHORIZATION_TOKEN

If Google successfully handles your request to delete a datafeed, the API will return a 200 HTTP response code. The body of the response will be empty.

Datafeed Attributes Reference

The table below details the requirements of client datafeeds entries.

Attribute Required Description
<title> yes A descriptive name of the datafeed.
<sc:attribute_language> yes Identifies the language in which the attributes are defined in the feed (e.g. en if you'll have a price attribute, fr if you'll have a prix attribute).
<sc:channel> no The channel for the product. Supported values are:
  • online
  • local
Defaults to online.
<sc:content_language> yes Specifies the language of the items in the feed (e.g. en if the title, the content and the web page the item points to are written in English).
<sc:feed_destination dest='DEST' enabled='enabled'> no The rule or set of rules determining the product destinations for the feed. Supported values for enabled are:
  • true
  • false
For example, one may include
<sc:feed_destination dest='ProductSearch' enabled='true'> <sc:feed_destination dest='CommerceSearch' enabled='false'>
<sc:feed_file_name> yes Specifies the filename of the feed. All feeds must have a unique file name as described in the Selecting feed filenames section.
<sc:fetch_schedule> no

Fetch schedule for the feed file. The list of required child elements depends on the frequency of fetching desired. The frequency will be inferred from the elements provided. The elements allowed by the API support monthly, weekly and daily fetch frequencies. See the the table below for details.

<sc:file_format format='FORMAT'> yes

Format of the feed file. Possible values for FORMAT are as follows.

  • auto: Google will automatically detect the file format;
  • dsv: The file contains delimiter-separated values;
  • xml: The feed is in XML format.
Depending on the chosen value for FORMAT, some child XML nodes of <sc:file_format> are required; see the table below for details.

Defaults to <sc:file_format format='auto'>.

<sc:target_country> yes Identifies the country where the items in the feed will be included in the search index.

The child elements required vary based on the frequency of fetching. No matter the frequency, <sc:fetch_url> is always required. The following table details the required child elements based on a given fetch frequency:

Fetch Frequency Additional Required Elements
Monthly <sc:day_of_month> and <sc:hour>
Weekly <sc:weekday> and <sc:hour>
Daily <sc:hour>

Note: If elements that are meant for different frequencies are combined, such as <sc:day_of_month> and <sc:weekday>, the request will result in an error.

The table below details the requirements of fetch_schedule specifications.

Attribute Description
<sc:day_of_month>

The day of the month to fetch the feed file, intended to be used only for monthly fetches. Accepted values are the integers 1-31.

Be careful using values above 28. In months that don't have the corresponding date, no fetch will occur.

<sc:fetch_url username='USERNAME' password='PASSWORD'>

The URL where the feed file can be fetched, required for all fetch frequencies. Google Merchant Center will support automatic scheduled uploads using the http, https, ftp, or sftp protocols, so the value will need to be a valid link using one of those four protocols.

If the URL is protected, a username and password can be optionally provided as XML attributes.

<sc:hour timezone='TIMEZONE'>

The hour in the day to fetch the feed file, intended to be used for monthly, weekly or daily fetches. Accepted values are the integers 0-23.

Specifying timezone is optional; by default, the timezone will be assumed UTC. If specified, the timezone should be the name of a standard zoneinfo time zone name.

<sc:weekday> The day of the week to fetch the feed file, intended to be used only for weekly fetches. Accepted values are:
  • Sunday
  • Monday
  • Tuesday
  • Wednesay
  • Thursday
  • Friday
  • Saturday
Though the values above are capitalized, case is not important.

The table below details the requirements of file_format specifications.

Attribute Required When Description
<sc:delimiter> format='dsv' Specifies the delimiter used to separate values in a delimiter-separated values feed. Possible values are:
  • tab
  • pipe
  • tilde
When format is not dsv, the tag is ignored.
<sc:encoding> optional Specifies the character encoding scheme used in the datafeed. Possible values are:
  • latin1
  • utf8
<sc:use_quoted_fields> format='dsv'

Indicates whether the delimiter may be a part of some of the field values in the feed. Ranges over:

  • yes
  • no
For example, the following feed snippet shows the name, description and price fields for a pipe-delimited values feed.

Name|Description|Price
Camping blanket|"Wool blanket with pipe character -- ||| --- print"|$19.99

Note that the description is encapsulated in quotation marks because the description contains a pipe character. This convention prevents the pipe character within the description from being interpreted as a delimiter between two feeds.

This tag shall be used only when format='dsv'.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.