4. Feed - General Requirements and Additional Parameters
Last updated
Was this helpful?
Last updated
Was this helpful?
Product feed is one of the key components of the personalization platform integration. Recommendations are built based on the product feed. The quality of recommendations directly depends on the quality of the product feed and the amount of information conveyed in it. During the integration process, we will assist you in creating an optimal set of fields that will provide users with high-quality product recommendations within any of the strategies.
Product feed is uploaded to Gravity Field as a file. The file should be available for download via a direct link. The recommended feed format is CSV; however, other formats (like JSON or XML) can also be used but do require writing a parser function in . The parcer will be required for product feeds consisting of multiple files.
The CSV file delimiter is a comma;
The price delimiter in the CSV file is a period (value type - float);
The maximum number of characters in a column is 1000;
The feed is limited to 1000 columns;
Column names must be in lowercase, with only "_" as a special character allowed;
If the value contains a comma, the entire value must be enclosed in double quotes ("value");
The image_url property must contain an image in the standard size as on category pages (this image will be displayed in recommendation widgets);
image_url cannot contain empty values. If there is no image for a specific product, a link to a placeholder image must be provided;
All fields with boolean values, except for in_stock, must be filled in the true/[empty] format for correct affinity calculation.
Fields with the lng parameter (used for multilingual/multilocal setup) cannot be used for affinity calculation.
Mandatory columns description
sku*
Unique product identifier
string (up to 256 characters)
12378
group_id*
Identifier of group of products that differ in some product attributes (variants of a single product)
string (up to 256 characters)
124578
name*
Product name
string (up to 1000 characters)
Dresses
url*
Product page URL
string (up to 1000 characters)
https://site.com/clothes/women/dresses/12447
price*
Product Price
float
50.00
in_stock*
Product availability
boolean
true / false
image_url*
Product image URL
string (up to 1000 characters)
https://site.com/image.jpg
categories*
The categories associated with the product from general to specific
String (separator "|" with no extra spaces, up to 1000 characters)
Clothes|Women|Dressses
keywords (optional but strongly recommended)
Additional product information separated by "|". Filling in this property is necessary for calculating product similarity (only for the Similarity strategy). Keywords should be specified from general to specific. When checking for matches, the system removes the last word if the entire set does not match. For example, if the keyword set is "Outerwear|Women|Coat|Black" - if there are no products with the exact same set of keywords, the system will search for products with keywords "Outerwear|Women|Coat" and so on until only the first keyword remains.
String (up to 1000 characters)
brand|style|season
In addition to the mandatory feed columns, there are four additional types of data that can expand your capabilities and improve the quality of recommendations.
Data for Visualization of Recommendations: this often includes product rating, review count, or the price of a product before discount.
Data Required for Proper Functioning of Recommendations: if, for instance, the cart addition method works with an identifier different from the SKU, this identifier must be added to the feed.
Data for Additional Logic in Recommendation Algorithms: for example, if you need to display only products that are available for a credit purchase, an indicator of credit availability for that product should be added to the feed.
Data for Affinity Calculation: It's recommended to select product properties that influence users’ buying behavior, are filled for most products (or at least for key categories), and have a limited number of possible values. For instance, for a clothing online store, suitable properties could include "season," "style," "color," and "brand." Unsuitable properties might include "size" (if sizes are not standardized across the site), "country of production," and "fastening type." There's a limit of 10 columns with data for affinity calculation in a feed.
We recommend including all products available to users on the website/app in the feed, even those that are out of stock. This enables strategies that offer users alternatives for products currently unavailable.
However, in cases where users potentially have access to all historical products, including those that were discontinued many years ago, it's advisable to limit the inclusion of out-of-stock items in the feed to the last 6 months since they went out of stock.
The following parameters are commonly used by our clients, and we've gathered them in the documentation to facilitate feed creation for those new to personalization.
old_price
Strikethrough price for discounted items, only filled for products with a discounted price. NB!: 'price' ≠ 'old_price'.
float
75.00
review_count
Number of reviews for the product.
string
15
rating
Product rating (typically from 0 to 10, equivalent to a scale of 0 to 5 stars with a half-star increment).
string
4
is_sale
If the product is part of a sale.
boolean
true
sale_badge_url
If badges are present on the site, provide the badge image URL.
string
https://site.com/img.png
is_bestseller
If the product is a bestseller.
boolean
true
bestseller_badge_url
If there are badges for bestsellers on the site, provide the badge image URL.
string
https://site.com/badge_img.png
is_new
If the product is new.
boolean
true
new_badge_url
URL of the badge image if a badge is displayed for the product.
string
https://site.com/badge_img.png
in_stock_status
Relative inventory level of the product.
string
low/medium/high
margin_group
Product's margin group.
string
low/medium/high
product_accessory
Field distinguishing between products, accessories for other products, and services provided by the store. Aids in accurate cross-sell recommendations.
string
product/accessory/service
brand
Brand of the product's manufacturer.
string
Samsung
You can also read more about examples of feeds by verticals:
In the context of a standard integration, working with the feed is an iterative process that consists of the following stages:
Preparing a Brief Feed Specification: In this step, we create a brief document outlining the information expected in the feed. The list of expected columns is constructed from mandatory columns, columns recommended for the client's vertical, and specific columns recommended for the client. The list includes as much data as possible based on our knowledge of the client and agreed-upon use cases. Often, it's acceptable to start with a feed that doesn't contain all the expected columns and add additional data later as the work progresses.
Validating the Feed: The received feed is validated against the general requirements outlined in the documentation and the specifications from the brief. The validation generates a document which suggests recommended changes. In some cases, this stage might involve multiple iterations, addressing issues such as feeds not meeting basic requirements or unexpected values in certain columns (e.g., 10,000 different values in the "color" field due to various spellings, languages, or encodings for the same color).
Loading the Feed and Widget Development: Once the feed is technically ready for upload to the platform, it is loaded into the interface, and a task is set for a test widget development. During this phase, additional nuances might be identified, which could lead to the need for adding or modifying columns in the feed.
Launching Personalization Cases: With the finalized feed loaded into the platform, you can start launching recommendation widgets and other personalization use cases. However, there are scenarios where additional columns might need to be added to the feed:
Certain personalization cases require additional data, which can potentially lead to feed modifications.
New data might become available for the business, which could be useful, for example, for calculating user affinities.
We periodically revisit the feed and provide suggestions to clients for adding specific information to enhance the platform's capabilities and recommendation algorithms.
Creating the ideal feed is a creative process involving multiple stakeholders on both the Gravity Field and client sides. It's based on a deep understanding of the product assortment, user behavior, and the continuous enrichment of the product database.