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

itemIdtitlehiddenimageUrldescription
6474337Iphone 5FALSEhttp://examplewebshop.img.com/6474337iPhone 5 for sell.
435675Sony XperiaFALSEhttp://examplewebshop.img.com/435675Brand new phone for sell!
93457566House in FalmouthTRUEhttp://examplewebshop.img.com/93457566Old styled family home available for rent.

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

Item Property Name (Key)Description
itemIdUnique identifier for the item (string)
titleName/title of the item
hidden1 or "true" if the item should not be recommended
<custom_property>Any additional information about the item, e.g. url, categoryPath, description, author, color, ...

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

Example custom properties

e-commerce site

Attribute nameExample valueTypeDescription
categoryPathMultimedia/TelephoneStringThe category hierarchy of the item separated by '/'
categoryId1455StringThe unique identifier of the item’s category.
urlhttps://www.items.com/item_123StringUrl of the item page.
imageUrlhttps://www.items.com/img/item_123StringUrl of the item's image.
descriptionThis is the description of the example item.StringLonger description of the item.
price3450StringThe price of the item.

classified site

For all items:

Attribute nameExample valueTypeDescription
companyAd0BooleanIs the item advertised by a company or a natural person.
adTypesellStringIs the item for sell or rent.
categoryPathMultimedia/TelephoneStringThe category hierarchy of the item separated by '/'
categoryId1455StringThe unique identifier of the items category.
urlwww.items.com/item_123StringUrl of the item page.
imageUrlwww.items.com/img/item_123StringUrl of the item's image.
descriptionThis is the description of the example item.StringLonger description of the item.
price3450StringThe price of the item.

For real-estate items:

Attribute nameExample valueTypeDescription
rooms3IntegerThe number of rooms present in the real-estate item.
size67IntegerThe size of the real-estate item in m2
lot340IntegerThe size of the lot belonging to the real-estate item in m2
cityLondonStringThe city the real-estate item is located in.
areaSouth-BankStringThe are the real-estate item is located in

For automobile items:

Attribute nameExample valueTypeDescription
year1989IntegerThe year the auto-mobile item was registered in.
milage200000IntegerThe number of kms the auto-mobile item has driven.
fuelbenzinStringThe fuel type of the auto-mobile item.
brandBMWStringThe brand of the auto-mobile item.
colorblueStringThe color of the auto-mobile item.

video streaming site

Some general attributes:

Attribute nameExample valueTypeDescription
categoryPathMultimedia/TelephoneStringThe category hierarchy of the item separated by '/'
categoryId1455StringThe unique identifier of the items category.
urlwww.items.com/item_123StringUrl of the item page.
imageUrlwww.items.com/img/item_123StringUrl of the item's image.
descriptionThis is the description of the example item.StringLonger description of the item.

Some video specific attributes:

Attribute nameExample valueTypeDescription
length600StringThe length of the video item in seconds.
genreactionStringThe genre of the video item.
typefilmStringThe type of the video item.
rating3.4DoubleThe rating of the video item.
actorBruce WillisStringThe actor of the video item.
actorVoiceRumi HiiragiStringThe voice actor of the video item.
directorQuentin TarantinoStringThe producer of the video item.
languageEnglishStringThe audio language of the video item.
subtitlesGermanStringThe subtitle language of the video item.

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:

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

ItemIdtitlehiddenurlimageUrldescriptionregioncitypricecategoryPathcategoryIdcompanyAdadtype
6474337Iphone 5FALSEhttp://examplewebshop.example.com/6474337http://examplewebshop.img.com/6474337iPhone 5 for sell.LondonLondon125Multimedia/Telephone66451sell
435675Sony XperiaFALSEhttp://examplewebshop.example.com/435675http://examplewebshop.img.com/435675Brand new phone for sell!NorfolkNorwich65Multimedia/Telephone66450sell
93457566House in FalmouthFALSEhttp://examplewebshop.example.com/93457566http://examplewebshop.img.com/93457566Old styled family home available for rent.CornwallFalmouth265Real-Estate/House1120rentsize350
46474BMW 4550FALSEhttp://examplewebshop.example.com/46474http://examplewebshop.img.com/46474This BMW is the perfect car to buyYorkshireYork54300Automobile/Car20sellyear1989

E-commerce TSV/CSV item catalog example

itemIdtitlehiddenurlimageUrldescriptionpricecategoryPathcategoryId
5133472Iphone 5FALSEhttp://examplewebshop.example.com/5133472http://examplewebshop.img.com/5133472The newest iPhone 5225Multimedia/Telephone54
3453248Sony XperiaFALSEhttp://examplewebshop.example.com/3453248http://examplewebshop.img.com/3453248Brand new phone for sell!165Multimedia/Telephone54
857764445Nokia adapterFALSEhttp://examplewebshop.example.com/857764445http://examplewebshop.img.com/857764445Adapter for all new smart Nokie phones34Multimedia/Accessory112
36645Mouse Pad XG340FALSEhttp://examplewebshop.example.com/36645http://examplewebshop.img.com/36645New red mousepads for gamers.54300Multimedia/Accessory2

Video streaming CSV/TSV item catalog example

itemIdtitlehiddenurlimageUrllength
3456The Dark KnightFALSEhttp://examplewebshop.example.com/3456http://examplewebshop.img.com/34569120genreactiongenrecrimegenredramatypemovie
34553Game of ThronesFALSEhttp://examplewebshop.example.com/34553http://examplewebshop.img.com/345533600genreadventuregenredramagenrefantasytypeseries
46753Sen to Chihiro no kamikakushiFALSEhttp://examplewebshop.example.com/46753http://examplewebshop.img.com/467537500genreanimationgenreadventuregenrefamilytypemovie

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>