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:
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 | |
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=∑Iw(I)∑Iw(I)s(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. s^i=siai, where si,ai 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, s^i=si. | |
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 | Float | 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 only available for the hybrid engine . |
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 | |
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=∑Iw(I)∑Iw(I)s(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. s^u=suau, where su,au 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, s^u=su. | |
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 | Float | 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 only available for the hybrid engine . |
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 | |
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=∑Iw(I)∑Iw(I)s(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. s^i=siai, where si,ai 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, s^i=si. | |
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 | Float | 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 only available for the hybrid engine . |
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 | |
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=∑Iw(I)∑Iw(I)s(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. s^u=suau, where su,au 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, s^u=su. | |
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 | Float | 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 only available for the hybrid engine . |
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
}
]