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.

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.

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:

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:

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