The Yusp training Developer Hub

Welcome to the Yusp developer hub. You'll find comprehensive guides and documentation to help you start working with Yusp as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

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

itemId

title

hidden

imageUrl

description

6474337

Iphone 5

FALSE

http://examplewebshop.img.com/6474337

iPhone 5 for sell.

435675

Sony Xperia

FALSE

http://examplewebshop.img.com/435675

Brand new phone for sell!

93457566

House in Falmouth

TRUE

http://examplewebshop.img.com/93457566

Old 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

itemId

Unique identifier for the item (string)

title

Name/title of the item

hidden

1 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 name

Example value

Type

Description

categoryPath

Multimedia/Telephone

String

The category hierarchy of the item separated by '/'

categoryId

1455

String

The unique identifier of the item’s category.

url

https://www.items.com/item_123

String

Url of the item page.

imageUrl

https://www.items.com/img/item_123

String

Url of the item's image.

description

This is the description of the example item.

String

Longer description of the item.

price

3450

String

The price of the item.

classified site

For all items:

Attribute name

Example value

Type

Description

companyAd

0

Boolean

Is the item advertised by a company or a natural person.

adType

sell

String

Is the item for sell or rent.

categoryPath

Multimedia/Telephone

String

The category hierarchy of the item separated by '/'

categoryId

1455

String

The unique identifier of the items category.

url

www.items.com/item_123

String

Url of the item page.

imageUrl

www.items.com/img/item_123

String

Url of the item's image.

description

This is the description of the example item.

String

Longer description of the item.

price

3450

String

The price of the item.

For real-estate items:

Attribute name

Example value

Type

Description

rooms

3

Integer

The number of rooms present in the real-estate item.

size

67

Integer

The size of the real-estate item in m2

lot

340

Integer

The size of the lot belonging to the real-estate item in m2

city

London

String

The city the real-estate item is located in.

area

South-Bank

String

The are the real-estate item is located in

For automobile items:

Attribute name

Example value

Type

Description

year

1989

Integer

The year the auto-mobile item was registered in.

milage

200000

Integer

The number of kms the auto-mobile item has driven.

fuel

benzin

String

The fuel type of the auto-mobile item.

brand

BMW

String

The brand of the auto-mobile item.

color

blue

String

The color of the auto-mobile item.

video streaming site

Some general attributes:

Attribute name

Example value

Type

Description

categoryPath

Multimedia/Telephone

String

The category hierarchy of the item separated by '/'

categoryId

1455

String

The unique identifier of the items category.

url

www.items.com/item_123

String

Url of the item page.

imageUrl

www.items.com/img/item_123

String

Url of the item's image.

description

This is the description of the example item.

String

Longer description of the item.

Some video specific attributes:

Attribute name

Example value

Type

Description

length

600

String

The length of the video item in seconds.

genre

action

String

The genre of the video item.

type

film

String

The type of the video item.

rating

3.4

Double

The rating of the video item.

actor

Bruce Willis

String

The actor of the video item.

actorVoice

Rumi Hiiragi

String

The voice actor of the video item.

director

Quentin Tarantino

String

The producer of the video item.

language

English

String

The audio language of the video item.

subtitles

German

String

The 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

ItemId

title

hidden

url

imageUrl

description

region

city

price

categoryPath

categoryId

companyAd

adtype

6474337

Iphone 5

FALSE

http://examplewebshop.example.com/6474337

http://examplewebshop.img.com/6474337

iPhone 5 for sell.

London

London

125

Multimedia/Telephone

6645

1

sell

435675

Sony Xperia

FALSE

http://examplewebshop.example.com/435675

http://examplewebshop.img.com/435675

Brand new phone for sell!

Norfolk

Norwich

65

Multimedia/Telephone

6645

0

sell

93457566

House in Falmouth

FALSE

http://examplewebshop.example.com/93457566

http://examplewebshop.img.com/93457566

Old styled family home available for rent.

Cornwall

Falmouth

265

Real-Estate/House

112

0

rent

size

350

46474

BMW 4550

FALSE

http://examplewebshop.example.com/46474

http://examplewebshop.img.com/46474

This BMW is the perfect car to buy

Yorkshire

York

54300

Automobile/Car

2

0

sell

year

1989

E-commerce TSV/CSV item catalog example

itemId

title

hidden

url

imageUrl

description

price

categoryPath

categoryId

5133472

Iphone 5

FALSE

http://examplewebshop.example.com/5133472

http://examplewebshop.img.com/5133472

The newest iPhone 5

225

Multimedia/Telephone

54

3453248

Sony Xperia

FALSE

http://examplewebshop.example.com/3453248

http://examplewebshop.img.com/3453248

Brand new phone for sell!

165

Multimedia/Telephone

54

857764445

Nokia adapter

FALSE

http://examplewebshop.example.com/857764445

http://examplewebshop.img.com/857764445

Adapter for all new smart Nokie phones

34

Multimedia/Accessory

112

36645

Mouse Pad XG340

FALSE

http://examplewebshop.example.com/36645

http://examplewebshop.img.com/36645

New red mousepads for gamers.

54300

Multimedia/Accessory

2

Video streaming CSV/TSV item catalog example

itemId

title

hidden

url

imageUrl

length

3456

The Dark Knight

FALSE

http://examplewebshop.example.com/3456

http://examplewebshop.img.com/3456

9120

genre

action

genre

crime

genre

drama

type

movie

34553

Game of Thrones

FALSE

http://examplewebshop.example.com/34553

http://examplewebshop.img.com/34553

3600

genre

adventure

genre

drama

genre

fantasy

type

series

46753

Sen to Chihiro no kamikakushi

FALSE

http://examplewebshop.example.com/46753

http://examplewebshop.img.com/46753

7500

genre

animation

genre

adventure

genre

family

type

movie

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>

Updated 8 months ago

Items


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.