[TRANSLATION ERROR] There are no messages for this key

Recommendations

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

When choosing the Hybrid Recommender Engine, 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.

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:

ParameterMandatoryTypeDescription
tableIdStringID of the table
userIdStringID of the user
filterStringBoolean-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.
interactionIdStringID of the main interaction to be used for the recommendation. If undefined, the recommendation ss is performed by taking the weighted average of the scores associated to each interaction, i.e. s=Iw(I)s(I)Iw(I)s = \frac{\sum_I w^{(I)} s^{(I)}}{\sum_I w^{(I)}}, where w(I),s(I)w^{(I)},\, s^{(I)} are the weight and score of the II-th interaction, respectively.
attributeIdStringAttribute ID of the items to be used as a weight in the recommendation, i.e. s^i=siai\hat s_i = s_i \, a_i\,, where si,ais_i,\, a_i\, are the score and the value of the attribute of the ii-th item. The corresponding attribute must be numeric and if there is more than one interaction, the interactionId parameter must be provided. If undefined, s^i=si\hat s_i = s_i \,.
limitStringMax. number of rows to be returned.
afterIdStringID of the last element of the current page, so the elements to be returned will start with the next ID. Useful for implementing pagination.
sortStringRSQL expression used to sort the result list.
diversityFloatValue 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 only available for the hybrid engine.

Response

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

JSON with the recommended items.

Example
Recommend three products to user01.

curl -X GET "https://recom.sherpa.ai/v2/recomm/products/users/user01/items?limit=3" \
-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:

ParameterMandatoryTypeDescription
tableIdStringID of the table
userIdStringID of the user
filterStringBoolean-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.
interactionIdStringID of the main interaction to be used for the recommendation. If undefined, the recommendation ss is performed by taking the weighted average of the scores associated to each interaction, i.e. s=Iw(I)s(I)Iw(I)s = \frac{\sum_I w^{(I)} s^{(I)}}{\sum_I w^{(I)}}, where w(I),s(I)w^{(I)},\, s^{(I)} are the weight and score of the II-th interaction, respectively.
attributeIdStringAttribute ID of the users to be used as a weight in the recommendation, i.e. s^u=suau\hat s_u = s_u \, a_u\,, where su,aus_u,\, a_u\, are the score and the value of the attribute of the uu-th user. The corresponding attribute must be numeric and if there is more than one interaction, the interactionId parameter must be provided. If undefined, s^u=su\hat s_u = s_u \,.
limitStringMax. number of rows to be returned.
afterIdStringID of the last element of the current page, so the elements to be returned will start with the next ID. Useful for implementing pagination.
sortStringRSQL expression used to sort the result list.
diversityFloatValue 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 only available for the hybrid engine.

Response

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

JSON with the recommended users.

Example
Recommend two similar users to user01.

curl -X GET "https://recom.sherpa.ai/v2/recomm/products/users/user01/users?limit=2" \
-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:

ParameterMandatoryTypeDescription
tableIdStringID of the table
itemIdStringID of the item
filterStringBoolean-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.
interactionIdStringID of the main interaction to be used for the recommendation. If undefined, the recommendation ss is performed by taking the weighted average of the scores associated to each interaction, i.e. s=Iw(I)s(I)Iw(I)s = \frac{\sum_I w^{(I)} s^{(I)}}{\sum_I w^{(I)}}, where w(I),s(I)w^{(I)},\, s^{(I)} are the weight and score of the II-th interaction, respectively.
attributeIdStringAttribute ID of the items to be used as a weight in the recommendation, i.e. s^i=siai\hat s_i = s_i \, a_i\,, where si,ais_i,\, a_i\, are the score and the value of the attribute of the ii-th item. The corresponding attribute must be numeric and if there is more than one interaction, the interactionId parameter must be provided. If undefined, s^i=si\hat s_i = s_i \,.
limitStringMax. number of rows to be returned.
afterIdStringID of the last element of the current page, so the elements to be returned will start with the next ID. Useful for implementing pagination.
sortStringRSQL expression used to sort the result list.
diversityFloatValue 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 only available for the hybrid engine.

Response

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

JSON with the recommended items.

Example
Recommend three products related to item01.

curl -X GET "https://recom.sherpa.ai/v2/recomm/products/items/item01/items?limit=3" \
-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:

ParameterMandatoryTypeDescription
tableIdStringID of the table
itemIdStringID of the item
filterStringBoolean-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.
interactionIdStringID of the main interaction to be used for the recommendation. If undefined, the recommendation ss is performed by taking the weighted average of the scores associated to each interaction, i.e. s=Iw(I)s(I)Iw(I)s = \frac{\sum_I w^{(I)} s^{(I)}}{\sum_I w^{(I)}}, where w(I),s(I)w^{(I)},\, s^{(I)} are the weight and score of the II-th interaction, respectively.
attributeIdStringAttribute ID of the users to be used as a weight in the recommendation, i.e. s^u=suau\hat s_u = s_u \, a_u\,, where su,aus_u,\, a_u\, are the score and the value of the attribute of the uu-th user. The corresponding attribute must be numeric and if there is more than one interaction, the interactionId parameter must be provided. If undefined, s^u=su\hat s_u = s_u \,.
limitStringMax. number of rows to be returned.
afterIdStringID of the last element of the current page, so the elements to be returned will start with the next ID. Useful for implementing pagination.
sortStringRSQL expression used to sort the result list.
diversityFloatValue 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 only available for the hybrid engine.

Response

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

JSON with the recommended users.

Example
Recommend two users that may be interested in the product item01.

curl -X GET "https://recom.sherpa.ai/v2/recomm/products/items/item01/users?limit=2" \
-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
    }
]