buySAFEshopping.com Data Feed Specifications

Introduction

buySAFEshopping.com accepts product data feeds from merchants for use in its shopping search engine. A data feed is a file that contains information about all the products sold by a site, including the product URL, price, image URL, title, and description.

This document describes how the feed process works and what the feed file format is.

Sending Product Data to buySAFE Product Data files must be consistent with the buySAFE Product Data Feed Specs which are described below. Product Data files must be named using the buySAFE Store Token (e.g. 11111111-2222-3333-4444-55555555.txt) that was assigned during buySAFE account setup. Thus, each Product Data file will contain data for only one Store. Merchants with multiple Stores will have multiple Product Data files. Product Data files must be tab-delimited text files, and should be compressed before transferring the files to buySAFE (.zip or .gz formats are acceptable). The compressed files must maintain their filename (e.g. 11111111-2222-3333-4444-55555555.zip or 11111111-2222-3333- 4444-55555555.txt.gz). Data Feeds should be posted to the buySAFE FTP server (feed.buysafe.com), on a daily basis. Do not create subdirectories for each merchant because the file naming structure provides buySAFE with adequate identification for each merchant. Creating subdirectories will cause the files to be overlooked. A unique FTP username and password will be provided to the Product Syndication Partner following the partner kick-off call with a buySAFE Implementation Manager. Only one username and password is necessary for each Product Syndication Partner.

Feed Process

Feeds are typically uploaded by the merchant to an FTP account at buySAFEshopping.com once a day. Merchants must contact buySAFE to set up an FTP account for their use.

Merchants are instructed not to send the feed file in uncompressed format, but rather to send the file after compressing in zip (i.e., WinZip) or gzip format. The feed file name must indicate whether the file has been compressed in zip format (.zip filename extension) or in gzip format (.gz filename extension).

The feed file name should generally stay the same from one day to the next.

buySAFEshopping.com only accepts passive mode FTP connections (technical detail).

Feed File Format

Feed files are tab-delimited text documents. As described above, feed files must be compressed before uploading to buySAFEshopping.com.

Creating a tab-delimited text document with Microsoft Excel:

On the first row of the spreadsheet enter the names of the attributes that describe your items, each in its own column. In the rows below the header row enter information about your items for the attributes you've chosen. Each item should be listed in a separate row, and its information divided into the appropriate columns.

For example:

To create the tab-delimited text file format you must save the Microsoft Excel spreadsheet in tab-delimited format (File -> Save As -> Save as type: Text/Tab delimited).

Feed format specifications:

The tab-delimited text file format is the same format as can be created by saving a spreadsheet from Microsoft Excel in tab-delimited format. Rows from the spreadsheet correspond to lines in the text file format. The first line of this tab-delimited file contains a set of product attribute names, and every other line of the document contains the attribute values corresponding to a single product. For example:

 link  title  description  price  image_link 

 http://www.foo.com/product1.html  Product 1  An   example  product. 126.33 http://www.foo.com/product1.jpg 

 http://www.foo.com/product2.html  Product 2  Example product 2. 23.12 http://www.foo.com/product2.jpg 

Here, there are five named attributes on the first line: link, title, description, price, and image_link. There are two products described here. The first product has title Product 1 and a price of $126.33. The second product has title Product 2 and a price of $23.12.

As shown, each line consists of fields separated by the tab character. Each field is optionally surrounded by double quote characters. If the text of a field contains the tab character, that field is required to be surrounded by double-quote characters. If the text of a field contains two double-quote characters in a row, those two double-quote characters are interpreted as a single character. For example, in the second line of the example, the description will appear on buySAFEshopping.com as:

An example product.

Fields may not contain end of line characters.

Mandatory Attributes

The following attributes are required for products to appear on buySAFEshopping.com:

link	The URL of the product page. A product page typically shows the details of a single product, along with a button to buy the product.
title	The name of the product. Please ensure that the title only includes information about the product and not about anything else. No keyword spamming/stuffing.
description	A description of the product. Please ensure that the description only includes information about the product and not about anything else. No keyword spamming/stuffing.
price	The price of the product in U.S. dollars.
image_link	The URL of an image of the product. For best viewing on buySAFEshopping.com, the image referred to by this URL should be at least 150 pixels wide and 150 pixels high. If a product does not have an image please leave this attribute field blank.

Highly Recommended Attributes

The following attributes are recommended wherever applicable, as products with these attributes may appear before products without these attributes in the results for some queries (depending on the product's category):

sale_price	The price of the product in U.S. dollars. The value of this attribute differs from the value of the price attribute if this product is on sale. In this case, the original price is given for the price attribute and the sale price is given for the sale_price attribute. If the product is not on sale, the sale_price value may be left empty or the sale_price attribute may be equal to the price attribute.
brand	The brand of the product.
breadcrumb	A hierarchical description of the category of merchandise the product falls into. Examples: Clothing > Mens Clothing > Mens Shirts Appliances > Washing Machines
tags	Additional keywords describing the product. No more than ten keywords please.
department	The department of a clothing item (for example, Mens or Womens).
model	The model name of the product (for example, Powershot SD660).
model_number	Number given to the model (for example, SD660).
mpn	Manufacturer's Product Number. The unique number assigned to the product by the manufacturer.

Additional Attributes

The following attributes are also understood by buySAFEshopping.com:

rating	How well users rate the product, from 1 to 5, with 5 being the highest rating. The value of this field may be a number (for example, "2" or "5") or may be explicitly "2 stars" or "5 stars".
shipping	The shipping cost in U.S. dollars.
upc	Universal Product Code
subject	The subject of a book.
isbn	The ISBN number for a book.
color	A comma-separated list of colors a product comes in. For example, "red,green,teal".
condition	Whether the product is new or used. Acceptable values for this field include "new", "used", and "refurbished".

Additional attributes may be given in the feed file, and those additional attributes may be used at buySAFEshopping.com's discretion.