Item feed requirements

This article presents item feed requirements for AI recommendations.

Before you import item feed to Synerise, become familiar with the feed types, requirements, limits, how you can import the feed and where it will be kept.

Note: The possibility of introducing the IDs of item attributes, which lets you group item variants in terms of their feature such as colors, sizes, models is available upon Synerise support request.

Feed types

AI recommendations make use of the following item feed types:

Feed type	Business application	Method of upload
Item feed	Used as a source of items for ALL recommendation types	- through an API request to a catalog ( Data Management > Catalogs) - through a workflow (`CSV` , `XML feed` , `JSONL` , `JSON` files) to a catalog ( Data Management > Catalogs) - Pulling from an URL as the item feed when Configuring AI engine for AI recommendations ( `Google Merchant Center XML` file) to an AI feed. This method creates an AI feed that contains your item feed in the Settings > AI Engine Configuration. Additionally, it will create an `AI feed` prefixed catalog with the item feed in Data Management > Catalogs (unavailable for editing).
Metadata catalog	Used as a supplementary source of items alongside the item feed for the following recommendation types: - section page - attribute recommendations	- through a simple import to a catalog, - through a workflow to a catalog, - through an API request to a catalog

Item feed in a catalog

General limitations

The name of the item catalog must be an alphanumeric string without any special characters nor whitespaces, following this regex pattern: [a-zA-Z0-9]*.
Item attribute names must be an alphanumeric string without whitespaces, following this regex pattern ^[_a-zA-Z0-9]+[\-_a-zA-Z0-9]*$.
Item attribute string values must be alphanumeric. They can’t contain following characters:
- " - quotation mark
- ’ - inverted comma
- . - dot
- , - comma
- space or any whitespace character
Therefore, complex.name is forbidden and you should rather use camelCase: complexName (preferred) or underscore format: complex_name.
Attribute names are case-sensitive.
Synerise accepts any properly formatted JSON which contains itemId and with proper key names. Later, item attributes are being returned by the API without changing or parsing values, which also applies to HTML/XML tags as values. You should handle the raw data retrieved from API in a way that will avoid the risk of XSS attack.
The item feed limit for visual similarity recommendation model is 1,000,000 items, regardless of the item feed type.

Item format

The format of an item is a JSON. Each object represents an item with its attributes, for instance:

{
    "itemId": "Xa34ad3d",
    "intAttribute": 5,
    "floatAttribute": 2.5124,
    "stringAttribute": "asfdqw",
    "timestampAttribute": 1356846157,
    "booleanAttribute": true,
    "arrayOfStringsAttribute": ["A", "B", "C"],
    "nestedObject": {
        "a": 1,
        "b": "value"
    },
    "nestedObjectsArray": [
        {
            "x": "y"
        }
    ]
}

Attributes

Required attributes

Important: Make sure to use the exact names as provided in the table below when setting up your item feed.

Attribute name	Function	Why is it required?
`itemID`	Unique identifier	Prevents any duplication of items and allows for accurate tracking and management of the items within the feed
`title`	The name of the item	For visibility and searchability of the items and for performing the AI model training on the feed
`category`	The category of an item	For search and filter capabilities and for performing the AI model training on the feed

Accepted attribute values

string: "foo"
integer: 12
float: 12.34
boolean: true/false
nested objects: { "sub": { "a1": "v1", "a2": "v2" } }
array (of strings, integers, floats, booleans, nested objects, arrays): ["foo", "bar"]
timestamp: should be formatted as Unix timestamp, for example, 1356846157
date: 2024-01-01T10:00:00Z or Unix timestamp (12345664000) sent as a string

Item availability attribute

If you want to include the item availability attribute (availability) in your item catalog, the attribute’s value must be a boolean.

Category attribute

category is a special attribute which is used to define the hierarchy of categories which an item belongs to. It must have the following format:

X > Y > Z

Where X is a top level category and Z is the lowest category level. For example, Electronics > Phone and Smartphones > Smartphones. Category levels should be joined with > (literally space>space). When you have an item which belongs to more than one category, you can pass the additionalCategories field in the following format:

"additionalCategories": ["A > B > C", "D > E > F"]

Both category and additionalCategories are used when you filter by categories.

Unique identifier

Each item (each JSON document) must contain an itemId field which is a reserved key used as a unique item identifier. Its value type must be a string and it’s case sensitive. As itemId is an item identifier it is specially treated:

It is always returned by search API
It is always returned by recommendations API
Events (especially page.visit and transaction.charge) should contain matching itemID

Google Merchant Center XML file

For instructions on building a Google Merchant Center XML file compatible with Synerise, see Google Merchant Center XML item feed.

Metadata catalog

The metadata catalog is used to enrich the standard item feed or catalog for section page and attribute recommendation campaigns. This catalog must contain the itemId column, which is the unique value of the attribute. For example, in a catalog that stores categories (category is an attribute), the values in the itemId may include “Hoodie”, “Longsleeve”, “T-shirt”, and so on.

Typically, the catalog contains at least an image that is used as the recommendation tile and the URL of the recommended attribute or category. It can also store data such as descriptions of the attribute (“This category includes the comfiest hoodies”), an alternative title that you want to show in the recommendation (“Comfy hoodies”), and any other data that your implementation requires.

This catalog is usually uploaded as a CSV file.

Metadata for attribute recommendations

Attribute recommendations do not recommend items from the feed or catalog. Instead, they recommend attribute values. When you recommend attribute values, the catalog must contain at least the itemId (the attribute value) and an image link.

Metadata for section recommendations

Section page recommendations recommend both attribute values and items within those values. The metadata catalog enriches the sections that correspond to attribute values (for example brands or categories).

Note: You can read Personalization of the main banner on the homepage use case to see how metadata catalog is used for creating attribute and section page recommendations in a real-life example.

Example:

An attribute recommendation is used to recommend categories. Each category value (for example, “Hoodies”) in the recommendation frame should be displayed with an image that illustrates it.

The link to the image (such as a hoodie for the “Hoodie” category) must be provided in the metadata catalog so it can be shown in the recommendation. You can then use that image in the recommendation frame as a tile that links to the “Hoodie” category page. In the recommendation response, this is what a single recommended category could look like:

        {
            "itemId": "Hoodies",
            "image": "/yourcdn.com/hoodie.png"
            "link": "/yourstore?category=hoodies"
            ...//  additional data from the metadata catalog, if you added some
        },