Recommendation¶

Get Similar Items Recommendations¶

GET recommendation/items/<str:item_id>/items/¶

Note

Authorized Roles: root, manager, backend, frontend

Get similar items.

Query Parameters

amt (int) – Optional. [max: 64] Maximum amount of items returned
cursor (string) – Optional. Pagination cursor, typically from the next_cursor value of the previous response
filters (list-of-(string|object)) –
Optional. Filter on item properties [see Filtering on Item Property]

A filter can either be given as a JSON object, or as a string compatible with URL query params formatted like '<PROPERTY_NAME>:<OP>' or '<PROPERTY_NAME>:<OP>:<VALUE>'. The field value is incompatible with notempty.

Inner fields:
- property_name (string) – Item-property name
- op (enum) – choices: [eq, lt, lte, gt, gte, in, notempty, neq, notin] Filter Operator
- value (any) – Filter Value

EXAMPLE QUERY PARAMS¶

?amt=10&filters=price:lt:10&filters=genres:eq:drama

Response JSON Object

items_id (ID-array) – Array of items IDs
next_cursor (string) – Pagination cursor to use in next request to get more items
warnings (list-of-string) – Optional. List of warnings

EXAMPLE RESPONSE¶

  {
      "items_id": [
          "c3391d83-553b-40e7-818e-fcf658ec397d",
          "c2a73584-bbd0-4f04-b497-26bf70152932"
      ],
      "next_cursor": "HLe-e1Sq..."
  }

Errors:

ServerUnavailable with error name DATABASE_NOT_READY if no ML model has been trained for this database
NotFoundError with error name ITEM_NOT_FOUND if the item does not exist
WrongData with error name WRONG_DATA_TYPE if any filter is invalid

Get Session-Based Items Recommendations¶

POST recommendation/sessions/items/¶

Note

Authorized Roles: root, manager, backend, frontend

Get items recommendations given the ratings of an anonymous session. Note that the HTTP verb is POST so that ratings can be sent in the body, but the endpoint is stateless as GET.

Request JSON Object

amt (int) – Optional. [max: 64] Maximum amount of items returned
cursor (string) – Optional. Pagination cursor, typically from the next_cursor value of the previous response
filters (list-of-(string|object)) –
Optional. Filter on item properties [see Filtering on Item Property]

A filter can either be given as a JSON object, or as a string compatible with URL query params formatted like '<PROPERTY_NAME>:<OP>' or '<PROPERTY_NAME>:<OP>:<VALUE>'. The field value is incompatible with notempty.

Inner fields:
- property_name (string) – Item-property name
- op (enum) – choices: [eq, lt, lte, gt, gte, in, notempty, neq, notin] Filter Operator
- value (any) – Filter Value
ratings (object-array) –
Optional. Ratings array

Inner fields:
- item_id (ID) – [see Flexible Identifiers] Item ID
- rating (float32) – [min: 1 max: 10] Rating value
user_properties (object) – Optional. User properties. Useful to solve the cold-start problem
exclude_rated_items (bool) – Optional. Exclude already rated items from response

EXAMPLE QUERY BODY¶

  {
      "ratings": [
          {"item_id": "123e4567-e89b-12d3-a456-426614174000", "rating": 8.5},
          {"item_id": "c3391d83-553b-40e7-818e-fcf658ec397d", "rating": 2.0}
      ],
      "user_properties": {
          "subscriptions": ["channel1", "channel2"],
          "age": 25
      },
      "amt": 10,
      "filters": [
          {"property_name": "price", "op": "lt", "value": 10},
          {"property_name": "genres", "op": "eq", "value": "drama"},
          {"property_name": "tags", "op": "in", "value": ["family", "fiction"]},
          {"property_name": "poster", "op": "notempty"},
      ],
      "exclude_rated_items": true
  }

Response JSON Object

items_id (ID-array) – Array of items IDs
next_cursor (string) – Pagination cursor to use in next request to get more items
warnings (list-of-string) – Optional. List of warnings

EXAMPLE RESPONSE¶

  {
      "items_id": [
          "c3391d83-553b-40e7-818e-fcf658ec397d",
          "c2a73584-bbd0-4f04-b497-26bf70152932"
      ],
      "next_cursor": "HLe-e1Sq..."
  }

Errors:

ServerUnavailable with error name DATABASE_NOT_READY if no ML model has been trained for this database
WrongData with error name WRONG_DATA_TYPE if any filter is invalid

Get Profile-Based Items Recommendations¶

GET recommendation/users/<str:user_id>/items/¶

Note

Authorized Roles: root, manager, backend, frontend

Get items recommendations given a user profile.

Query Parameters

amt (int) – Optional. [max: 64] Maximum amount of items returned
cursor (string) – Optional. Pagination cursor, typically from the next_cursor value of the previous response
filters (list-of-(string|object)) –
Optional. Filter on item properties [see Filtering on Item Property]

A filter can either be given as a JSON object, or as a string compatible with URL query params formatted like '<PROPERTY_NAME>:<OP>' or '<PROPERTY_NAME>:<OP>:<VALUE>'. The field value is incompatible with notempty.

Inner fields:
- property_name (string) – Item-property name
- op (enum) – choices: [eq, lt, lte, gt, gte, in, notempty, neq, notin] Filter Operator
- value (any) – Filter Value
exclude_rated_items (bool) – Optional. Exclude already rated items from response

EXAMPLE QUERY PARAMS¶

  ?amt=10&filters=price:lt:10&filters=genres:eq:drama&filters=tags:in:family,fiction&filters=poster:notempty&exclude_rated_items=true

Response JSON Object

items_id (ID-array) – Array of items IDs
next_cursor (string) – Pagination cursor to use in next request to get more items
warnings (list-of-string) – Optional. List of warnings

EXAMPLE RESPONSE¶

  {
      "items_id": [
          "c3391d83-553b-40e7-818e-fcf658ec397d",
          "c2a73584-bbd0-4f04-b497-26bf70152932"
      ],
      "next_cursor": "HLe-e1Sq..."
  }

Errors:

ServerUnavailable with error name DATABASE_NOT_READY if no ML model has trained for this database
NotFoundError with error name USER_NOT_FOUND if the user does not exist
WrongData with error name WRONG_DATA_TYPE if any filter is invalid