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:

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:

Fields to be included in the request body:

Configuration map available parameters:

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

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:

Response

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:

Response

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
}