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]

    The field value is incompatible with notempty. See Filter Syntax for the syntax.

    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

  • reranking (list-of-(string|object)) –

    Optional. Reranking business rules to apply [see Reranking on Item Property]

    See Reranking Syntax for the syntax

    Inner fields:

    • property_name (string) – Item-property name

    • op (enum) – choices: [diversity] Reranking op

    • weight (float) – Weight to apply to reranking; must be positive; defaults to 1; values between 0 and 1.5 are recommended

    • options (object) – Op-specific options

  • scenario (string) – Optional. Name of scenario to apply [see Scenarios]

  • skip_default_scenario (bool) – Optional. Specify whether default scenario should by applied or skipped [see Default Scenario]

  • algorithms (string) – Optional. [WORK IN PROGRESS] Algorithms whitelist, formatted as a single string of |-separated values

EXAMPLE QUERY PARAMS
?amt=10&filters=price:lt:10&reranking=genres:diversity:0.75::default_malus:0.25

or with a runtime-scenario and the default one, adding a filter and an algorithm

EXAMPLE QUERY PARAMS
  ?amt=10&scenario=scenario109&filters=price:lt:10&algorithms=algo1|algo2
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 SCENARIO_NOT_FOUND if provided scenario does not exist

  • WrongData with error name WRONG_DATA_TYPE if any business rule is invalid, or if there is no whitelisted trained instance

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]

    The field value is incompatible with notempty. See Filter Syntax for the syntax.

    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

  • reranking (list-of-(string|object)) –

    Optional. Reranking business rules to apply [see Reranking on Item Property]

    See Reranking Syntax for the syntax

    Inner fields:

    • property_name (string) – Item-property name

    • op (enum) – choices: [diversity] Reranking op

    • weight (float) – Weight to apply to reranking; must be positive; defaults to 1; values between 0 and 1.5 are recommended

    • options (object) – Op-specific options

  • scenario (string) – Optional. Name of scenario to apply [see Scenarios]

  • skip_default_scenario (bool) – Optional. Specify whether default scenario should by applied or skipped [see Default Scenario]

  • algorithms (string) – Optional. [WORK IN PROGRESS] Algorithms whitelist, formatted as a single string of |-separated values

  • 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. Defaults to false.

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,
      "algorithms": "my_algo_1|my_algo_2"
  }
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 SCENARIO_NOT_FOUND if provided scenario does not exist

  • WrongData with error name WRONG_DATA_TYPE if any business rule is invalid, or if there is no whitelisted trained instance

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]

    The field value is incompatible with notempty. See Filter Syntax for the syntax.

    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

  • reranking (list-of-(string|object)) –

    Optional. Reranking business rules to apply [see Reranking on Item Property]

    See Reranking Syntax for the syntax

    Inner fields:

    • property_name (string) – Item-property name

    • op (enum) – choices: [diversity] Reranking op

    • weight (float) – Weight to apply to reranking; must be positive; defaults to 1; values between 0 and 1.5 are recommended

    • options (object) – Op-specific options

  • scenario (string) – Optional. Name of scenario to apply [see Scenarios]

  • skip_default_scenario (bool) – Optional. Specify whether default scenario should by applied or skipped [see Default Scenario]

  • algorithms (string) – Optional. [WORK IN PROGRESS] Algorithms whitelist, formatted as a single string of |-separated values

  • exclude_rated_items (bool) – Optional. Exclude already rated items from response. Defaults to false.

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
EXAMPLE QUERY PARAMS
  ?amt=10&scenario=rule109&skip_default_scenario=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, with error name SCENARIO_NOT_FOUND if provided scenario does not exist

  • WrongData with error name WRONG_DATA_TYPE if any business rule is invalid, or if there is no whitelisted trained instance

Get Profile-Based Recommendations of Item-Properties

GET recommendation/users/<str:user_id>/items-properties/<str:property_name>/

Note

Authorized Roles: root, manager, backend, frontend

Get item-property recommendations given a user profile.

Query Parameters
  • amt (int) – Optional. [max: 64] Maximum amount of item-properties returned

  • algorithms (string) – Optional. [WORK IN PROGRESS] Algorithms whitelist, formatted as a single string of |-separated values

EXAMPLE QUERY PARAMS
  ?amt=10&algorithms=my_algo_1
Response JSON Object
  • properties (list-of-(string|int|float)) – Item properties. Values type uniquely depends on the property

EXAMPLE RESPONSE
  {
      "properties": ["drama", "thriller", "comedy"]
  }

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, with error name ITEM_PROPERTY_NOT_FOUND if the property name cannot be found.

  • WrongData with error name WRONG_DATA_TYPE if the property cannot be recommended, or if there is no whitelisted trained instance