For the recommendation engine, an item is anything that can be recommended. Items are identified by a unique ID and they can have as many custom attributes as required.

Example item list

Attributes are used for:

• Metadata-based recommendations
• Business rules filtering
• Optimizing the recommendations by feeding them back into the system from other areas

Item Anatomy

Important! All Item property names (keys) should not exceed 32 characters.

Example custom properties

e-commerce site

classified site

For all items:

For real-estate items:

For automobile items:

video streaming site

Some general attributes:

Some video specific attributes:

File-based item catalog update

You can provide an item catalog for Gravity using a TSV, CSV or XML (e.g. RSS 2.0 - Google Merchant) file. The catalog file should be made available over HTTP/HTTPS/FTP and it will be periodically imported into our database.

Crawling

Gravity can also process your site directly to build the item catalog. This means that as soon as there is at least one user event on a certain item, it will be passed over to the Gravity database with all its visible metadata. By “visible”, we mean visible and accessible to our crawling engine from the HTML code (machine-readable format). This way we can build up the site-specific item catalog on our own.

For this, you might need to add the item data to your site with hidden HTML tags in a machine readable format.

📘

Note

Using the crawling methodology, the item deletion is not synchronized immediately. If you would like to have an immediate deleted item synchronization then you should implement an extra server-side API call (see below).

Server-side API item catalog update

For special cases, e.g. if every second counts and very frequent item updates are needed (as is the case for classified sites or video streaming sites) you can use direct server-side API calls. We have publicly available client libraries for Java and PHP. For other programming languages, the REST API is available.

For more details please visit the following pages:

• Java client
• PHP client
• REST API

Tab-delimited item example

The tab-delimited format is a simple format for providing tabular data, where the first line contains the attribute names, and further lines contain the attribute data. Columns are separeted by tabulator characters.

Handling multiple-valued attributes

The fixed table format is purposed to describe items having the same attributes but is not suitable for items with different set of attributes. Some attributes can occur multiple times, for example "Tags", or different items can have different number of custom attributes. To help this situation, the Yusp engine accepts an extended version of tab-delimited format to handle this situation:

• The format allows the same attribute name to occur multiple times in the first line. For example, if every item is at least two level deep in the category hierarchy, you can include the CategoryId attribute name two times in the first line.
• The format allows data lines to have more columns than the header line. In this case, these further columns are interpreted in pairs, the first column in the pair is an attribute name, and the second column in the pair is the attribute value.

Format specification

• The input file can be uncompressed, gzip compressed or a zip compressed package containing one file.
• The file encoding is UTF-8 without BOM
• The first line of the file contains predefined and custom attribute names (For the list of predefined attributes, see the item catalog page). Custom attribute names can occur multiple times. Adjacent attribute names are separated by one tabulator character. Attribute names cannot contain tabulator characters.
• The further lines contain item data, each line represents one item. A line contains attribute values in the same order as the attribute names occur in the header line. Attribute values are separated by one tabulator character. Attribute values cannot contain tabulator character.
• If an item does not have a value for that attribute, it can be left empty, e.g. the tabulator before the value is immediately followed by a tabulator before the next value.
• A data line can have more column than the header line. In this case these further column must occur in pairs. The first column in the pair is interpreted as an attribute name, and the second column is interpreted as the attribute value.

Classified TSV/CSV item catalog example

E-commerce TSV/CSV item catalog example

Video streaming CSV/TSV item catalog example

Comma-delimited item example

The comma-delimited format (CSV) is a simple format for providing tabular data, where the first line contains the attribute names, and further lines contain the attribute data. Columns are separated by comma <,> semicolon <;> pipe <|> or other separator characters (the separator character is auto-detected by our system).

Format specification

• The input file can be uncompressed, gzip compressed or a zip compressed package containing one file.
• The file encoding should be UTF-8 without BOM
• The first line (header) of the file contains predefined and custom attribute names (For the list of predefined attributes, see the item catalog page). Custom attribute names can occur multiple times. Adjacent attribute names are separated by one separator character. Attribute names cannot contain the separator character.
• The further lines contain item data, each line represents one item. A line contains attribute values in the same order as the attribute names occur in the header line. Attribute values are separated by one separator character. Attribute values cannot contain separator character.
• If an item does not have a value for that attribute, it can be left empty, i.e. the separator character before the value is immediately followed by a separator character before the next value.

XML item example

<products>
    <product>
        <itemId>6474337</itemId>
        <title>Iphone 5</title>
        <hidden>false</hidden>
        <url>http://examplewebshop.example.com/6474337</url>
        <imageUrl>http://examplewebshop.img.com/6474337</imageUrl>
        <description>iPhone 5 for sell.</description>
        <region>London</region>
        <city>London</city>
        <price>125</price>
        <categoryPath>Multimedia/Telephone</categoryPath>
        <categoryId>6645</categoryId>
        <companyAd>1</companyAd>
        <adType>sell</adType>
    </product>
    <product>
        <itemId>435675</itemId>
        <title>Sony Xperia</title>
        <hidden>false</hidden>
        <url>http://examplewebshop.example.com/435675</url>
        <imageUrl>http://examplewebshop.img.com/435675</imageUrl>
        <description>Brand new phone for sell!</description>
        <region>Norfolk</region>
        <city>Norwich</city>
        <price>65</price>
        <categoryPath>Multimedia/Telephone</categoryPath>
        <categoryId>6645</categoryId>
        <companyAd>0</companyAd>
        <adType>sell</adType>
    </product>
    <product>
        <itemId>93457566</itemId>
        <title>House in Falmouth</title>
        <hidden>false</hidden>
        <url>http://examplewebshop.example.com/93457566</url>
        <imageUrl>http://examplewebshop.img.com/93457566</imageUrl>
        <description>Old styled family home available for rent.</description>
        <region>Cornwall</region>
        <city>Falmouth</city>
        <price>265</price>
        <categoryPath>Real-Estate/House</categoryPath>
        <categoryId>112</categoryId>
        <companyAd>0</companyAd>
        <adType>rent</adType>
        <size>350</size>
        <rooms>5</rooms>
    </product>
    <product>
        <itemId>46474</itemId>
        <title>BMW 4550</title>
        <hidden>false</hidden>
        <url>http://examplewebshop.example.com/46474</url>
        <imageUrl>http://examplewebshop.img.com/46474</imageUrl>
        <description>This BMW is the perfect car to buy</description>
        <region>Yorkshire</region>
        <city>York</city>
        <price>54300</price>
        <categoryPath>Automobile/Car</categoryPath>
        <categoryId>2</categoryId>
        <companyAd>0</companyAd>
        <adType>sell</adType>
        <year>1989</year>
        <milage>134500</milage>
        <fuel>diesel</fuel>
        <brand>BMW</brand>
        <color>brown</color>
    </product>
</products>