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