Recommendation¶

Get Similar Items Recommendations¶

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

Note

Authorized Roles: root, manager, backend, frontend

Get similar items.

Query Parameters

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

Inner fields:
- property_name (string) – Item-property name
- op (enum) – choices: [eq, lt, lte, gt, gte, in, notempty, neq, notin, ftsearch] Filter Operator
- value (json-value) – Filter Value
reranking (list-of-object) –
Optional. Reranking business rules to apply [see Reranking on Item Property]

Inner fields:
- property_name (string) – Item-property name. Used for diversity reranking rules.
- op (enum) – choices: [diversity] Reranking op
- weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended
- options (object) – Op-specific options
  
  Inner fields:
  - activation_period (int) –
  - max_activation_count (int) –
  - default_malus (float) –
user_id (ID) – Optional. [see Flexible Identifiers], [max_length: 64] 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. Cannot be used together with a session_id.
session_id (ID) – Optional. [see Flexible Identifiers], [max_length: 64] Anonymous Session 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. Cannot be used together with a user_id.

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

warnings (list-of-string) – Optional. List of warnings
items_id (ID-array) – Array of items IDs
evaluated_scenarios (object) –
Optional.

Inner fields:
- runtime (list-of-object) – List of evaluated scenarios from runtime scenario [see About Scenarios]
  
  Inner fields:
  - scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario
  - scenario_name (string) – Name of scenario
  - to (string) – Characterization of next scenario evaluated
- default (list-of-object) – List of evaluated scenarios from default scenario [see About Scenarios]
  
  Inner fields:
  - scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario
  - scenario_name (string) – Name of scenario
  - to (string) – Characterization of next scenario evaluated
metadata (object) – Optional. [internal] WORK-IN-PROGRESS
next_cursor (string) – Optional. Pagination cursor to use in next request to get more items

EXAMPLE RESPONSE¶

  {
      "items_id": [
          "c3391d83-553b-40e7-818e-fcf658ec397d",
          "c2a73584-bbd0-4f04-b497-26bf70152932"
      ],
      "next_cursor": "HLe-e1Sq...",
      "evaluated_scenarios": {
          "runtime": [
              {"scenario_type": "alias", "scenario_name": "items_page", "to": "alias"}],
              {"scenario_type": "condition", "scenario_name": "is_item_popular", "to": "then"}],
              {"scenario_type": "ab_test", "scenario_name": "ab_test_on_item_categories", "to": "group_b"}],
              {"scenario_type": "case", "scenario_name": "only_thrillers"}
          ],
          "default": [
              {"scenario_type": "case", "scenario_name": "only_recent_movies"}
          ]
      }
  }

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 have properties that a business rule requires; and with error name ITEM_PROPERTY_NOT_FOUND if an item property required by a business rule 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 allowlisted 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.

This endpoint supports multiple ways to personalize the recommendations when no history of the user’s item interactions is available, for instance when the user ID itself is not available. The simplest use case is to use an anonymous session ID for which item interactions were previously created. Alternatively, this endpoint also supports sending the item interactions (or equivalently item ratings) directly in the request body.

Compared to the endpoint GET recommendation/users/<str:user_id>/items/, this endpoint is more optimized for capturing short term interactions.

In the special case with no interaction, this endpoint will approximately return the most popular items satisfying the business rules.

Request JSON Object

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]
cursor (string) – Optional. Pagination cursor, typically from the next_cursor value of the previous response
session_id (ID) – Optional. [see Flexible Identifiers], [max_length: 64] Anonymous Session ID. Recommendations will be personalized using the item interactions that were previously created for this anonymous session ID. Also used in the context of an A/B test scenario to select the group A or B and later keep track of the respective group in analytics. Mutually exclusive with providing ratings or user_id.
interactions (object-array) –
Optional. Item interactions array. Alternatively to personalizing the recommendations using a session_id, you can also provide item interactions directly in the body of the request. This is typically useful when the item interactions are stored in the local storage of the frontend instead of being created as they occur. When both interactions and session_id are used, the item interactions are combined for personalization. Mutually exclusive with providing ratings.

Inner fields:
- item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID
- interaction_type (O) – Interaction Type
- timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp (default: now)
ratings (object-array) –
Optional. Item ratings array. Rarely used. Similar to interactions but using ratings numbers instead of interactions types. Mutually exclusive with providing interactions or session_id.

Inner fields:
- item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID
- rating (float32) – [min: 1 max: 10] Rating value
user_properties (object) – Optional. User properties. Useful to solve the cold-start problem
user_id (ID) – Optional. [see Flexible Identifiers], [max_length: 64] User ID. Very rarely used, and NOT used to personalize recommendations. Mutually exclusive with providing session_id as a user is either logged-in or anonymous. Only used in the context of an A/B test scenario to select the group A or B and later keep track of the respective group in analytics, using a user_id instead of a session_id. Note that after an anonymous user is logging-in, using the user_id is preferred to the former anonymous session_id. However, typically when a user_id is available, it is more common to use the GET recommendation/users/<str:user_id>/items/ endpoint instead of this endpoint.
amt (int) – Optional. [min: 0 max: 64] Maximum amount of items returned
filters (list-of-object) –
Optional. Filter on item properties [see Filtering on Item Property]

Inner fields:
- property_name (string) – Item-property name
- op (enum) – choices: [eq, lt, lte, gt, gte, in, notempty, neq, notin, ftsearch] Filter Operator
- value (json-value) – Filter Value
reranking (list-of-object) –
Optional. Reranking business rules to apply [see Reranking on Item Property]

Inner fields:
- property_name (string) – Item-property name. Used for diversity reranking rules.
- op (enum) – choices: [diversity] Reranking op
- weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended
- options (object) – Op-specific options
  
  Inner fields:
  - activation_period (int) –
  - max_activation_count (int) –
  - default_malus (float) –
exclude_rated_items (bool) – Optional. Exclude already rated items from response

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

warnings (list-of-string) – Optional. List of warnings
items_id (ID-array) – Array of items IDs
evaluated_scenarios (object) –
Optional.

Inner fields:
- runtime (list-of-object) – List of evaluated scenarios from runtime scenario [see About Scenarios]
  
  Inner fields:
  - scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario
  - scenario_name (string) – Name of scenario
  - to (string) – Characterization of next scenario evaluated
- default (list-of-object) – List of evaluated scenarios from default scenario [see About Scenarios]
  
  Inner fields:
  - scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario
  - scenario_name (string) – Name of scenario
  - to (string) – Characterization of next scenario evaluated
metadata (object) – Optional. [internal] WORK-IN-PROGRESS
next_cursor (string) – Optional. Pagination cursor to use in next request to get more items

EXAMPLE RESPONSE¶

  {
      "items_id": [
          "c3391d83-553b-40e7-818e-fcf658ec397d",
          "c2a73584-bbd0-4f04-b497-26bf70152932"
      ],
      "next_cursor": "HLe-e1Sq...",
      "evaluated_scenarios": {
          "runtime": [
              {"scenario_type": "alias", "scenario_name": "home", "to": "alias"}],
              {"scenario_type": "ab_test", "scenario_name": "ab_test_on_model_type", "to": "group_a"}],
              {"scenario_type": "case", "scenario_name": "strongly_collaborative_filter"}
          ],
          "default": [
              {"scenario_type": "case", "scenario_name": "future_events_filter"}
          ]
      }
  }

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 allowlisted 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

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]
session_id (ID) – Optional. [see Flexible Identifiers], [max_length: 64] Anonymous Session ID. Recommendations will be personalized using the item interactions that were previously created for this anonymous session ID. Also used in the context of an A/B test scenario to select the group A or B and later keep track of the respective group in analytics. Mutually exclusive with providing ratings or user_id.
interactions (object-array) –
Optional. Item interactions array. Alternatively to personalizing the recommendations using a session_id, you can also provide item interactions directly in the body of the request. This is typically useful when the item interactions are stored in the local storage of the frontend instead of being created as they occur. When both interactions and session_id are used, the item interactions are combined for personalization. Mutually exclusive with providing ratings.

Inner fields:
- item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID
- interaction_type (O) – Interaction Type
- timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp (default: now)
ratings (object-array) –
Optional. Item ratings array. Rarely used. Similar to interactions but using ratings numbers instead of interactions types. Mutually exclusive with providing interactions or session_id.

Inner fields:
- item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID
- rating (float32) – [min: 1 max: 10] Rating value
user_properties (object) – Optional. User properties. Useful to solve the cold-start problem
user_id (ID) – Optional. [see Flexible Identifiers], [max_length: 64] User ID. Very rarely used, and NOT used to personalize recommendations. Mutually exclusive with providing session_id as a user is either logged-in or anonymous. Only used in the context of an A/B test scenario to select the group A or B and later keep track of the respective group in analytics, using a user_id instead of a session_id. Note that after an anonymous user is logging-in, using the user_id is preferred to the former anonymous session_id. However, typically when a user_id is available, it is more common to use the GET recommendation/users/<str:user_id>/items/ endpoint instead of this endpoint.
amt (int) – Optional. [min: 0 max: 64] Maximum amount of items returned
filters (list-of-object) –
Optional. Filter on item properties [see Filtering on Item Property]

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

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

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

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 allowlisted 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.

Compared to the endpoint POST recommendation/sessions/items/, this endpoint is more optimized for capturing long term interactions.

In the special case with no interaction, this endpoint will approximately return the most popular items satisfying the business rules.

Query Parameters

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

Inner fields:
- property_name (string) – Item-property name
- op (enum) – choices: [eq, lt, lte, gt, gte, in, notempty, neq, notin, ftsearch] Filter Operator
- value (json-value) – Filter Value
reranking (list-of-object) –
Optional. Reranking business rules to apply [see Reranking on Item Property]

Inner fields:
- property_name (string) – Item-property name. Used for diversity reranking rules.
- op (enum) – choices: [diversity] Reranking op
- weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended
- options (object) – Op-specific options
  
  Inner fields:
  - activation_period (int) –
  - max_activation_count (int) –
  - default_malus (float) –
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

EXAMPLE QUERY PARAMS¶

  ?amt=10&scenario=rule109&skip_default_scenario=true

Response JSON Object

warnings (list-of-string) – Optional. List of warnings
items_id (ID-array) – Array of items IDs
evaluated_scenarios (object) –
Optional.

Inner fields:
- runtime (list-of-object) – List of evaluated scenarios from runtime scenario [see About Scenarios]
  
  Inner fields:
  - scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario
  - scenario_name (string) – Name of scenario
  - to (string) – Characterization of next scenario evaluated
- default (list-of-object) – List of evaluated scenarios from default scenario [see About Scenarios]
  
  Inner fields:
  - scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario
  - scenario_name (string) – Name of scenario
  - to (string) – Characterization of next scenario evaluated
metadata (object) – Optional. [internal] WORK-IN-PROGRESS
next_cursor (string) – Optional. Pagination cursor to use in next request to get more items

EXAMPLE RESPONSE¶

  {
      "items_id": [
          "c3391d83-553b-40e7-818e-fcf658ec397d",
          "c2a73584-bbd0-4f04-b497-26bf70152932"
      ],
      "next_cursor": "HLe-e1Sq...",
      "evaluated_scenarios": {
          "runtime": [{"scenario_type": "case", "scenario_name": "year_filters"}],
          "default": [{"scenario_type": "case", "scenario_name": "favorite_scenario"}]
      }
  }

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 allowlisted 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

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]
amt (int) – Optional. [min: 0 max: 64] Maximum amount of items returned
filters (list-of-object) –
Optional. Filter on item properties [see Filtering on Item Property]

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

EXAMPLE QUERY PARAMS¶

  ?amt=10

Response JSON Object

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

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 allowlisted trained instance

Get Items Recommendations for Groups of Users¶

POST recommendation/users-groups/items/¶

Note

Authorized Roles: root, manager, backend

Get items recommendations given a group of users. Note that the HTTP verb is POST so that user ids can be sent in the body, but the endpoint is stateless as GET.

Request JSON Object

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]
cursor (string) – Optional. Pagination cursor, typically from the next_cursor value of the previous response
users (object-array) –
[min_length: 2] Users array

Inner fields:
- user_id (ID) – [see Flexible Identifiers], [max_length: 64] User ID
consensus_factor (float) – Optional. [min: 0 max: 1] Parameter controlling the consensus between the tastes of the users from the group. Float between 0 and 1 (defaults to 0.5); 0 for no consensus between the users (that is, find a mix from the top items of each individual), 1 for maximal consensus (that is, find the least-worst items among each individual).
amt (int) – Optional. [min: 0 max: 64] Maximum amount of items returned
filters (list-of-object) –
Optional. Filter on item properties [see Filtering on Item Property]

Inner fields:
- property_name (string) – Item-property name
- op (enum) – choices: [eq, lt, lte, gt, gte, in, notempty, neq, notin, ftsearch] Filter Operator
- value (json-value) – Filter Value
reranking (list-of-object) –
Optional. Reranking business rules to apply [see Reranking on Item Property]

Inner fields:
- property_name (string) – Item-property name. Used for diversity reranking rules.
- op (enum) – choices: [diversity] Reranking op
- weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended
- options (object) – Op-specific options
  
  Inner fields:
  - activation_period (int) –
  - max_activation_count (int) –
  - default_malus (float) –

EXAMPLE QUERY BODY¶

  {
      "users": [
          {
              "user_id": "123e4567-e89b-12d3-a456-426614174000"
          },
          {
              "user_id": "c3391d83-553b-40e7-818e-fcf658ec397d"
          },
          {
              "user_id": "e89b1d83-818e-40e7-12d3-174005e89b1d"
          }
      ],
      "consensus_factor": 0.7,
      "amt": 2,
      "filters": [
          {"property_name": "tags", "op": "in", "value": ["family", "fiction"]},
          {"property_name": "poster", "op": "notempty"}
      ]
  }

Response JSON Object

warnings (list-of-string) – Optional. List of warnings
items_id (ID-array) – Array of items IDs
evaluated_scenarios (object) –
Optional.

Inner fields:
- runtime (list-of-object) – List of evaluated scenarios from runtime scenario [see About Scenarios]
  
  Inner fields:
  - scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario
  - scenario_name (string) – Name of scenario
  - to (string) – Characterization of next scenario evaluated
- default (list-of-object) – List of evaluated scenarios from default scenario [see About Scenarios]
  
  Inner fields:
  - scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario
  - scenario_name (string) – Name of scenario
  - to (string) – Characterization of next scenario evaluated
metadata (object) – Optional. [internal] WORK-IN-PROGRESS
next_cursor (string) – Optional. Pagination cursor to use in next request to get more items

EXAMPLE RESPONSE¶

  {
      "items_id": [
          "c3391d83-553b-40e7-818e-fcf658ec397d",
          "c2a73584-bbd0-4f04-b497-26bf70152932"
      ],
      "next_cursor": "HLe-e1Sq...",
      "evaluated_scenarios": {
          "runtime": [{"scenario_type": "case", "scenario_name": "year_filters"}],
          "default": [{"scenario_type": "case", "scenario_name": "favorite_scenario"}]
      }
  }

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, 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 allowlisted 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

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]
cursor (string) – Optional. Pagination cursor, typically from the next_cursor value of the previous response
context_items (object-array) –
Context items array. Can be used to provide additional context like items in a cart.Contact our support for advanced usage.

Inner fields:
- item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID
amt (int) – Optional. [min: 0 max: 64] Maximum amount of items returned
filters (list-of-object) –
Optional. Filter on item properties [see Filtering on Item Property]

Inner fields:
- property_name (string) – Item-property name
- op (enum) – choices: [eq, lt, lte, gt, gte, in, notempty, neq, notin, ftsearch] Filter Operator
- value (json-value) – Filter Value
reranking (list-of-object) –
Optional. Reranking business rules to apply [see Reranking on Item Property]

Inner fields:
- property_name (string) – Item-property name. Used for diversity reranking rules.
- op (enum) – choices: [diversity] Reranking op
- weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended
- options (object) – Op-specific options
  
  Inner fields:
  - activation_period (int) –
  - max_activation_count (int) –
  - default_malus (float) –
exclude_rated_items (bool) – Optional. Exclude already rated items from response

EXAMPLE QUERY BODY¶

  {
      "context_items": [
          {"item_id": "123e4567-e89b-12d3-a456-426614174000"},
          {"item_id": "c3391d83-553b-40e7-818e-fcf658ec397d"},
          {"item_id": "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

warnings (list-of-string) – Optional. List of warnings
items_id (ID-array) – Array of items IDs
evaluated_scenarios (object) –
Optional.

Inner fields:
- runtime (list-of-object) – List of evaluated scenarios from runtime scenario [see About Scenarios]
  
  Inner fields:
  - scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario
  - scenario_name (string) – Name of scenario
  - to (string) – Characterization of next scenario evaluated
- default (list-of-object) – List of evaluated scenarios from default scenario [see About Scenarios]
  
  Inner fields:
  - scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario
  - scenario_name (string) – Name of scenario
  - to (string) – Characterization of next scenario evaluated
metadata (object) – Optional. [internal] WORK-IN-PROGRESS
next_cursor (string) – Optional. Pagination cursor to use in next request to get more items

EXAMPLE RESPONSE¶

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

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 allowlisted 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

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]
cursor (string) – Optional. Pagination cursor, typically from the next_cursor value of the previous response
session_id (ID) – Optional. [see Flexible Identifiers], [max_length: 64] Anonymous Session ID. Recommendations will be personalized using the item interactions that were previously created for this anonymous session ID. Also used in the context of an A/B test scenario to select the group A or B and later keep track of the respective group in analytics. Mutually exclusive with providing ratings or user_id.
interactions (object-array) –
Optional. Item interactions array. Alternatively to personalizing the recommendations using a session_id, you can also provide item interactions directly in the body of the request. This is typically useful when the item interactions are stored in the local storage of the frontend instead of being created as they occur. When both interactions and session_id are used, the item interactions are combined for personalization. Mutually exclusive with providing ratings.

Inner fields:
- item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID
- interaction_type (O) – Interaction Type
- timestamp (float64) – [min: -150000000000.0 (year -2786) max: 3500000000.0 (year 2080)] Interaction timestamp (default: now)
ratings (object-array) –
Optional. Item ratings array. Rarely used. Similar to interactions but using ratings numbers instead of interactions types. Mutually exclusive with providing interactions or session_id.

Inner fields:
- item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID
- rating (float32) – [min: 1 max: 10] Rating value
user_properties (object) – Optional. User properties. Useful to solve the cold-start problem
user_id (ID) – Optional. [see Flexible Identifiers], [max_length: 64] User ID. Very rarely used, and NOT used to personalize recommendations. Mutually exclusive with providing session_id as a user is either logged-in or anonymous. Only used in the context of an A/B test scenario to select the group A or B and later keep track of the respective group in analytics, using a user_id instead of a session_id. Note that after an anonymous user is logging-in, using the user_id is preferred to the former anonymous session_id. However, typically when a user_id is available, it is more common to use the GET recommendation/users/<str:user_id>/items/ endpoint instead of this endpoint.
context_items (object-array) –
Context items array. Can be used to provide additional context like items in a cart.Contact our support for advanced usage.

Inner fields:
- item_id (ID) – [see Flexible Identifiers], [max_length: 64] Item ID
amt (int) – Optional. [min: 0 max: 64] Maximum amount of items returned
filters (list-of-object) –
Optional. Filter on item properties [see Filtering on Item Property]

Inner fields:
- property_name (string) – Item-property name
- op (enum) – choices: [eq, lt, lte, gt, gte, in, notempty, neq, notin, ftsearch] Filter Operator
- value (json-value) – Filter Value
reranking (list-of-object) –
Optional. Reranking business rules to apply [see Reranking on Item Property]

Inner fields:
- property_name (string) – Item-property name. Used for diversity reranking rules.
- op (enum) – choices: [diversity] Reranking op
- weight (float) – Weight to apply to diversity reranking rules; must be positive; defaults to 1; values between 0 and 1.5 are recommended
- options (object) – Op-specific options
  
  Inner fields:
  - activation_period (int) –
  - max_activation_count (int) –
  - default_malus (float) –
exclude_rated_items (bool) – Optional. Exclude already rated items from response

EXAMPLE QUERY BODY¶

  {
      "context_items": [
          {"item_id": "123e4567-e89b-12d3-a456-426614174000"},
          {"item_id": "c3391d83-553b-40e7-818e-fcf658ec397d"},
          {"item_id": "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

warnings (list-of-string) – Optional. List of warnings
items_id (ID-array) – Array of items IDs
evaluated_scenarios (object) –
Optional.

Inner fields:
- runtime (list-of-object) – List of evaluated scenarios from runtime scenario [see About Scenarios]
  
  Inner fields:
  - scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario
  - scenario_name (string) – Name of scenario
  - to (string) – Characterization of next scenario evaluated
- default (list-of-object) – List of evaluated scenarios from default scenario [see About Scenarios]
  
  Inner fields:
  - scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario
  - scenario_name (string) – Name of scenario
  - to (string) – Characterization of next scenario evaluated
metadata (object) – Optional. [internal] WORK-IN-PROGRESS
next_cursor (string) – Optional. Pagination cursor to use in next request to get more items

EXAMPLE RESPONSE¶

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

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 allowlisted 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. When using precomputed recommendations, recommendations are computed and stored in advance. All filtering and other business rules are already applied, and this endpoint simply retrieves stored recommendations.

Precomputed recommendations typically allow for more customization of business rules and of the final recommendations, but are not updated frequently. If you need real-time features such as: - live filtering or live business rules; - new items handling (you cannot wait a day for new items to have personalized recommendations, and for new items to appear in recommendations; Then consider using the real-time endpoint.

Internal notes: When using a custom table, the table should 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

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]
table (string) – Optional. Table name to read recommendations. This is typically set inside the scenario,it is rare that customers should ever set it themselves
user_id (ID) – Optional. [see Flexible Identifiers], [max_length: 64] 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. Cannot be used together with a session_id.
session_id (ID) – Optional. [see Flexible Identifiers], [max_length: 64] Anonymous Session 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. Cannot be used together with a user_id.

EXAMPLE QUERY PARAMS¶

?scenario=scenario_name

Response JSON Object

warnings (list-of-string) – Optional. List of warnings
items_id (ID-array) – Array of items IDs
evaluated_scenarios (object) –
Optional.

Inner fields:
- runtime (list-of-object) – List of evaluated scenarios from runtime scenario [see About Scenarios]
  
  Inner fields:
  - scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario
  - scenario_name (string) – Name of scenario
  - to (string) – Characterization of next scenario evaluated
- default (list-of-object) – List of evaluated scenarios from default scenario [see About Scenarios]
  
  Inner fields:
  - scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario
  - scenario_name (string) – Name of scenario
  - to (string) – Characterization of next scenario evaluated
metadata (object) – Optional. [internal] WORK-IN-PROGRESS

EXAMPLE RESPONSE¶

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

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.

When using precomputed recommendations, recommendations are computed and stored in advance. All filtering and other business rules are already applied, and this endpoint simply retrieves stored recommendations.

The main use-case for precomputed recommendations based on a user profile is emailing and other campaigns. While precomputed recommendations allow for more customization of business rules and of the final recommendations, they are not updated frequently and we typically recommend using live recommendations for use on your website or on your app for best results.

Internal notes: When using a custom table, the table should 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

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]
table (string) – Optional. Table name to read recommendations. This is typically set inside the scenario,it is rare that customers should ever set it themselves
user_id (ID) – Optional. [see Flexible Identifiers], [max_length: 64] 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. Cannot be used together with a session_id.
session_id (ID) – Optional. [see Flexible Identifiers], [max_length: 64] Anonymous Session 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. Cannot be used together with a user_id.

EXAMPLE QUERY PARAMS¶

?scenario=scenario_name

Response JSON Object

warnings (list-of-string) – Optional. List of warnings
items_id (ID-array) – Array of items IDs
evaluated_scenarios (object) –
Optional.

Inner fields:
- runtime (list-of-object) – List of evaluated scenarios from runtime scenario [see About Scenarios]
  
  Inner fields:
  - scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario
  - scenario_name (string) – Name of scenario
  - to (string) – Characterization of next scenario evaluated
- default (list-of-object) – List of evaluated scenarios from default scenario [see About Scenarios]
  
  Inner fields:
  - scenario_type (enum) – choices: [case, ab_test, condition, alias] Type of scenario
  - scenario_name (string) – Name of scenario
  - to (string) – Characterization of next scenario evaluated
metadata (object) – Optional. [internal] WORK-IN-PROGRESS

EXAMPLE RESPONSE¶

  {
      "items_id": [
          "c3391d83-553b-40e7-818e-fcf658ec397d",
          "c2a73584-bbd0-4f04-b497-26bf70152932"
      ],
      "evaluated_scenarios": {
          "runtime": [
              {"scenario_type": "ab_test", "scenario_name": "my_ab_test"},
              {"scenario_type": "case", "scenario_name": "year_filters"}
          ]
      }
  }

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