[TRANSLATION ERROR] There are no messages for this key

Batch Recommendations

With batch recommendations, recommendation job requests can be made and the results will be saved in the client workspace. All the recommendations generated will be saved in a folder named with the request ID and contain one json file per recommendation that has been made. Also Endpoints to check the recommendation work order status and to cancel them also exist.

The number of recommendations made to recipients will be added to the client's request counter, and if the number of recommendations is greater than the available requests for the client, the request will be rejected.

There are five possible statuses for the batch recommendation process:

StatusDescription
queuedThe recommendation request has been logged, but it has not been processed yet.
processingThe recommendation request is being processed.
canceledThe recommendation request has been canceled at the request of the user.
errorAn error occurred while generating the recommendations. No changes have been applied.
completedThe recommendation request completed successfully.

When batch recommendation is requested for the first time (see Schedule Batch Recommendations, the API automatically assigns queued status. To check the updated status, please refer to Get batch recommendation Status.

Schedule Batch Recommendations

The batch recommendation for the given table will be scheduled.

URL

  • Items for each user: POST /{tableId}/users/items/recommend
  • Users for each item: POST /{tableId}/items/users/recommend
  • Items for each item: POST /{tableId}/items/items/recommend
  • Users for each user: POST /{tableId}/users/users/recommend

Parameters

URL parameters:

ParameterMandatoryTypeDescription
tableIdStringID of the table

Fields to be included in the request body:

FieldMandatoryTypeDescription
engineStringEngine to perform the training: content_based or hybrid.
If no engine is specified, the default table engine will be used.
configurationMap<String, Object>Configuration for batch recommendations.

Configuration map available parameters:

Configuration parameterMandatoryTypeDescription
recipientsFilterStringBoolean-returning RSQL expression, which allows you to filter the recipients to be recommended. Only the recipients for which the expression is true will be returned.
recommendationsFilterStringBoolean-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.
interactionFilterStringRSQL expression to filter recommended entities depending on the users' past interactions with the items. It is a combination of [interactionId]==[boolean] expressions (see RSQL for and and or operators). It only works for items to users or users to items recommendations.
popularFilterStringAn integer number or a percentage of the most popular entities (those which have more interactions) to be omitted in the recommendation
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 should be numeric and if there is more than one interaction, the interactionId parameter should be provided.
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.
limitIntegerNumber of recommendations for each recipient. Default value is 500
sortStringRSQL expression used to sort the result list.
diversityDoubleValue 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.

Examples:

Recommendations with the default table engine, for all recipients, using all the items and all the interactions defined for the table:

{
    // no parameters
}

Recommendations with the hybrid engine, only for interaction rating, using filters for both recipients and recommendation entities, with diversity and with a limit of 100 recommendations per recommendation recipient. The interaction filter implies that the recipient will not get recommendations of items that they have already rated. The popular filter excludes the top-20 items with more interactions. The results will be sorted by year ascending:

{
    "engine" : "hybrid",
    "configuration":{
      "recipientsFilter" : "age=gt=65",
      "recommendationsFilter" : "year=lt=1980",
      "interactionFilter" : "rating==false",
      "popularFilter" : "20",
      "interactionId" : "rating",
      "limit" : 100,
      "diversity": 0.45,
      "sort": "year==ASC"
    }
}

Response

CodeName
202Accepted
400Bad Request
401Unauthorized
403Forbidden
404Not Found
500Internal Server Error
503Service Unavailable

JSON that includes the ID and the status of the request.

Example

Schedule content_based items batch recommendation for all users of the movies table, with a max of 100 items per recommendation.

curl -X POST "https://recom.sherpa.ai/v2/recomm/movies/users/items/recommend" \
-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******" \
-d  "{\"engine\":\"content_based\",\"limit\":100}"
{
    "requestId": "0f1105ed-9b09-42d9-a377-635ea44d2519",
    "status": "queued",
    "recommendationsCount" : 939
}

Get Batch Recommendation Status

Return the status of the batch recommendation work order.

URL
GET /{tableId}/recommend/{requestId}

Parameters

URL parameters:

ParameterMandatoryTypeDescription
tableIdStringID of the table
requestIdStringID returned by the work order request

Response

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

JSON that includes the current status of the request.

Example

Get the current status of the request 0f1105ed-9b09-42d9-a377-635ea44d2519.

curl -X GET "https://recom.sherpa.ai/v2/recomm/movies/recommend/0f1105ed-9b09-42d9-a377-635ea44d2519" \
-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******"
{
    "requestId": "0f1105ed-9b09-42d9-a377-635ea44d2519",
    "status": "completed",
    "recommendationsCount" : 939
}

Cancel Batch Recommendation

Cancel a work order request. This can only be done when the status of the request is queued.

URL

DELETE /{tableId}/recommend/{requestId}

Parameters

URL parameters:

ParameterMandatoryTypeDescription
tableIdStringID of the table
requestIdStringID returned by a work order request

Response

CodeName
200OK
400Bad Request
401Unauthorized
403Forbidden
404Not Found
500Internal Server Error
503Service Unavailable

JSON that includes the current status of the request.

Example

Cancel the request 0f1105ed-9b09-42d9-a377-635ea44d2519.

curl -X DELETE "https://recom.sherpa.ai/v2/recomm/movies/recommend/0f1105ed-9b09-42d9-a377-635ea44d2519" \
-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******"
{
    "requestId": "0f1105ed-9b09-42d9-a377-635ea44d2519",
    "status": "canceled",
    "recommendationsCount" : 939
}