Recommendations

This section describes the available recommender systems. For a detailed description of filters, please refer to RSQL.

When choosing the Hybrid or ISVD Recommender Engines, every entity included in the list of recommendations comes with a percent match score. This score, a number between 0 and 100, indicates the degree of affinity between the recommended entity and the recipient. The Factorization Machines Engine returns a value that represents the expected interaction value if the interaction is continuous, and a score between 0 and 100 otherwise. The Most Popular Recommender Engine returns a score between 0 and 100, related to the popularity of the entities in terms of interaction counts. Finally, the Ensemble Recommender Engine returns a score as well, which is calculated based on the weighted scores of the engines defined in the setup.

In order to use the ensemble engine to make recommendations, remember to configure it and train every engine in the configuration.

Items to a User

Recommend top-N items that are most likely to be of great value to a given user, based on said user’s past interactions with the items.

URL
GET /{tableId}/users/{userId}/items

Parameters

URL parameters:

Parameter	Mandatory	Type	Description
tableId	✓	String	ID of the table
userId	✓	String	ID of the user
filter		String	Boolean-returning RSQL expression, which allows you to filter the items to be listed. Only the items for which the expression is true will be returned.
interactionFilter		String	RSQL expression to filter items depending on the user's past interactions with them. It is a combination of [interactionId]==[boolean] expressions (see RSQL for and and or operators).
popularFilter		String	An integer number or a percentage of the most popular items (those which have been interacted the most) to be omitted in the recommendation. It requires the Most Popular Recommender Engine to be trained.
interactionId		String	ID of the main interaction to be used for the recommendation. If undefined, the recommendation $s$ is performed by taking the weighted average of the scores associated to each interaction, i.e. $s = \frac{\sum_I w^{(I)} s^{(I)}}{\sum_I w^{(I)}}$ , where $w^{(I)},\, s^{(I)}$ are the weight and score of the $I$ -th interaction, respectively.
attributeId		String	Attribute ID of the items to be used as a weight in the recommendation, i.e. $\hat s_i = s_i \, a_i\,$ , where $s_i,\, a_i\,$ are the score and the value of the attribute of the $i$ -th item. The corresponding attribute must be numeric and if there is more than one interaction, the interactionId parameter must be provided. If undefined, $\hat s_i = s_i \,$ .
limit		String	Max. number of rows to be returned.
afterId		String	ID of the last element of the current page, so the elements to be returned will start with the next ID. Useful for implementing pagination.
sort		String	RSQL expression used to sort the result list.
diversity		Double	Value between 0 and 1 representing the amount of diversity, where 0 means no diversity and 1 means a high level of diversity. If undefined, it defaults to 0. Note that diversity can reduce the degree of matching. The diversity parameter is available for the `hybrid`, `FM`, `ISVD`, `Most popular` and `ensemble` engines. Please be aware that `FM`, `ISVD`, `Most popular` and `ensemble` engines require the tags extracted from the model for the diversity to work.
detailed		String	Set as `true` to return the attributes of the recommended items.

Response

Code	Name
200	OK
400	Bad Request
401	Unauthorized
404	Not Found
429	Too Many Requests
500	Internal Server Error
503	Service Unavailable

JSON with the recommended items.

Example
Recommend three products to user01 which they have not already purchased.

curl -X GET "https://recom.sherpa.ai/v2/recomm/products/users/user01/items?limit=3&interactionFilter=purchase==false" \
-H  "Content-Type: application/json" \
-H  "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H  "X-Sherpa-timestamp: 1548084514112" \
-H  "X-Sherpa-nonce: XXXX-SHERPA-RANDOM-UUID-XXXX" \
-H  "X-Sherpa-hmac: xxxxyyyyyyy***signature******"

[
    {
    	"itemId": "item03",
    	"match": 95.32
    },
    {
    	"itemId": "item01",
    	"match": 91.23
    },
    {
    	"itemId": "item04",
    	"match": 88.07
    }
]

Users to a User

Get users that are similar to a given user, based on the user’s interactions and values of attributes.

URL
GET /{tableId}/users/{userId}/users

Parameters

URL parameters:

Parameter	Mandatory	Type	Description
tableId	✓	String	ID of the table
userId	✓	String	ID of the user
filter		String	Boolean-returning RSQL expression, which allows you to filter the users to be listed. Only the users for which the expression is true will be returned.
popularFilter		String	An integer number or a percentage of the most popular users (those who have interacted the most) to be omitted in the recommendation. It requires the Most Popular Recommender Engine to be trained.
interactionId		String	ID of the main interaction to be used for the recommendation. If undefined, the recommendation $s$ is performed by taking the weighted average of the scores associated to each interaction, i.e. $s = \frac{\sum_I w^{(I)} s^{(I)}}{\sum_I w^{(I)}}$ , where $w^{(I)},\, s^{(I)}$ are the weight and score of the $I$ -th interaction, respectively.
attributeId		String	Attribute ID of the users to be used as a weight in the recommendation, i.e. $\hat s_u = s_u \, a_u\,$ , where $s_u,\, a_u\,$ are the score and the value of the attribute of the $u$ -th user. The corresponding attribute must be numeric and if there is more than one interaction, the interactionId parameter must be provided. If undefined, $\hat s_u = s_u \,$ .
limit		String	Max. number of rows to be returned.
afterId		String	ID of the last element of the current page, so the elements to be returned will start with the next ID. Useful for implementing pagination.
sort		String	RSQL expression used to sort the result list.
diversity		Double	Value between 0 and 1 representing the amount of diversity, where 0 means no diversity and 1 means a high level of diversity. If undefined, it defaults to 0. Note that diversity can reduce the degree of matching. The diversity parameter is available for the `hybrid`, `FM`, `ISVD`, `Most popular` and `ensemble` engines. Please be aware that `FM`, `ISVD`, `Most popular` and `ensemble` engines require the tags extracted from the model for the diversity to work.
detailed		String	Set as `true` to return the attributes of the recommended users.

Response

Code	Name
200	OK
400	Bad Request
401	Unauthorized
404	Not Found
429	Too Many Requests
500	Internal Server Error
503	Service Unavailable

JSON with the recommended users.

Example
Recommend two similar users to user01. Exclude the 2% of the users who have interacted the most.

curl -X GET "https://recom.sherpa.ai/v2/recomm/products/users/user01/users?limit=2&popularFilter=2%25" \
-H  "Content-Type: application/json" \
-H  "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H  "X-Sherpa-timestamp: 1548084514112" \
-H  "X-Sherpa-nonce: XXXX-SHERPA-RANDOM-UUID-XXXX" \
-H  "X-Sherpa-hmac: xxxxyyyyyyy***signature******"

[
    {
    	"userId": "user04",
    	"match": 94.75
    },
    {
    	"userId": "user02",
    	"match": 93.81
    }
]

Items to an Item

Recommend a set of items that are somehow related to one given item. A typical scenario is when a user is viewing an item. Then, you may display other items to the user that they might be also interested in. The recommendation request gives you the Top-N of such items.

URL
GET /{tableId}/items/{itemId}/items

Parameters

URL parameters:

Parameter	Mandatory	Type	Description
tableId	✓	String	ID of the table
itemId	✓	String	ID of the item
filter		String	Boolean-returning RSQL expression, which allows you to filter the items to be listed. Only the items for which the expression is true will be returned.
popularFilter		String	An integer number or a percentage of the most popular items (those which have been interacted the most) to be omitted in the recommendation. It requires the Most Popular Recommender Engine to be trained.
interactionId		String	ID of the main interaction to be used for the recommendation. If undefined, the recommendation $s$ is performed by taking the weighted average of the scores associated to each interaction, i.e. $s = \frac{\sum_I w^{(I)} s^{(I)}}{\sum_I w^{(I)}}$ , where $w^{(I)},\, s^{(I)}$ are the weight and score of the $I$ -th interaction, respectively.
attributeId		String	Attribute ID of the items to be used as a weight in the recommendation, i.e. $\hat s_i = s_i \, a_i\,$ , where $s_i,\, a_i\,$ are the score and the value of the attribute of the $i$ -th item. The corresponding attribute must be numeric and if there is more than one interaction, the interactionId parameter must be provided. If undefined, $\hat s_i = s_i \,$ .
limit		String	Max. number of rows to be returned.
afterId		String	ID of the last element of the current page, so the elements to be returned will start with the next ID. Useful for implementing pagination.
sort		String	RSQL expression used to sort the result list.
diversity		Double	Value between 0 and 1 representing the amount of diversity, where 0 means no diversity and 1 means a high level of diversity. If undefined, it defaults to 0. Note that diversity can reduce the degree of matching. The diversity parameter is available for the `hybrid`, `FM`, `ISVD`, `Most popular` and `ensemble` engines. Please be aware that `FM`, `ISVD`, `Most popular` and `ensemble` engines require the tags extracted from the model for the diversity to work.
detailed		String	Set as `true` to return the attributes of the recommended items.

Response

Code	Name
200	OK
400	Bad Request
401	Unauthorized
404	Not Found
429	Too Many Requests
500	Internal Server Error
503	Service Unavailable

JSON with the recommended items.

Example
Recommend three products related to item01. Exclude the top-10 items with more interactions.

curl -X GET "https://recom.sherpa.ai/v2/recomm/products/items/item01/items?limit=3&popularFilter='10'" \
-H  "Content-Type: application/json" \
-H  "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H  "X-Sherpa-timestamp: 1548084514112" \
-H  "X-Sherpa-nonce: XXXX-SHERPA-RANDOM-UUID-XXXX" \
-H  "X-Sherpa-hmac: xxxxyyyyyyy***signature******"

[
    {
    	"itemId": "item05",
    	"match": 96.48
    },
    {
    	"itemId": "item04",
    	"match": 94.48
    },
    {
    	"itemId": "item02",
    	"match": 91.55
    }
]

Users to an Item

Recommend users that are likely to be interested in a given item.

URL
GET /{tableId}/items/{itemId}/users

Parameters

URL parameters:

Parameter	Mandatory	Type	Description
tableId	✓	String	ID of the table
itemId	✓	String	ID of the item
filter		String	Boolean-returning RSQL expression, which allows you to filter the users to be listed. Only the users for which the expression is true will be returned.
interactionFilter		String	RSQL expression to filter users depending on their past interactions with the item. It is a combination of [interactionId]==[boolean] expressions (see RSQL for and and or operators).
popularFilter		String	An integer number or a percentage of the most popular users (those who have interacted the most) to be omitted in the recommendation. It requires the Most Popular Recommender Engine to be trained.
interactionId		String	ID of the main interaction to be used for the recommendation. If undefined, the recommendation $s$ is performed by taking the weighted average of the scores associated to each interaction, i.e. $s = \frac{\sum_I w^{(I)} s^{(I)}}{\sum_I w^{(I)}}$ , where $w^{(I)},\, s^{(I)}$ are the weight and score of the $I$ -th interaction, respectively.
attributeId		String	Attribute ID of the users to be used as a weight in the recommendation, i.e. $\hat s_u = s_u \, a_u\,$ , where $s_u,\, a_u\,$ are the score and the value of the attribute of the $u$ -th user. The corresponding attribute must be numeric and if there is more than one interaction, the interactionId parameter must be provided. If undefined, $\hat s_u = s_u \,$ .
limit		String	Max. number of rows to be returned.
afterId		String	ID of the last element of the current page, so the elements to be returned will start with the next ID. Useful for implementing pagination.
sort		String	RSQL expression used to sort the result list.
diversity		Double	Value between 0 and 1 representing the amount of diversity, where 0 means no diversity and 1 means a high level of diversity. If undefined, it defaults to 0. Note that diversity can reduce the degree of matching. The diversity parameter is available for the `hybrid`, `FM`, `ISVD`, `Most popular` and `ensemble` engines. Please be aware that `FM`, `ISVD`, `Most popular` and `ensemble` engines require the tags extracted from the model for the diversity to work.
detailed		String	Set as `true` to return the attributes of the recommended users.

Response

Code	Name
200	OK
400	Bad Request
401	Unauthorized
404	Not Found
429	Too Many Requests
500	Internal Server Error
503	Service Unavailable

JSON with the recommended users.

Example
Recommend two users that may be interested in the product item01 and that have not bought it already.

curl -X GET "https://recom.sherpa.ai/v2/recomm/products/items/item01/users?limit=2&interactionFilter=purchase==false" \
-H  "Content-Type: application/json" \
-H  "X-Sherpa-apikey: XXXX-SHERPA-DELIVERED-PUBLIC-APIKEY-XXXX" \
-H  "X-Sherpa-timestamp: 1548084514112" \
-H  "X-Sherpa-nonce: XXXX-SHERPA-RANDOM-UUID-XXXX" \
-H  "X-Sherpa-hmac: xxxxyyyyyyy***signature******"

[
    {
    	"userId": "user03",
    	"match": 94.35
    },
    {
    	"userId": "user01",
    	"match": 90.46
    }
]