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