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 (json-value) – 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 About Scenarios]
skip_default_scenario (bool) – Optional. Specify whether default scenario should by applied or skipped [see Default Scenario]
user_id (ID) – Optional. [see Flexible Identifiers] User ID. Only used in the context of an A/B test scenario to select the group A or B and keep track of the respective group in analytics. NOT used to personalize recommendations.

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

EXAMPLE QUERY PARAMS¶

  ?amt=10&scenario=scenario109&filters=price:lt:10

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, with error name ITEM_PROPERTY_NOT_FOUND if a filter property to filter on does not exist
WrongData with error name WRONG_DATA_TYPE if any filter is invalid, with error name WRONG_OP_USE if a filter operator is not used appropriately, with error name WRONG_PARAMETER if a parameter is not valid.
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 or interactions 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. Ratings and interactions are mutually exclusive

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 (json-value) – 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 About Scenarios]
skip_default_scenario (bool) – Optional. Specify whether default scenario should by applied or skipped [see Default Scenario]
ratings (object-array) –
Optional. Ratings array

Inner fields:
- item_id (ID) – [see Flexible Identifiers] Item ID
- rating (float32) – [min: 1 max: 10] Rating value
interactions (object-array) –
Optional. Interactions array

Inner fields:
- item_id (ID) – [see Flexible Identifiers] Item ID
- interaction_type (O) – Interaction Type
- timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp (default: now)
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.
user_id (ID) – Optional. [see Flexible Identifiers] User ID. Only used in the context of an A/B test scenario to select the group A or B and keep track of the respective group in analytics. NOT used to personalize recommendations.

EXAMPLE QUERY BODY WITH INTERACTIONS¶

  {
      "interactions": [
          {
              "item_id": "123e4567-e89b-12d3-a456-426614174000",
              "interaction_type": "like",
              "timestamp": 1632759339.123
          },
          {
              "item_id": "c3391d83-553b-40e7-818e-fcf658ec397d",
              "interaction_type": "dislike",
              "timestamp": 1632759339.123
          }
      ],
      "user_properties": {
          "age": 25
      },
      "amt": 10,
      "filters": [
          {"property_name": "tags", "op": "in", "value": ["family", "fiction"]},
          {"property_name": "poster", "op": "notempty"},
      ],
      "exclude_rated_items": true,
  }

EXAMPLE QUERY BODY WITH RATINGS¶

  {
      "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"],
      },
      "amt": 10,
      "filters": [
          {"property_name": "price", "op": "lt", "value": 10},
          {"property_name": "genres", "op": "eq", "value": "drama"},
      ],
      "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
NotFoundError with error name ITEM_PROPERTY_NOT_FOUND if a filter property to filter on does not exist, with error name USER_PROPERTY_NOT_FOUND if a user property does not exist.
WrongData with error name WRONG_DATA_TYPE if any filter is invalid, with error name WRONG_OP_USE if a filter operator is not used appropriately, with error name WRONG_PARAMETER if a parameter is not valid.
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 Recommendations of Item-Properties¶

POST recommendation/sessions/items-properties/<str:property_name>/¶

Note

Authorized Roles: root, manager, backend, frontend

Get item-property recommendations given the ratings or interactions of an anonymous session. Note that the HTTP verb is POST so that ratings or interactions can be sent in the body, but the endpoint is stateless as GET. Ratings and interactions are mutually exclusive.

Warning: while it may change in the future, current implementation uses an intermediate step selecting items. Consequently, using filters may have a strange behavior that you’re invited to check first, and the filters option may be removed in future versions of the API.

Request JSON Object

amt (int) – Optional. [max: 64] Maximum amount of item-properties returned
skip_default_scenario (bool) – Optional. Specify whether default scenario should by applied or skipped [see Default Scenario]
filters (list-of-(string|object)) –
Optional. Filter on item properties of the intermediate selected items [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 (json-value) – Filter Value
scenario (string) – Optional. Name of scenario [see About Scenarios]
ratings (object-array) –
Optional. Ratings array

Inner fields:
- item_id (ID) – [see Flexible Identifiers] Item ID
- rating (float32) – [min: 1 max: 10] Rating value
interactions (object-array) –
Optional. Interactions array

Inner fields:
- item_id (ID) – [see Flexible Identifiers] Item ID
- interaction_type (O) – Interaction Type
- timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp (default: now)
user_properties (object) – Optional. User properties. Useful to solve the cold-start problem
user_id (ID) – Optional. [see Flexible Identifiers] User ID. Only used in the context of an A/B test scenario to select the group A or B and keep track of the respective group in analytics. NOT used to personalize recommendations.

EXAMPLE QUERY BODY WITH INTERACTIONS¶

  {
      "interactions": [
          {
              "item_id": "123e4567-e89b-12d3-a456-426614174000",
              "interaction_type": "like",
              "timestamp": 1632759339.123
          },
          {
              "item_id": "c3391d83-553b-40e7-818e-fcf658ec397d",
              "interaction_type": "dislike",
              "timestamp": 1632759339.123
          }
      ],
      "user_properties": {
          "age": 25
      },
      "amt": 10,
      "filters": [
          {"property_name": "tags", "op": "in", "value": ["family", "fiction", "drama", "thriller", "comedy]},
          {"property_name": "poster", "op": "notempty"},
      ]
  }

Response JSON Object

properties (list-of-(string|int|float)) – Item properties. Values type uniquely depends on the property
warnings (list-of-string) – Optional. List of warnings

EXAMPLE RESPONSE¶

  {
      "properties": ["drama", "thriller", "comedy"],
      "warnings": []
  }

Errors:

ServerUnavailable with error name DATABASE_NOT_READY if no ML model has trained for this database
NotFoundError 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

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 (json-value) – 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 About Scenarios]
skip_default_scenario (bool) – Optional. Specify whether default scenario should by applied or skipped [see Default Scenario]
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 ITEM_PROPERTY_NOT_FOUND if a filter property to filter on does not exist
WrongData with error name WRONG_DATA_TYPE if any filter is invalid, with error name WRONG_OP_USE if a filter operator is not used appropriately, with error name WRONG_PARAMETER if a parameter is not valid. 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
skip_default_scenario (bool) – Optional. Specify whether default scenario should by applied or skipped [see Default Scenario]
filters (list-of-(string|object)) –
Optional. Filter on item properties of the intermediate selected items [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 (json-value) – Filter Value
scenario (string) – Optional. Name of scenario [see About Scenarios]

EXAMPLE QUERY PARAMS¶

  ?amt=10

Response JSON Object

properties (list-of-(string|int|float)) – Item properties. Values type uniquely depends on the property
warnings (list-of-string) – Optional. List of warnings

EXAMPLE RESPONSE¶

  {
      "properties": ["drama", "thriller", "comedy"],
      "warnings": ["the user had no ratings, used most-popular"]
  }

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

Get Profile-Based Items Recommendations with Context Items¶

POST recommendation/context-items/users/<str:user_id>/items/¶

Note

Authorized Roles: root, manager, backend, frontend

Get items recommendations given a user profile and a set of context items. Note that the HTTP verb is POST so that items ID 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 (json-value) – 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 About Scenarios]
skip_default_scenario (bool) – Optional. Specify whether default scenario should by applied or skipped [see Default Scenario]
context_items (object-array) –
Context items array

Inner fields:
- item_id (ID) – [see Flexible Identifiers] Item ID

EXAMPLE QUERY BODY¶

  {
      "context_items": [
          "123e4567-e89b-12d3-a456-426614174000",
          "c3391d83-553b-40e7-818e-fcf658ec397d",
          "sdf33000-0011-5fh3-235a-sldkjflsjdcc"
      ],
      "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
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 with Context Items¶

POST recommendation/context-items/sessions/items/¶

Note

Authorized Roles: root, manager, backend, frontend

Get items recommendations given the ratings of an anonymous session.and a set of context items. Note that the HTTP verb is POST so that the ratings and items ID 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 (json-value) – 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 About Scenarios]
skip_default_scenario (bool) – Optional. Specify whether default scenario should by applied or skipped [see Default Scenario]
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
context_items (object-array) –
Context items array

Inner fields:
- item_id (ID) – [see Flexible Identifiers] Item ID

EXAMPLE QUERY BODY¶

  {
      "context_items": [
          "123e4567-e89b-12d3-a456-426614174000",
          "c3391d83-553b-40e7-818e-fcf658ec397d",
          "sdf33000-0011-5fh3-235a-sldkjflsjdcc"
      ],
      "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
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 Precomputed Similar Items Recommendations¶

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

Note

Authorized Roles: root, manager, backend, frontend

Get precomputed similar items. The table must be with LOCAL connection, have no compressions and have resource equal to ITEM_TO_ITEMS_RECO. The table format must be indexed raw data file.

Query Parameters

table (string) – Optional. Table name to read recommendations
scenario (string) – Optional. Name of scenario [see About Scenarios]
skip_default_scenario (bool) – Optional. Specify whether default scenario should by applied or skipped [see Default Scenario]

EXAMPLE QUERY PARAMS¶

?scenario=scenario_name&skip_default_scenario=true

Response JSON Object

items_id (ID-array) – Array of items IDs

EXAMPLE RESPONSE¶

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

Errors:

WrongData with error name WRONG_DATA_TYPE if the table has wrong params or not compatible with this endpoint
NotFoundError with error name TABLE_NOT_FOUND if the table name does not exist, with error name ITEM_NOT_FOUND if the item does not exist, with error name SCENARIO_NOT_FOUND` if the scenario does not exist

Get Precomputed Profile-Based Items Recommendations¶

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

Note

Authorized Roles: root, manager, backend, frontend

Get item recommendations given a user profile, from a precomputed file. The table must be with LOCAL connection, have no compressions and have resource equal to USER_TO_ITEMS_RECO. The table format must be indexed raw data file.

Query Parameters

table (string) – Optional. Table name to read recommendations
scenario (string) – Optional. Name of scenario [see About Scenarios]
skip_default_scenario (bool) – Optional. Specify whether default scenario should by applied or skipped [see Default Scenario]

EXAMPLE QUERY PARAMS¶

?scenario=scenario_name&skip_default_scenario=true

Response JSON Object

items_id (ID-array) – Array of items IDs

EXAMPLE RESPONSE¶

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

Errors:

WrongData with error name WRONG_DATA_TYPE if the table has wrong params or not compatible with this endpoint
NotFoundError with error name TABLE_NOT_FOUND if the table name does not exist, with error name USER_NOT_FOUND if the user does not exist