Seldon REST API for Content Recommendation

The Seldon Recommendation REST API interacts with three main concepts:

Use the relevant API endpoint to provide content recommendations

An API method can be called with the following template

[GET|POST]      /endpoint?oauth_token=t

For security reasons using the HTTPS protocol is recommended.

API Input Endpoints

This section outlines the endpoints that allow you to input data the API needs to support the personalisation and recommendation methods.

Items

An item is an element within the service identified by id and name. An item generally maps to a piece of content that users interact with.

A service may have different pre-defined item types, and for each item type a set of attributes can be specified.

POST   /items

Input

Example

The service is an E-commerce website selling music and video games.

Item types:

The two item types have different attributes:

Music Item Attributes:

(pop [value_id 1], rock [value_id 2], rap [value_id 3])

Video game Item Attributes:

where:

The JSON to post a music item [‘xxx’,‘yyy’,‘rock’,12.99] having id ‘abc’ using the attributeName map:

{
    "id" : "abc",
    "type" : 1,
    "name" : "xxx",
    "attributesName" : { 
    		     "title"        :   "xxx",
		     "artist"        :   "yyy",
		     "genre"        :   "rock",
		     "price"        :   12.99 
		     }    
}

The method to add a video game item [‘www’,‘sport’,‘wii’,29.99] having id ‘def’ using the attribute map is:

{
    "id" : "def",
    "type" : 2,
    "name" : "www"
    "attributes” : {
                        5        :   "www",
			6        :   2,
			7        :   1,
			8        :   29.99
		}    
}

Users

A user is a service customer identified by an id and a username. A set of user attributes (demographics) can be defined.

POST     /users

Input

Example

The service is a Social Network website.

The user attributes are:

where:

The JSON to post a user [‘male’,29,‘es’,‘New York, US’] having id ‘123’ and username ‘xxx’ using the attribute map:

{
    "id" : "123",
    "username" : "xxx"
    "active" : true,
    "attributes": {
              	  1        :        1,
		  2        :        29,
		  3        :        3,
		  4        :        "New York,US"
		  }    
}

and using the attributesName map:

{
    "id" : "123",
    "username" : "xxx"
    "active" : true,
    "attributesName" : {
                        "Gender"        :        "male",
			"Age"                :        29,
			"Language"        :        "es",
			"Location"        :        "New York,US"
			}    
}

Actions

An action is any interaction of a user with an item within the service. A service may have different action type and may specify further optional information as value, comment and tags.

POST     /actions

Input

Example

The service is an e-commerce website.

The action types are:

The JSON to post a click action performed by user “xxx” on the item “yyy”:

{
"user" : "xxx",
"item" : "yyy",
"type" : 1
}

The JSON to post a page view action performed by the user “xxx” on the item “yyy” that lasted 40 seconds:

{
"user" : "xxx",
"item" : "yyy",
"type" : 2,
"value": 40
}

The JSON to post a review action performed by the user “xxx” on the item “yyy” with rating 4 and comment “…”:

{
"user"    :        "xxx",
"item"    :        "yyy",
"type"    :        2,
"value"   :        4,
"comment" : "..."
}

Recommend Items

A list of recommended items can be retrieved for a user. The list size can be specified with a limit. The filter type, for selecting only a specific item type, or dimension, for selecting items in a specific category can be applied. If the service has provided textual content for the items, a personalized search can be performed specifying the keyword parameter. The relevant items matching the keywords are retrieved and reordered for the specified user.

Scenario

This method could be used as part of the home page for a user to provide links to pages for items they may have interest in. The keyword parameter can be used to provide a personalised search engine for the service.

GET     /users/{user_id}/recommendations

Parameters

Example

The API call to get the top 20 recommend items for the user ‘xxx’:

GET /users/xxx/recommendations?limit=20

The API call to get the top 10 recommended items in the dimension 3 (for example “genre=rock”):

GET /users/xxx/recommendations?dimension=3

Output

{
  "list" :[
           {"item"        :        "x", "pos"                :        "1"},
	   {"item"        :        "y", "pos"                :        "2"}
	   ]    
}

where list is an array containing a list of items. For each item the pos specify the rank in the recommendation list

Appendix

Dimensions

A dimension is a subset of the item set based on the item attributes.

Each item attribute-value generates a dimension containing all the items having the specific attribute-value.

Dimensions allow the item space to be divided into relevant semantic sections which can then be used to characterize users’ preferences and behaviour (for example dimensions can be used to spot a user’s interest for specifics topics and categories, price range, content language and so forth).

Example

The service is an e-commerce music website. The item set is composed of songs.

The item attribute definition is:

Where:

We’ll have the following dimension definition:

This item would be in the dimension2 and dimension5:

Demographics

A demographic is a subset of the user set based on the user attributes.

Each user attribute-value generates a demographic containing all the users having the specific attribute-value. Demographics allow the user space to be divided into useful semantic sections which can help in clustering items for classes of users and provide demographic-based recommendations for new users.

Example

The service is a Social Network.

The user attribute definition is:

where:

We might have the following demographic definition:

Note that the attribute username is not used for the demographics creation since it’s not a property that could classify the user set.

This user would be in the dimension2 and dimension4: