As an XML document, a product feed begins with a root node of Feed, and each product in the product catalog features its own Product element within a parent Products element under the root Feed. Product-related metadata appears as children elements like ProductPageUrl under the appropriate product.

Categories, brands, and their associated content can also appear as children elements under the Feed element and within parent Categories and Brands elements, respectively.

The following example shows the general structure of a simplified product feed.

<?xml version="1.0" encoding="UTF-8"?> 
    <Feed>
        <Brands>
            <Brand>...</Brand>
        </Brands>
    <Categories>
        <Category>...</Category>
    </Categories>
    <Products>
        <Product>...</Product>
    </Products>
</Feed>

Utilize the following best practices when you create a data feed:

  • Ensure that the first line of your feed adheres to the following format:

    <?xml version="1.0" encoding="utf-8"?>
    
  • The standard character-encoding scheme, such as UTF-8 or Windows-1252, must match the scheme that you use for any special characters in the feed.
  • If you do not have a value for a particular field, omit the field from your feed. Do not include the field with a blank value.

To view an example product feed, see Example feeds.

Attributes associated with the element

The following table identifies the attributes that are associated with a data feed’s required, top-level Feed element.

AttributeValue
xmlnshttp://www.bazaarvoice.com/xs/PRR/ProductFeed/5.6
nameExampleClient
incrementalIf you are sending a data feed that contains your entire product catalog, set this value to false.

If the number of products in your catalog exceeds 750,000, set this value to true and send incremental feeds with no more than 750,000 products in each feed.

extractDatePopulate this value automatically with a timestamp that identifies the date and time at which the data that constitutes the feed was extracted from your database. This value must be presented in XML's dateTime format.

Children elements associated with the element

The following table identifies the required children elements that are associated with a data feed’s Brand element.

ElementValue
ExternalId

Unique brand ID that can contain only alphanumeric characters and the following special characters: asterisk (*), hyphen (-), period (.), and underscore (_). If your brand IDs contain invalid characters, replace them with an alternate character, such as an underscore. This format is used in the data feed only and is not surfaced to end users.

Ensure that the ID is a stable ID that will not change for the same logical brand, even if the name of the brand changes.

NameName of the brand; visible to end users.

Children elements associated with the element

The category structure in your data feed affects several aspects of your Bazaarvoice implementation. Tags can be assigned to categories, which allow contributors to highlight specific product attributes when submitting content. For example, an electronics retailer could create the following tags for the “headphones” product category: perfect fit, poor fit, stylish, good sound quality, and poor sound quality. The tags appear as check boxes on the content submission form and can also appear on product category or product display pages. A reviewer can select the appropriate tags when submitting content, and shoppers can filter products within a category to see only the ones where ratings include the matching tags. Categories also populate the category picker, which impacts how people at your organization can filter user-generated content in reports, the manage content tools, or Bazaarovoice Intelligence. For example, a well-defined category structure can help a Merchandiser see reviews only for the product categories they care about.

Avoid using false categories like Sale because they do not truly categorize products.

The following table identifies the children elements that are associated with a data feed’s Category element.

ElementValueRequired
NameName of the category or subcategory; visible to end users.Yes
ExternalId

Unique category or subcategory ID that can contain only alphanumeric characters and the following special characters: asterisk (*), hyphen (-), period (.), and underscore (_). If your category IDs contain invalid characters, replace them with an alternate character, such as an underscore. This format is used in the data feed only and is not surfaced to end users.

Ensure that the ID is a stable ID that will not change for the same logical category, even if the name of the category changes.

Yes
CategoryPageUrlUnique, uncorrupted URL for the category or subcategory. Do not include extraneous query string parameters that you might use for tracking and partnership codes.Yes
CategoryPageUrls

Contains a <CategoryPageUrl> element for each locale in a multilingual implementation. Each <CategoryPageUrl> element features a locale attribute of type String.

No
ParentExternalIdParent category's ID of the subcategory in question.No
ImageUrlURL for the category image, which is usually hosted on your website or a content delivery network (CDN). Spaces are not allowed in the ImageURL node.No
ImageUrls

Contains an <ImageUrl> element for each locale in a multilingual implementation. Each <ImageUrl> element features a locale attribute of type String.

No

Children elements associated with the element

The following table identifies common children elements that are associated with a data feed’s Product element. For a complete list of available elements, consult the data feed schema.

ElementValueRequired
ExternalIdUnique, product family-level ID that can contain only alphanumeric characters and the following special characters: asterisk (*), hyphen (-), period (.), and underscore (_). If your product IDs contain invalid characters, replace them with an alternate character, such as an underscore. If a product has its own page, that page is the product ID.

The product ID is not necessarily the stock keeping unit (SKU) ID, as Bazaarvoice does not collect separate content for different styles of product.

This format is used in the data feed only and is not surfaced to end users.

Yes
NameName of the product; visible to end users.Yes
CategoryExternalIdCategory ID or subcategory ID within your store catalog to which the product belongs.Yes
ProductPageUrlUnique, uncorrupted URL for the product page. Do not include extraneous query string parameters that you might use for tracking and partnership codes.Yes
ImageUrlUnique URL for the product image. The optimal but slightly flexible display size is 100 pixels x 100 pixels. Thumbnail images are recommended. Spaces are not allowed in the ImageURL node.Yes
EANsContains at least one child <EAN> element.No, unless including <EAN> elements
EANEuropean Article Number, which is used worldwide for marking retail goods; can be a string of digits either 8 or 13 characters long.No
ManufacturerPartNumbersContains at least one child <ManufacturerPartNumber> element.No, unless including <ManufacturerPartNumber> elements
ManufacturerPartNumberManufacturer-specific part number that can contain letters, numerals, and characters.No
UPCsContains at least one child <UPC> element.No, unless including <UPC> elements
UPCUniversal Product Code, which is the 6- or 12-digit bar code used for standard retail packaging in the United States. The UPC must contain numerals only, with no letters or characters. Further, spaces and hyphens disrupt syndication matching and must be removed.No
ISBNsContains at least one child <ISBN> element.No, unless including <ISBN> elements
ISBNInternational Standard Book Number, which is a unique identifier for books and which is intended for commercial use. The number is either 10 or 13 digits long and consists of four or five parts. The different sections of the number can be of different lengths and are usually separated by hyphens (-) or tildes (~). Spaces and hyphens disrupt syndication matching and must be removed.No
Names

Contains a child <Name> element for each locale in a multilingual implementation. Each <Name> element features a locale attribute of type String.

No
DescriptionDescription of the product. To help products with few or short reviews contribute a significant amount of content to the SEO-optimized landing pages, it is recommended that product descriptions be at least three sentences or 300 characters in length. If you store descriptive information about your products across multiple elements, concatenate your elements into the Description element.

No HTML elements are recognized within the Description element.

No
Descriptions

Contains a child <Description> element for each locale in a multilingual implementation. Each <Description> element features a locale attribute of type String.

No
BrandExternalIdBrand ID of the product.No
ProductPageUrls

Contains a child <ProductPageUrl> element for each locale in a multilingual implementation. Each <ProductPageUrl> element features a locale attribute of type String.

No
ImageUrls

Contains a <ImageUrl> element for each locale in a multilingual implementation. Each <ImageUrl> element features a locale attribute of type String.

No
ModelNumberUnique referencing code that businesses use to identify a part that a particular industry uses. The model number can contain letters, numerals, and other characters.No

If an element is not required but you maintain it for your products, include it in the data feed.

Incremental product feeds

To reduce file size, you can send incremental feeds that include newly added and updated products, categories, and brands, including items that have been removed. Incremental feeds differ from standard feeds in the following ways:

  • The root Feed element contains an incremental attribute that is set to true
  • The removed attribute that is associated with the applicable Product, Category, and Brand elements is set to true

The following example shows an incremental Product feed.

<Feed name="ExampleClient" incremental="true" extractDate="2009-08-31T08:02:00-05:00">
    <Categories>
        <Category>
            <ExternalId>1-8</ExternalId>
            <Name> How my pet makes me a champion </Name>
            <ParentExternalId>1-16</ParentExternalId>
            <CategoryPageUrl>
            http://www.client.com/Content/ContentNoNAV.aspx?PC=heartofchampion
            </CategoryPageUrl>
        </Category>
        <Category>
            <ExternalId>1-9</ExternalId>
            <Name> Why my pet is a champion </Name>
            <ParentExternalId>1-16</ParentExternalId>
            <CategoryPageUrl>
            http://www.client.com/Content/ContentNoNAV.aspx?PC=heartofchampion
            </CategoryPageUrl>
        </Category>
        <Category removed="true">
            <ExternalId>1-6</ExternalId>
            <Name> Naughty </Name>
            <CategoryPageUrl>
            http://www.client.com/Content/ContentNoNAV.aspx?PC=naughtynicecontest
            </CategoryPageUrl>
        </Category>
        <Category removed="true">
            <ExternalId>1-7</ExternalId>
            <Name> Nice </Name>
            <CategoryPageUrl>
            http://www.client.com/Content/ContentNoNAV.aspx?PC=naughtynicecontest
            </CategoryPageUrl>
        </Category>
    </Categories>
</Feed>

In this example, the following element defines the feed as an incremental Product feed:

<Feed name="ExampleClient" incremental="true" extractDate="2009-08-31T08:02:00-05:00”>

Further, the following element specifies the removal of the relevant category:

<Category removed="true">

Validating product feeds

We recommend validating your feed against our product feed schema before uploading.

Validate your data feeds against the following schema before submitting them to Bazaarvoice:

http://www.bazaarvoice.com/xs/PRR/ProductFeed/5.6

XML Beans provides command-line tools that you can use to validate your data feed, and companies like DecisionSoft provide online validation tools. If you use an online tool, you might need to provide the XML schema with your feed.

Your technical team can use the feed validation tool in the Bazaarvoice client portal to view the following information:

  • Import status
  • Errors and warnings related to data feeds that you have dropped into the /import-inbox directory and that have been processed by the automatic importer
  • Invoke ad-hoc imports on staging using the “Invoke one-time import” link

If you upload a data feed to the staging SFTP server, access the staging portal at https://workbench-staging.bazaarvoice.com/portal to view its status. If you upload a feed to the production SFTP server, the production portal at https://workbench.bazaarvoice.com retains its details.

Uploading product feeds

Deliver your data feeds on a recurring basis to the SFTP location that stores the feed until it is picked up by Bazaarvoice’s automatic import process. Bazaarvoice recommends updating this feed on a daily basis because it must be regenerated and uploaded every time your product inventory changes. Supply a public Secure Socket Shell (SSH) key if you choose to automate this process by using SSH passwordless entry. To compress the data feed before you upload it, use the GZIP utility to save it with a file name extension of *.xml.gz.

Before you go live, upload staging data feeds to the /import-inbox directory of the staging SFTP server. Files in this folder are processed automatically once a day at 2 a.m. Central U.S. time. You can also invoke an ad-hoc import of the data feed by clicking the “Invoke one-time import” link in the Validate Product Feed section of the client portal. You can continue to upload data feeds to the staging SFTP server for testing.

After you go live, upload production data feeds to the /import-inbox directory of the production SFTP server. Bazaarvoice’s production feed-import process automatically picks up files in this folder on a nightly basis.

To be notified when a feed import fails, provide your implementation team with one or more email addresses to add to the notification list.

SFTP connection values

Use the following information to access the Bazaarvoice SFTP location:

  • Staging server – sftp-stg.bazaarvoice.com
  • Production server – sftp.bazaarvoice.com

Contact your Bazaarvoice implementation project manager if you have not received your login credentials.