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 responsefilters (list-of-(string|object)) –
Optional. Filter on item properties [see Filtering on Item Property]
The field
value
is incompatible withnotempty
. 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 Operatorvalue (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 opweight (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 databaseNotFoundError with error name
ITEM_NOT_FOUND
if the item does not exist, with error nameITEM_PROPERTY_NOT_FOUND
if a filter property to filter on does not existWrongData with error name
WRONG_DATA_TYPE
if any filter is invalid, with error nameWRONG_OP_USE
if a filter operator is not used appropriately, with error nameWRONG_PARAMETER
if a parameter is not valid.NotFoundError with error name
SCENARIO_NOT_FOUND
if provided scenario does not existWrongData 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 asGET
. 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 responsefilters (list-of-(string|object)) –
Optional. Filter on item properties [see Filtering on Item Property]
The field
value
is incompatible withnotempty
. 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 Operatorvalue (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 opweight (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 databaseNotFoundError with error name
ITEM_PROPERTY_NOT_FOUND
if a filter property to filter on does not exist, with error nameUSER_PROPERTY_NOT_FOUND
if a user property does not exist.WrongData with error name
WRONG_DATA_TYPE
if any filter is invalid, with error nameWRONG_OP_USE
if a filter operator is not used appropriately, with error nameWRONG_PARAMETER
if a parameter is not valid.NotFoundError with error name
SCENARIO_NOT_FOUND
if provided scenario does not existWrongData 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 asGET
. 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 thefilters
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 withnotempty
. 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 Operatorvalue (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 databaseNotFoundError 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 responsefilters (list-of-(string|object)) –
Optional. Filter on item properties [see Filtering on Item Property]
The field
value
is incompatible withnotempty
. 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 Operatorvalue (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 opweight (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 databaseNotFoundError with error name
USER_NOT_FOUND
if the user does not exist, with error nameITEM_PROPERTY_NOT_FOUND
if a filter property to filter on does not existWrongData with error name
WRONG_DATA_TYPE
if any filter is invalid, with error nameWRONG_OP_USE
if a filter operator is not used appropriately, with error nameWRONG_PARAMETER
if a parameter is not valid. if the user does not exist, with error nameSCENARIO_NOT_FOUND
if provided scenario does not existWrongData 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 thefilters
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 withnotempty
. 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 Operatorvalue (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 databaseNotFoundError with error name
USER_NOT_FOUND
if the user does not exist, with error nameITEM_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 asGET
.- 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 responsefilters (list-of-(string|object)) –
Optional. Filter on item properties [see Filtering on Item Property]
The field
value
is incompatible withnotempty
. 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 Operatorvalue (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 opweight (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 databaseNotFoundError with error name
SCENARIO_NOT_FOUND
if provided scenario does not existWrongData 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 asGET
.- 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 responsefilters (list-of-(string|object)) –
Optional. Filter on item properties [see Filtering on Item Property]
The field
value
is incompatible withnotempty
. 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 Operatorvalue (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 opweight (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 databaseNotFoundError with error name
SCENARIO_NOT_FOUND
if provided scenario does not existWrongData 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 toITEM_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 endpointNotFoundError with error name
TABLE_NOT_FOUND
if the table name does not exist, with error nameITEM_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 toUSER_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 endpointNotFoundError with error name
TABLE_NOT_FOUND
if the table name does not exist, with error nameUSER_NOT_FOUND
if the user does not exist