The following methods allow you to maintain the set of items in the catalog. The items are specified using their ids, which are unique string identifiers matching ^[a-zA-Z0-9_-:@.]+$, i.e., they may consist of digits, Latin letters, underscores, colons, minus signs, at signs, and dots. Item ID undefined is forbidden.
put
Add Item
Adds new item of the given itemId to the items catalog.
All the item properties for the newly created items are set to null.
The itemId is already present in the item catalog. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.
delete
Delete Item
Deletes an item of the given itemId from the catalog.
If there are any purchases, ratings, bookmarks, cart additions, or detail views of the item present in the database, they will be deleted in cascade as well. Also, if the item is present in some series, it will be removed from all the series where present.
If an item becomes obsolete/no longer available, it is meaningful to keep it in the catalog (along with all the interaction data, which are very useful), and only exclude the item from recommendations. In such a case, use ReQL filter instead of deleting the item completely.
The itemId is not present in the item catalog. In many cases, you may consider this code a success – it only tells you that nothing has been deleted from the database since the item was already not present. If there is no additional info in the JSON response, you probably have an error in your URL.
get
List Items
Gets a list of IDs of items currently present in the catalog.
request := client.NewListItems()
// optional parameters:
.SetFilter(filter string)
.SetCount(count int)
.SetOffset(offset int)
.SetReturnProperties(returnProperties bool)
.SetIncludedProperties(includedProperties []string)
result, err := request.Send() // result is of the type []bindings.Item
Copy
GET /{databaseId}/items/list/?filter=<string>
&count=<integer>
&offset=<integer>
&returnProperties=<boolean>
&includedProperties=<array>
Calls Limit Per Minute
100
Parameters
databaseId
String
Located in: path
Required: Yes
ID of your database.
filter
String
Located in: query
Required: No
Boolean-returning ReQL expression, which allows you to filter items to be listed. Only the items for which the expression is true will be returned.
count
Integer
Located in: query
Required: No
The number of items to be listed.
offset
Integer
Located in: query
Required: No
Specifies the number of items to skip (ordered by itemId).
returnProperties
Boolean
Located in: query
Required: No
Since version: 1.4.0
With returnProperties=true, property values of the listed items are returned along with their IDs in a JSON dictionary.
Example response:
[{"itemId":"tv-178","description":"4K TV with 3D feature","categories":["Electronics","Televisions"],"price":342,"url":"myshop.com/tv-178"},{"itemId":"mixer-42","description":"Stainless Steel Mixer","categories":["Home & Kitchen"],"price":39,"url":"myshop.com/mixer-42"}]
includedProperties
Array
Located in: query
Required: No
Since version: 1.4.0
Allows specifying which properties should be returned when returnProperties=true is set. The properties are given as a comma-separated list.
Example response for includedProperties=description,price:
[{"itemId":"tv-178","description":"4K TV with 3D feature","price":342},{"itemId":"mixer-42","description":"Stainless Steel Mixer","price":39}]
Responses
200
Successful operation.
["item-1","item-2","item-3"]
404
If present, filter contains a non-existing item property.
delete
Delete More Items
Deletes all the items that pass the filter.
If an item becomes obsolete/no longer available, it is meaningful to keep it in the catalog (along with all the interaction data, which are very useful) and only exclude the item from recommendations. In such a case, use ReQL filter instead of deleting the item completely.
Item properties are used for modeling your domain. The following methods allow the definition of item properties. The properties may be thought of as columns in a relational database table.
put
Add Item Property
Adding an item property is somewhat equivalent to adding a column to the table of items. The items may be characterized by various properties of different types.
PUT /{databaseId}/items/properties/{propertyName}
Body (application/json):
{
"type" => <string>,
"role" => <string / Object>,
"metadata" => <array>
}
Parameters
databaseId
String
Located in: path
Required: Yes
ID of your database.
propertyName
String
Located in: path
Required: Yes
Name of the item property to be created. Currently, the following names are reserved: id, itemid, case-insensitively. Also, the length of the property name must not exceed 63 characters.
type
String
Located in: body
Required: Yes
Value type of the item property to be created. One of: int, double, string, boolean, timestamp, set, image or imageList.
int - Signed integer number.
double - Floating point number. It uses 64-bit base-2 format (IEEE 754 standard).
string - UTF-8 string.
boolean - true / false
timestamp - Value representing date and time. ISO8601-1 pattern (string) or UTC epoch time (number).
List of metadata entries to assign to the property.
Responses
201
Successful operation.
400
Property name does not match ^[a-zA-Z0-9_-:]+$, or it is a reserved keyword (''id'', ''itemid''), or its length exceeds 63 characters. Type information is missing, or the given type is invalid.
409
Property of the given name is already present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.
delete
Delete Item Property
Deleting an item property is roughly equivalent to removing a column from the table of items.
Property of the given name is not present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been deleted from the database since the item property was already not present. If there is no additional info in the JSON response, you probably have an error in your URL.
PropertyInfo result = client.Send(GetItemPropertyInfo(string propertyName));
Copy
Initialization
request := client.NewGetItemPropertyInfo(propertyName string)
result, err := request.Send() // result is of the type bindings.PropertyInfo
Copy
GET /{databaseId}/items/properties/{propertyName}
Parameters
databaseId
String
Located in: path
Required: Yes
ID of your database.
propertyName
String
Located in: path
Required: Yes
Name of the property about which the information is to be retrieved.
Responses
200
Successful operation.
{"name":"num-processors","type":"int"}
400
Property name does not match ^[a-zA-Z0-9_-:]+$.
404
Property of the given name is not present in the database. If there is no additional info in the JSON response, you probably have an error in your URL.
get
List Item Properties
Gets the list of all the item properties in your database.
The following methods allow assigning property values to items in the catalog. Set values are examined by content-based algorithms and used for recommendations, especially in the case of cold-start items that have no interactions yet. Properties are also used in ReQL for filtering and boosting according to your business rules.
post
Set Item Values
Sets/updates (some) property values of the given item. The properties (columns) must be previously created by Add item property.
{"product_description":"4K TV with 3D feature","categories":["Electronics","Televisions"],"price_usd":342,"in_stock_from":"2016-11-16T08:00Z","image":"http://myexamplesite.com/products/4ktelevision3d/image.jpg","other_images":["http://myexamplesite.com/products/4ktelevision3d/image2.jpg","http://myexamplesite.com/products/4ktelevision3d/image3.jpg"]}
Set item values can also cascade create the item if it's not already present in the database.
For this functionality:
When using the client libraries:
Set the optional cascadeCreate parameter to true, just like when creating an interaction.
When using directly REST API: Set special "property" !cascadeCreate.
Example:
{"product_description":"4K TV with 3D feature","!cascadeCreate":true}
Note the exclamation mark (!) at the beginning of the parameter's name to distinguish it from item property names.
Responses
200
Successful operation.
400
Property name does not match ''^[a-zA-Z0-9_-:]+$'', value does not match the property type.
404
Property of the given name is not present in the database. If there is no additional info in the JSON response, you probably have an error in your URL.
get
Get Item Values
Gets all the current property values of the given item.
UpdateMoreItemsResponse result = client.Send(UpdateMoreItems(string filter, Dictionary<string, object> changes));
Copy
Initialization
request := client.NewUpdateMoreItems(filter string, changes map[string]interface{})
result, err := request.Send() // result is of the type bindings.UpdateMoreItemsResponse
Copy
POST /{databaseId}/more-items/
Body (application/json):
{
"filter" => <string>,
"changes" => <Object>
}
Since version
3.3.0
Parameters
databaseId
String
Located in: path
Required: Yes
Since version: 3.3.0
ID of your database.
filter
String
Located in: body
Required: Yes
Since version: 3.3.0
A ReQL expression, which returns true for the items that shall be updated.
changes
Object
Located in: body
Required: Yes
Since version: 3.3.0
A dictionary where the keys are properties that shall be updated.
Responses
200
Successful operation. Returns IDs of updated items and their count.
User of the given userId is already present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.
delete
Delete User
Deletes a user of the given userId from the database.
If there are any purchases, ratings, bookmarks, cart additions or detail views made by the user present in the database, they will be deleted in cascade as well.
The userId does not match ''^[a-zA-Z0-9_-:@.]+$''.
404
User of the given userId is not present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been deleted from the database since the user was already not present. If there is no additional info in the JSON response, you probably have an error in your URL.
put
Merge Users
Allowed on Client-Side
Merges interactions (purchases, ratings, bookmarks, detail views ...) of two different users under a single user ID. This is especially useful for online e-commerce applications working with anonymous users identified by unique tokens such as the session ID. In such applications, it may often happen that a user owns a persistent account, yet accesses the system anonymously while, e.g., putting items into a shopping cart. At some point in time, such as when the user wishes to confirm the purchase, (s)he logs into the system using his/her username and password. The interactions made under anonymous session ID then become connected with the persistent account, and merging these two becomes desirable.
Merging happens between two users referred to as the target and the source. After the merge, all the interactions of the source user are attributed to the target user, and the source user is deleted.
By default, the Merge Users request is only available from server-side integrations for security reasons, to prevent potential abuse.
If you need to call this request from a client-side environment (such as a web or mobile app), please contact our support and request access to enable this feature for your database.
PUT /{databaseId}/users/{targetUserId}/merge/{sourceUserId}?cascadeCreate=<boolean>
Calls Limit Per Minute
100
Parameters
databaseId
String
Located in: path
Required: Yes
ID of your database.
targetUserId
String
Located in: path
Required: Yes
ID of the target user.
sourceUserId
String
Located in: path
Required: Yes
ID of the source user.
cascadeCreate
Boolean
Located in: query
Required: No
Sets whether the user targetUserId should be created if not present in the database.
Responses
201
Successful operation.
400
The sourceUserId or targetUserId does not match ^[a-zA-Z0-9_-:@.]+$
404
The sourceUserId or targetUserId does not exist in the database. If there is no additional info in the JSON response, you probably have an error in your URL.
get
List Users
Gets a list of IDs of users currently present in the catalog.
User properties are used for modeling users. The following methods allow the definition of user properties. The properties may be thought of as columns in a relational database table.
put
Add User Property
Adding a user property is somewhat equivalent to adding a column to the table of users. The users may be characterized by various properties of different types.
PUT /{databaseId}/users/properties/{propertyName}
Body (application/json):
{
"type" => <string>,
"role" => <string / Object>,
"metadata" => <array>
}
Since version
1.3.0
Parameters
databaseId
String
Located in: path
Required: Yes
Since version: 1.3.0
ID of your database.
propertyName
String
Located in: path
Required: Yes
Since version: 1.3.0
Name of the user property to be created. Currently, the following names are reserved: id, userid, case-insensitively. Also, the length of the property name must not exceed 63 characters.
type
String
Located in: body
Required: Yes
Value type of the user property to be created. One of: int, double, string, boolean, timestamp, set.
int - Signed integer number.
double - Floating point number. It uses 64-bit base-2 format (IEEE 754 standard).
string - UTF-8 string.
boolean - true / false
timestamp - Value representing date and time. ISO8601-1 pattern (string) or UTC epoch time (number).
List of metadata entries to assign to the property.
Responses
201
Successful operation.
400
Property name does not match ^[a-zA-Z0-9_-:]+$, or it is a reserved keyword (''id'', ''userid''), or its length exceeds 63 characters. Type information is missing, or the given type is invalid.
409
Property of the given name is already present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.
delete
Delete User Property
Deleting a user property is roughly equivalent to removing a column from the table of users.
Property of the given name is not present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been deleted from the database since the user property was already not present. If there is no additional info in the JSON response, you probably have an error in your URL.
PropertyInfo result = client.Send(GetUserPropertyInfo(string propertyName));
Copy
Initialization
request := client.NewGetUserPropertyInfo(propertyName string)
result, err := request.Send() // result is of the type bindings.PropertyInfo
Copy
GET /{databaseId}/users/properties/{propertyName}
Since version
1.3.0
Parameters
databaseId
String
Located in: path
Required: Yes
Since version: 1.3.0
ID of your database.
propertyName
String
Located in: path
Required: Yes
Since version: 1.3.0
Name of the property about which the information is to be retrieved.
Responses
200
Successful operation.
{"name":"country","type":"string"}
400
Property name does not match ^[a-zA-Z0-9_-:]+$.
404
Property of the given name is not present in the database. If there is no additional info in the JSON response, you probably have an error in your URL.
get
List User Properties
Gets the list of all the user properties in your database.
The following methods allow assigning property values to the user. Set values are examined by content-based algorithms and used in building recommendations, especially for users that have only a few interactions (e.g., new users). Useful properties may be, for example, gender or region. The values can be used in filtering using the context_user ReQL function.
post
Set User Values
Sets/updates (some) property values of the given user. The properties (columns) must be previously created by Add user property.
Set user values can also cascade create the user if it's not already present in the database.
For this functionality:
When using the client libraries:
Set the optional cascadeCreate parameter to true, just like when creating an interaction.
When using directly REST API: Set special "property" !cascadeCreate.
Example:
{"country":"US","!cascadeCreate":true}
Note the exclamation mark (!) at the beginning of the parameter's name to distinguish it from item property names.
Responses
200
Successful operation.
400
Property name does not match ''^[a-zA-Z0-9_-:]+$'', value does not agree to property type.
404
Property of the given name is not present in the database. If there is no additional info in the JSON response, you probably have an error in your URL.
get
Get User Values
Gets all the current property values of the given user.
UTC timestamp of the view as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
duration
Integer
Located in: body
Required: No
Duration of the view
cascadeCreate
Boolean
Located in: body
Required: No
Sets whether the given user/item should be created if not present in the database.
recommId
String
Located in: body
Required: No
Since version: 2.2.0
If this detail view is based on a recommendation request, recommId is the id of the clicked recommendation.
additionalData
Object
Located in: body
Required: No
Since version: 2.3.0
Additional data associated with the interaction. The expected structure is defined for specific use cases and will be provided by the Recombee Support team when applicable.
autoPresented
Boolean
Located in: body
Required: No
Since version: 6.0.0
Indicates whether the item was automatically presented to the user (e.g., in a swiping feed) or explicitly requested by the user (e.g., by clicking on a link). Defaults to false.
Responses
200
Successful operation.
400
Given userId or itemId does not match ^[a-zA-Z0-9_-:@.]+$. timestamp or duration is not a real number ≥ 0.
404
The cascadeCreate is not set true and the userId or the itemId were found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.
409
A detail view of the exact same userId, itemId, and timestamp is already present in the database. Note that a user may view an item's details multiple times, yet triplets (userId, itemId, timestamp) must be unique. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.
delete
Delete Detail View
Deletes an existing detail view uniquely specified by (userId, itemId, and timestamp) or all the detail views with the given userId and itemId if timestamp is omitted.
Unix timestamp of the detail view. If the timestamp is omitted, then all the detail views with the given userId and itemId are deleted.
Responses
200
Successful operation.
400
Given userId or itemId does not match ^[a-zA-Z0-9_-:@.]+$, or timestamp is not a real number ≥ 0.
404
The userId, itemId, or detail view with the given (userId, itemId, timestamp) not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.
get
List Item Detail Views
Lists all the detail views of the given item ever made by different users.
UTC timestamp of the purchase as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
cascadeCreate
Boolean
Located in: body
Required: No
Sets whether the given user/item should be created if not present in the database.
amount
Number
Located in: body
Required: No
Since version: 1.6.0
Amount (number) of purchased items. The default is 1. For example, if user-x purchases two item-y during a single order (session...), the amount should equal 2.
price
Number
Located in: body
Required: No
Since version: 1.6.0
Price paid by the user for the item. If amount is greater than 1, the sum of prices of all the items should be given.
profit
Number
Located in: body
Required: No
Since version: 1.6.0
Your profit from the purchased item. The profit is natural in the e-commerce domain (for example, if user-x purchases item-y for $100 and the gross margin is 30 %, then the profit is $30) but is also applicable in other domains (for example, at a news company it may be income from a displayed advertisement on article page). If amount is greater than 1, the sum of profit of all the items should be given.
recommId
String
Located in: body
Required: No
Since version: 2.2.0
If this purchase is based on a recommendation request, recommId is the id of the clicked recommendation.
additionalData
Object
Located in: body
Required: No
Since version: 2.3.0
Additional data associated with the interaction. The expected structure is defined for specific use cases and will be provided by the Recombee Support team when applicable.
Responses
200
Successful operation.
400
The userId or itemId does not match ^[a-zA-Z0-9_-:@.]+$. timestamp is not a real number ≥ 0.
404
The cascadeCreate is not set true and the userId or the itemId were found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.
409
A purchase of the exact same userId, itemId, and timestamp is already present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.
delete
Delete Purchase
Deletes an existing purchase uniquely specified by userId, itemId, and timestamp or all the purchases with the given userId and itemId if timestamp is omitted.
Unix timestamp of the purchase. If the timestamp is omitted, then all the purchases with the given userId and itemId are deleted.
Responses
200
Successful operation.
400
Given userId or itemId does not match ^[a-zA-Z0-9_-:@.]+$, or timestamp is not a real number ≥ 0.
404
The userId, itemId, or purchase with the given (userId, itemId, timestamp) not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.
get
List Item Purchases
Lists all the ever-made purchases of the given item.
UTC timestamp of the rating as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
rating
Number
Located in: body
Required: Yes
Rating rescaled to interval [-1.0,1.0], where -1.0 means the worst rating possible, 0.0 means neutral, and 1.0 means absolutely positive rating. For example, in the case of 5-star evaluations, rating = (numStars-3)/2 formula may be used for the conversion.
cascadeCreate
Boolean
Located in: body
Required: No
Sets whether the given user/item should be created if not present in the database.
recommId
String
Located in: body
Required: No
Since version: 2.2.0
If this rating is based on a recommendation request, recommId is the id of the clicked recommendation.
additionalData
Object
Located in: body
Required: No
Since version: 2.3.0
Additional data associated with the interaction. The expected structure is defined for specific use cases and will be provided by the Recombee Support team when applicable.
Responses
200
Successful operation.
400
The userId or itemId does not match ^[a-zA-Z0-9_-:@.]+$, or rating is not a real number from [-1.0,1.0], or timestamp is not a real number ≥ 0.
404
The cascadeCreate is not set true and the userId or the itemId were found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.
409
A rating of the exact same userId, itemId, and timestamp is already present in the database. Note that a user may rate an item multiple times, yet triplets (userId, itemId, timestamp) must be unique. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.
delete
Delete Rating
Deletes an existing rating specified by (userId, itemId, timestamp) from the database or all the ratings with the given userId and itemId if timestamp is omitted.
Unix timestamp of the rating. If the timestamp is omitted, then all the ratings with the given userId and itemId are deleted.
Responses
200
Successful operation.
400
Given userId or itemId does not match ^[a-zA-Z0-9_-:@.]+$, or timestamp is not a real number ≥ 0.
404
The userId, itemId or rating with the given (userId, itemId, timestamp) not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.
get
List Item Ratings
Lists all the ratings of an item ever submitted by different users.
UTC timestamp of the cart addition as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
cascadeCreate
Boolean
Located in: body
Required: No
Sets whether the given user/item should be created if not present in the database.
amount
Number
Located in: body
Required: No
Since version: 1.6.0
Amount (number) added to cart. The default is 1. For example, if user-x adds two item-y during a single order (session...), the amount should equal 2.
price
Number
Located in: body
Required: No
Since version: 1.6.0
Price of the added item. If amount is greater than 1, the sum of prices of all the items should be given.
recommId
String
Located in: body
Required: No
Since version: 2.2.0
If this cart addition is based on a recommendation request, recommId is the id of the clicked recommendation.
additionalData
Object
Located in: body
Required: No
Since version: 2.3.0
Additional data associated with the interaction. The expected structure is defined for specific use cases and will be provided by the Recombee Support team when applicable.
Responses
200
Successful operation.
400
The userId or itemId does not match ^[a-zA-Z0-9_-:@.]+$, timestamp is not a real number ≥ 0.
404
The cascadeCreate is not set true and the userId or the itemId were found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.
409
A cart addition of the exact same userId, itemId, and timestamp is already present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.
delete
Delete Cart Addition
Deletes an existing cart addition uniquely specified by userId, itemId, and timestamp or all the cart additions with the given userId and itemId if timestamp is omitted.
Unix timestamp of the cart addition. If the timestamp is omitted, then all the cart additions with the given userId and itemId are deleted.
Responses
200
Successful operation.
400
Given userId or itemId does not match ^[a-zA-Z0-9_-:@.]+$, or timestamp is not a real number ≥ 0.
404
The userId, itemId, or cart addition with the given (userId, itemId, timestamp) not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.
get
List Item Cart Additions
Lists all the ever-made cart additions of the given item.
UTC timestamp of the bookmark as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
cascadeCreate
Boolean
Located in: body
Required: No
Sets whether the given user/item should be created if not present in the database.
recommId
String
Located in: body
Required: No
Since version: 2.2.0
If this bookmark is based on a recommendation request, recommId is the id of the clicked recommendation.
additionalData
Object
Located in: body
Required: No
Since version: 2.3.0
Additional data associated with the interaction. The expected structure is defined for specific use cases and will be provided by the Recombee Support team when applicable.
Responses
200
Successful operation.
400
The userId or itemId does not match ^[a-zA-Z0-9_-:@.]+$, timestamp is not a real number ≥ 0.
404
The cascadeCreate is not set true and the userId or the itemId were found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.
409
A bookmark of the exact same userId, itemId, and timestamp is already present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.
delete
Delete Bookmark
Deletes a bookmark uniquely specified by userId, itemId, and timestamp or all the bookmarks with the given userId and itemId if timestamp is omitted.
Unix timestamp of the bookmark. If the timestamp is omitted, then all the bookmarks with the given userId and itemId are deleted.
Responses
200
Successful operation.
400
Given userId or itemId does not match ^[a-zA-Z0-9_-:@.]+$, or timestamp is not a real number ≥ 0.
404
The userId, itemId, or bookmark with the given (userId, itemId, timestamp) not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.
get
List Item Bookmarks
Lists all the ever-made bookmarks of the given item.
Given userId not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.
View Portions
post
Set View Portion
Allowed on Client-Side
Sets viewed portion of an item (for example a video or article) by a user (at a session).
If you send a new request with the same (userId, itemId, sessionId), the portion gets updated.
Viewed portion of the item (number between 0.0 (viewed nothing) and 1.0 (viewed full item) ). It should be the actual viewed part of the item, no matter the seeking. For example, if the user seeked immediately to half of the item and then viewed 10% of the item, the portion should still be 0.1.
sessionId
String
Located in: body
Required: No
Since version: 2.1.0
ID of the session in which the user viewed the item. Default is null (None, nil, NULL etc., depending on the language).
timestamp
String
Number
Located in: body
Required: No
Since version: 2.1.0
UTC timestamp of the view portion as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
cascadeCreate
Boolean
Located in: body
Required: No
Since version: 2.1.0
Sets whether the given user/item should be created if not present in the database.
recommId
String
Located in: body
Required: No
Since version: 2.2.0
If this view portion is based on a recommendation request, recommId is the id of the clicked recommendation.
additionalData
Object
Located in: body
Required: No
Since version: 2.3.0
Additional data associated with the interaction. The expected structure is defined for specific use cases and will be provided by the Recombee Support team when applicable.
autoPresented
Boolean
Located in: body
Required: No
Since version: 6.0.0
Indicates whether the item was automatically presented to the user (e.g., in a swiping feed) or explicitly requested by the user (e.g., by clicking on a link). Defaults to false.
timeSpent
Number
Located in: body
Required: No
Since version: 6.0.0
The duration (in seconds) that the user viewed the item. In update requests, this value may only increase and is required only if it has changed.
Responses
200
Successful operation.
400
The userId, itemId or sessionId does not match ^[a-zA-Z0-9_-:@.]+$, or the portion is not a real number from [0.0,1.0].
404
The cascadeCreate is not set true and the userId or the itemId were found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.
409
A view portion of the exact same userId, itemId, and a greater or equal timestamp (or a greater portion) is already present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.
delete
Delete View Portion
Deletes an existing view portion specified by (userId, itemId, sessionId) from the database.
Given userId, itemId or sessionId does not match ^[a-zA-Z0-9_-:@.]+$.
404
The userId, itemId or view portion with the given (userId, itemId, sessionId) not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.
get
List Item View Portions
Lists all the view portions of an item ever submitted by different users.
Given userId not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.
Recommendations
Recommendation methods are capable of recommending items (Recommend Items to User, Recommend Items to Item) or users (Recommend Users to Item, Recommend Users to User).
See Segmentations section for recommendation endpoints that return Segments (e.g. "recommend categories to a user").
Recommending Items
Recommendation endpoints that return the Items (content, products, etc.).
get
Recommend Items to User
Allowed on Client-Side
Based on the user's past interactions (purchases, ratings, etc.) with the items, recommends top-N items that are most likely to be of high value for the given user.
The most typical use cases are recommendations on the homepage, in some "Picked just for you" section, or in email.
The returned items are sorted by relevance (the first item being the most relevant).
Besides the recommended items, also a unique recommId is returned in the response. It can be used to:
Let Recombee know that this recommendation was successful (e.g., user clicked one of the recommended items). See Reported metrics.
Get subsequent recommended items when the user scrolls down (infinite scroll) or goes to the next page. See Recommend Next Items.
It is also possible to use POST HTTP method (for example in the case of a very long ReQL filter) - query parameters then become body parameters.
ID of the user for whom personalized recommendations are to be generated.
count
Integer
Located in: query
Required: Yes
Since version: 2.0.0
Number of items to be recommended (N for the top-N recommendation).
scenario
String
Located in: query
Required: No
Since version: 2.0.0
Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".
You can set various settings to the scenario in the Admin UI. You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs.
The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.
cascadeCreate
Boolean
Located in: query
Required: No
Since version: 2.0.0
If the user does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows, for example, rotations in the following recommendations for that user, as the user will be already known to the system.
returnProperties
Boolean
Located in: query
Required: No
Since version: 2.0.0
With returnProperties=true, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used to easily display the recommended items to the user.
Example response:
{"recommId":"ce52ada4-e4d9-4885-943c-407db2dee837","recomms":[{"id":"tv-178","values":{"description":"4K TV with 3D feature","categories":["Electronics","Televisions"],"price":342,"url":"myshop.com/tv-178"}},{"id":"mixer-42","values":{"description":"Stainless Steel Mixer","categories":["Home & Kitchen"],"price":39,"url":"myshop.com/mixer-42"}}],"numberNextRecommsCalls":0}
includedProperties
Array
Located in: query
Required: No
Since version: 2.0.0
Allows specifying which properties should be returned when returnProperties=true is set. The properties are given as a comma-separated list.
Example response for includedProperties=description,price:
{"recommId":"a86ee8d5-cd8e-46d1-886c-8b3771d0520b","recomms":[{"id":"tv-178","values":{"description":"4K TV with 3D feature","price":342}},{"id":"mixer-42","values":{"description":"Stainless Steel Mixer","price":39}}],"numberNextRecommsCalls":0}
filter
String
Located in: query
Required: No
Since version: 2.0.0
Boolean-returning ReQL expression, which allows you to filter recommended items based on the values of their attributes.
Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case.
See this section for a list of available logics and other details.
The difference between logic and scenario is that logic specifies mainly behavior, while scenario specifies the place where recommendations are shown to the users.
A dictionary of ReQL expressions that will be executed for each recommended item.
This can be used to compute additional properties of the recommended items that are not stored in the database.
The keys are the names of the expressions, and the values are the actual ReQL expressions.
Example request:
{"reqlExpressions":{"isInUsersCity":"context_user[\"city\"] in 'cities'","distanceToUser":"earth_distance('location', context_user[\"location\"])"}}
Expert option: Specifies the threshold of how relevant must the recommended items be to the user. Possible values one of: "low", "medium", "high". The default value is "low", meaning that the system attempts to recommend a number of items equal to count at any cost. If there is not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations to be appended to reach the full count. This behavior may be suppressed by using "medium" or "high" values. In such a case, the system only recommends items of at least the requested relevance and may return less than count items when there is not enough data to fulfill it.
rotationRate
Number
Located in: query
Required: No
Since version: 2.0.0
Expert option: If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Recombee API allows you to control this per request in a backward fashion. You may penalize an item for being recommended in the near past. For the specific user, rotationRate=1 means maximal rotation, rotationRate=0 means absolutely no rotation. You may also use, for example, rotationRate=0.2 for only slight rotation of recommended items. Default: 0.
rotationTime
Number
Located in: query
Required: No
Since version: 2.0.0
Expert option: Taking rotationRate into account, specifies how long it takes for an item to recover from the penalization. For example, rotationTime=7200.0 means that items recommended less than 2 hours ago are penalized. Default: 7200.0.
userId does not match ^[a-zA-Z0-9_-:@.]+$, count is not a positive integer, filter or booster is not valid ReQL expressions, filter expression does not return boolean, booster does not return double or integer.
404
userId not found in the database and cascadeCreate is false. If there is no additional info in the JSON response, you probably have an error in your URL.
get
Recommend Items to Item
Allowed on Client-Side
Recommends a set of items that are somehow related to one given item, X. A typical scenario is when the user A is viewing X. Then you may display items to the user that he might also be interested in. Recommend items to item request gives you Top-N such items, optionally taking the target user A into account.
The returned items are sorted by relevance (the first item being the most relevant).
Besides the recommended items, also a unique recommId is returned in the response. It can be used to:
Let Recombee know that this recommendation was successful (e.g., user clicked one of the recommended items). See Reported metrics.
Get subsequent recommended items when the user scrolls down (infinite scroll) or goes to the next page. See Recommend Next Items.
It is also possible to use POST HTTP method (for example in the case of a very long ReQL filter) - query parameters then become body parameters.
ID of the item for which the recommendations are to be generated.
targetUserId
String
Located in: query
Required: Yes
Since version: 2.0.0
ID of the user who will see the recommendations.
Specifying the targetUserId is beneficial because:
It makes the recommendations personalized
Allows the calculation of Actions and Conversions
in the graphical user interface,
as Recombee can pair the user who got recommendations
and who afterward viewed/purchased an item.
If you insist on not specifying the user, pass null
(None, nil, NULL etc., depending on the language) to targetUserId.
Do not create some special dummy user for getting recommendations,
as it could mislead the recommendation models,
and result in wrong recommendations.
For anonymous/unregistered users, it is possible to use, for example, their session ID.
count
Integer
Located in: query
Required: Yes
Since version: 2.0.0
Number of items to be recommended (N for the top-N recommendation).
scenario
String
Located in: query
Required: No
Since version: 2.0.0
Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".
You can set various settings to the scenario in the Admin UI. You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs.
The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.
cascadeCreate
Boolean
Located in: query
Required: No
Since version: 2.0.0
If an item of the given itemId or user of the given targetUserId doesn't exist in the database, it creates the missing entity/entities and returns some (non-personalized) recommendations. This allows, for example, rotations in the following recommendations for the user of the given targetUserId, as the user will be already known to the system.
returnProperties
Boolean
Located in: query
Required: No
Since version: 2.0.0
With returnProperties=true, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used to easily display the recommended items to the user.
Example response:
{"recommId":"0c6189e7-dc1a-429a-b613-192696309361","recomms":[{"id":"tv-178","values":{"description":"4K TV with 3D feature","categories":["Electronics","Televisions"],"price":342,"url":"myshop.com/tv-178"}},{"id":"mixer-42","values":{"description":"Stainless Steel Mixer","categories":["Home & Kitchen"],"price":39,"url":"myshop.com/mixer-42"}}],"numberNextRecommsCalls":0}
includedProperties
Array
Located in: query
Required: No
Since version: 2.0.0
Allows specifying which properties should be returned when returnProperties=true is set. The properties are given as a comma-separated list.
Example response for includedProperties=description,price:
{"recommId":"6842c725-a79f-4537-a02c-f34d668a3f80","recomms":[{"id":"tv-178","values":{"description":"4K TV with 3D feature","price":342}},{"id":"mixer-42","values":{"description":"Stainless Steel Mixer","price":39}}],"numberNextRecommsCalls":0}
filter
String
Located in: query
Required: No
Since version: 2.0.0
Boolean-returning ReQL expression, which allows you to filter recommended items based on the values of their attributes.
Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case.
See this section for a list of available logics and other details.
The difference between logic and scenario is that logic specifies mainly behavior, while scenario specifies the place where recommendations are shown to the users.
A dictionary of ReQL expressions that will be executed for each recommended item.
This can be used to compute additional properties of the recommended items that are not stored in the database.
The keys are the names of the expressions, and the values are the actual ReQL expressions.
Example request:
{"reqlExpressions":{"isInUsersCity":"context_user[\"city\"] in 'cities'","distanceToUser":"earth_distance('location', context_user[\"location\"])","isFromSameCompany":"'company' == context_item[\"company\"]"}}
Expert option: If the targetUserId is provided: Specifies the threshold of how relevant must the recommended items be to the user. Possible values one of: "low", "medium", "high". The default value is "low", meaning that the system attempts to recommend a number of items equal to count at any cost. If there is not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations being appended to reach the full count. This behavior may be suppressed by using "medium" or "high" values. In such case, the system only recommends items of at least the requested relevance and may return less than count items when there is not enough data to fulfill it.
rotationRate
Number
Located in: query
Required: No
Since version: 2.0.0
Expert option: If the targetUserId is provided: If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Recombee API allows you to control this per request in a backward fashion. You may penalize an item for being recommended in the near past. For the specific user, rotationRate=1 means maximal rotation, rotationRate=0 means absolutely no rotation. You may also use, for example, rotationRate=0.2 for only slight rotation of recommended items.
rotationTime
Number
Located in: query
Required: No
Since version: 2.0.0
Expert option: If the targetUserId is provided: Taking rotationRate into account, specifies how long it takes for an item to recover from the penalization. For example, rotationTime=7200.0 means that items recommended less than 2 hours ago are penalized.
itemId does not match ^[a-zA-Z0-9_-:@.]+$, count is not a positive integer, filter or booster is not valid ReQL expressions, filter expression does not return boolean, booster does not return double or integer.
404
itemId not found in the database and cascadeCreate is false. If there is no additional info in the JSON response, you probably have an error in your URL.
get
Recommend Items to Item Segment
Allowed on Client-Side
Recommends Items that are the most relevant to a particular Segment from a context Segmentation.
Based on the used Segmentation, this endpoint can be used for example for:
Recommending articles related to a particular topic
Recommending songs belonging to a particular genre
Recommending products produced by a particular brand
You need to set the used context Segmentation in the Admin UI in the Scenario settings prior to using this endpoint.
The returned items are sorted by relevance (the first item being the most relevant).
It is also possible to use the POST HTTP method (for example, in the case of a very long ReQL filter) — query parameters then become body parameters.
ID of the segment from contextSegmentationId for which the recommendations are to be generated.
targetUserId
String
Located in: query
Required: Yes
Since version: 5.0.0
ID of the user who will see the recommendations.
Specifying the targetUserId is beneficial because:
It makes the recommendations personalized
Allows the calculation of Actions and Conversions
in the graphical user interface,
as Recombee can pair the user who got recommendations
and who afterward viewed/purchased an item.
If you insist on not specifying the user, pass null
(None, nil, NULL etc., depending on the language) to targetUserId.
Do not create some special dummy user for getting recommendations,
as it could mislead the recommendation models,
and result in wrong recommendations.
For anonymous/unregistered users, it is possible to use, for example, their session ID.
count
Integer
Located in: query
Required: Yes
Since version: 5.0.0
Number of items to be recommended (N for the top-N recommendation).
scenario
String
Located in: query
Required: No
Since version: 5.0.0
Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".
You can set various settings to the scenario in the Admin UI. You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs.
The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.
cascadeCreate
Boolean
Located in: query
Required: No
Since version: 5.0.0
If a user of the given targetUserId doesn't exist in the database, it creates this user and returns some (non-personalized) recommendations. This allows, for example, rotations in the following recommendations for the user of the given targetUserId, as the user will be already known to the system.
returnProperties
Boolean
Located in: query
Required: No
Since version: 5.0.0
With returnProperties=true, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used to easily display the recommended items to the user.
Example response:
{"recommId":"0c6189e7-dc1a-429a-b613-192696309361","recomms":[{"id":"tv-178","values":{"description":"4K TV with 3D feature","categories":["Electronics","Televisions"],"price":342,"url":"myshop.com/tv-178"}},{"id":"mixer-42","values":{"description":"Stainless Steel Mixer","categories":["Home & Kitchen"],"price":39,"url":"myshop.com/mixer-42"}}],"numberNextRecommsCalls":0}
includedProperties
Array
Located in: query
Required: No
Since version: 5.0.0
Allows specifying which properties should be returned when returnProperties=true is set. The properties are given as a comma-separated list.
Example response for includedProperties=description,price:
{"recommId":"6842c725-a79f-4537-a02c-f34d668a3f80","recomms":[{"id":"tv-178","values":{"description":"4K TV with 3D feature","price":342}},{"id":"mixer-42","values":{"description":"Stainless Steel Mixer","price":39}}],"numberNextRecommsCalls":0}
filter
String
Located in: query
Required: No
Since version: 5.0.0
Boolean-returning ReQL expression, which allows you to filter recommended items based on the values of their attributes.
Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case.
See this section for a list of available logics and other details.
The difference between logic and scenario is that logic specifies mainly behavior, while scenario specifies the place where recommendations are shown to the users.
A dictionary of ReQL expressions that will be executed for each recommended item.
This can be used to compute additional properties of the recommended items that are not stored in the database.
The keys are the names of the expressions, and the values are the actual ReQL expressions.
Example request:
{"reqlExpressions":{"isInUsersCity":"context_user[\"city\"] in 'cities'","distanceToUser":"earth_distance('location', context_user[\"location\"])"}}
Expert option: If the targetUserId is provided: Specifies the threshold of how relevant must the recommended items be to the user. Possible values one of: "low", "medium", "high". The default value is "low", meaning that the system attempts to recommend a number of items equal to count at any cost. If there is not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations being appended to reach the full count. This behavior may be suppressed by using "medium" or "high" values. In such case, the system only recommends items of at least the requested relevance and may return less than count items when there is not enough data to fulfill it.
rotationRate
Number
Located in: query
Required: No
Since version: 5.0.0
Expert option: If the targetUserId is provided: If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Recombee API allows you to control this per request in a backward fashion. You may penalize an item for being recommended in the near past. For the specific user, rotationRate=1 means maximal rotation, rotationRate=0 means absolutely no rotation. You may also use, for example, rotationRate=0.2 for only slight rotation of recommended items.
rotationTime
Number
Located in: query
Required: No
Since version: 5.0.0
Expert option: If the targetUserId is provided: Taking rotationRate into account, specifies how long it takes for an item to recover from the penalization. For example, rotationTime=7200.0 means that items recommended less than 2 hours ago are penalized.
contextSegmentId not found in the context segmentation
get
Recommend Next Items
Allowed on Client-Side
Returns items that shall be shown to a user as next recommendations when the user e.g. scrolls the page down (infinite scroll) or goes to the next page.
It accepts recommId of a base recommendation request (e.g., request from the first page) and the number of items that shall be returned (count).
The base request can be one of:
All the other parameters are inherited from the base request.
Recommend next items can be called many times for a single recommId and each call returns different (previously not recommended) items.
The number of Recommend next items calls performed so far is returned in the numberNextRecommsCalls field.
Recommend next items can be requested up to 30 minutes after the base request or a previous Recommend next items call.
For billing purposes, each call to Recommend next items is counted as a separate recommendation request.
RecommendationResponse result = client.Send(RecommendNextItems(string recommId, long count));
Copy
Initialization
request := client.NewRecommendNextItems(recommId string, count int)
result, err := request.Send() // result is of the type bindings.RecommendationResponse
Copy
GET /{databaseId}/recomms/next/items/{recommId}?count=<integer>
Since version
3.1.0
Parameters
databaseId
String
Located in: path
Required: Yes
Since version: 3.1.0
ID of your database.
recommId
String
Located in: path
Required: Yes
Since version: 3.1.0
ID of the base recommendation request for which next recommendations should be returned
request := client.NewRecommendItemSegmentsToUser(userId string, count int)
// optional parameters:
.SetScenario(scenario string)
.SetCascadeCreate(cascadeCreate bool)
.SetFilter(filter string)
.SetBooster(booster string)
.SetLogic(logic bindings.Logic)
.SetReqlExpressions(reqlExpressions map[string]string)
result, err := request.Send() // result is of the type bindings.RecommendationResponse
Copy
GET /{databaseId}/recomms/users/{userId}/item-segments/?count=<integer>
&scenario=<string>
&cascadeCreate=<boolean>
&filter=<string>
&booster=<string>
&logic=<string / Object>
&reqlExpressions=<Object>
Since version
4.1.0
Parameters
databaseId
String
Located in: path
Required: Yes
Since version: 4.1.0
ID of your database.
userId
String
Located in: path
Required: Yes
Since version: 4.1.0
ID of the user for whom personalized recommendations are to be generated.
count
Integer
Located in: query
Required: Yes
Since version: 4.1.0
Number of item segments to be recommended (N for the top-N recommendation).
scenario
String
Located in: query
Required: No
Since version: 4.1.0
Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".
You can set various settings to the scenario in the Admin UI. You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs.
The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.
cascadeCreate
Boolean
Located in: query
Required: No
Since version: 4.1.0
If the user does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows, for example, rotations in the following recommendations for that user, as the user will be already known to the system.
filter
String
Located in: query
Required: No
Since version: 4.1.0
Boolean-returning ReQL expression which allows you to filter recommended segments based on the segmentationId.
booster
String
Located in: query
Required: No
Since version: 4.1.0
Number-returning ReQL expression which allows you to boost recommendation rate of some segments based on the segmentationId.
logic
String
Object
Located in: query
Required: No
Since version: 4.1.0
Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case.
See this section for a list of available logics and other details.
The difference between logic and scenario is that logic specifies mainly behavior, while scenario specifies the place where recommendations are shown to the users.
A dictionary of ReQL expressions that will be executed for each recommended Item Segment.
This can be used to compute additional properties of the recommended Item Segments.
The keys are the names of the expressions, and the values are the actual ReQL expressions.
ID of the item for which the recommendations are to be generated.
targetUserId
String
Located in: query
Required: Yes
Since version: 4.1.0
ID of the user who will see the recommendations.
Specifying the targetUserId is beneficial because:
It makes the recommendations personalized
Allows the calculation of Actions and Conversions
in the graphical user interface,
as Recombee can pair the user who got recommendations
and who afterward viewed/purchased an item.
If you insist on not specifying the user, pass null
(None, nil, NULL etc., depending on the language) to targetUserId.
Do not create some special dummy user for getting recommendations,
as it could mislead the recommendation models,
and result in wrong recommendations.
For anonymous/unregistered users, it is possible to use, for example, their session ID.
count
Integer
Located in: query
Required: Yes
Since version: 4.1.0
Number of item segments to be recommended (N for the top-N recommendation).
scenario
String
Located in: query
Required: No
Since version: 4.1.0
Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".
You can set various settings to the scenario in the Admin UI. You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs.
The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.
cascadeCreate
Boolean
Located in: query
Required: No
Since version: 4.1.0
If the user does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows, for example, rotations in the following recommendations for that user, as the user will be already known to the system.
filter
String
Located in: query
Required: No
Since version: 4.1.0
Boolean-returning ReQL expression which allows you to filter recommended segments based on the segmentationId.
booster
String
Located in: query
Required: No
Since version: 4.1.0
Number-returning ReQL expression which allows you to boost recommendation rate of some segments based on the segmentationId.
logic
String
Object
Located in: query
Required: No
Since version: 4.1.0
Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case.
See this section for a list of available logics and other details.
The difference between logic and scenario is that logic specifies mainly behavior, while scenario specifies the place where recommendations are shown to the users.
A dictionary of ReQL expressions that will be executed for each recommended Item Segment.
This can be used to compute additional properties of the recommended Item Segments.
The keys are the names of the expressions, and the values are the actual ReQL expressions.
ID of the segment from contextSegmentationId for which the recommendations are to be generated.
targetUserId
String
Located in: query
Required: Yes
Since version: 4.1.0
ID of the user who will see the recommendations.
Specifying the targetUserId is beneficial because:
It makes the recommendations personalized
Allows the calculation of Actions and Conversions
in the graphical user interface,
as Recombee can pair the user who got recommendations
and who afterward viewed/purchased an item.
If you insist on not specifying the user, pass null
(None, nil, NULL etc., depending on the language) to targetUserId.
Do not create some special dummy user for getting recommendations,
as it could mislead the recommendation models,
and result in wrong recommendations.
For anonymous/unregistered users, it is possible to use, for example, their session ID.
count
Integer
Located in: query
Required: Yes
Since version: 4.1.0
Number of item segments to be recommended (N for the top-N recommendation).
scenario
String
Located in: query
Required: No
Since version: 4.1.0
Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".
You can set various settings to the scenario in the Admin UI. You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs.
The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.
cascadeCreate
Boolean
Located in: query
Required: No
Since version: 4.1.0
If the user does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows, for example, rotations in the following recommendations for that user, as the user will be already known to the system.
filter
String
Located in: query
Required: No
Since version: 4.1.0
Boolean-returning ReQL expression which allows you to filter recommended segments based on the segmentationId.
booster
String
Located in: query
Required: No
Since version: 4.1.0
Number-returning ReQL expression which allows you to boost recommendation rate of some segments based on the segmentationId.
logic
String
Object
Located in: query
Required: No
Since version: 4.1.0
Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case.
See this section for a list of available logics and other details.
The difference between logic and scenario is that logic specifies mainly behavior, while scenario specifies the place where recommendations are shown to the users.
A dictionary of ReQL expressions that will be executed for each recommended Item Segment.
This can be used to compute additional properties of the recommended Item Segments.
The keys are the names of the expressions, and the values are the actual ReQL expressions.
contextSegmentId not found in the context segmentation
get
Recommend Next Item Segments
Allowed on Client-Side
Returns Item Segments to be shown as the next recommendations when a user scrolls (e.g., within a carousel or feed of Item Segments such as brands, artists, topics, or categories).
The request requires the recommId of a base recommendation request and the number of Segments to return (count).
All other parameters are inherited from the base request associated with the provided recommId.
This endpoint can be called multiple times for a single recommId. Each call returns different Item Segments that have not been recommended in previous calls.
The number of calls made so far is returned in the numberNextRecommsCalls field.
Requests can be made up to 30 minutes after the base request or the most recent Recommend Next Item Segments call.
For billing purposes, each call to this endpoint is counted as a separate recommendation request.
RecommendationResponse result = client.Send(RecommendNextItemSegments(string recommId, long count));
Copy
Initialization
request := client.NewRecommendNextItemSegments(recommId string, count int)
result, err := request.Send() // result is of the type bindings.RecommendationResponse
Copy
GET /{databaseId}/recomms/next/item-segments/{recommId}?count=<integer>
Since version
6.2.0
Parameters
databaseId
String
Located in: path
Required: Yes
Since version: 6.2.0
ID of your database.
recommId
String
Located in: path
Required: Yes
Since version: 6.2.0
ID of the base recommendation request for which next recommendations should be returned
Number of users to be recommended (N for the top-N recommendation).
scenario
String
Located in: query
Required: No
Since version: 2.0.0
Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".
You can set various settings to the scenario in the Admin UI. You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs.
The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.
cascadeCreate
Boolean
Located in: query
Required: No
Since version: 2.0.0
If the user does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows, for example, rotations in the following recommendations for that user, as the user will be already known to the system.
returnProperties
Boolean
Located in: query
Required: No
Since version: 2.0.0
With returnProperties=true, property values of the recommended users are returned along with their IDs in a JSON dictionary. The acquired property values can be used to easily display the recommended users.
Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case.
See this section for a list of available logics and other details.
The difference between logic and scenario is that logic specifies mainly behavior, while scenario specifies the place where recommendations are shown to the users.
A dictionary of ReQL expressions that will be executed for each recommended user.
This can be used to compute additional properties of the recommended users that are not stored in the database.
The keys are the names of the expressions, and the values are the actual ReQL expressions.
Example request:
{"reqlExpressions":{"isInUsersCity":"context_user[\"city\"] in 'cities'","distanceToUser":"earth_distance('location', context_user[\"location\"])"}}
Expert option: If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Recombee API allows you to control this per request in a backward fashion. You may penalize a user for being recommended in the near past. For the specific user, rotationRate=1 means maximal rotation, rotationRate=0 means absolutely no rotation. You may also use, for example, rotationRate=0.2 for only slight rotation of recommended users.
rotationTime
Number
Located in: query
Required: No
Since version: 5.0.0
Expert option: Taking rotationRate into account, specifies how long it takes for a user to recover from the penalization. For example, rotationTime=7200.0 means that users recommended less than 2 hours ago are penalized.
userId does not match ^[a-zA-Z0-9_-:@.]+$, count is not a positive integer, filter or booster is not valid ReQL expressions, filter expression does not return boolean, booster does not return double or integer.
404
userId not found in the database and cascadeCreate is false. If there is no additional info in the JSON response, you probably have an error in your URL.
get
Recommend Users to Item
Recommends users that are likely to be interested in the given item.
It is also possible to use POST HTTP method (for example in the case of a very long ReQL filter) - query parameters then become body parameters.
The returned users are sorted by predicted interest in the item (the first user being the most interested).
ID of the item for which the recommendations are to be generated.
count
Integer
Located in: query
Required: Yes
Since version: 2.0.0
Number of users to be recommended (N for the top-N recommendation).
scenario
String
Located in: query
Required: No
Since version: 2.0.0
Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".
You can set various settings to the scenario in the Admin UI. You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs.
The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.
cascadeCreate
Boolean
Located in: query
Required: No
Since version: 2.0.0
If an item of the given itemId doesn't exist in the database, it creates the missing item.
returnProperties
Boolean
Located in: query
Required: No
Since version: 2.0.0
With returnProperties=true, property values of the recommended users are returned along with their IDs in a JSON dictionary. The acquired property values can be used to easily display the recommended users.
Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case.
See this section for a list of available logics and other details.
The difference between logic and scenario is that logic specifies mainly behavior, while scenario specifies the place where recommendations are shown to the users.
A dictionary of ReQL expressions that will be executed for each recommended user.
This can be used to compute additional properties of the recommended users that are not stored in the database.
The keys are the names of the expressions, and the values are the actual ReQL expressions.
Example request:
{"reqlExpressions":{"isInUsersCity":"context_user[\"city\"] in 'cities'","distanceToUser":"earth_distance('location', context_user[\"location\"])","isFromSameCompany":"'company' == context_item[\"company\"]"}}
itemId does not match ^[a-zA-Z0-9_-:@.]+$, count is not a positive integer, filter or booster is not valid ReQL expressions, filter expression does not return boolean, booster does not return double or integer.
404
itemId not found in the database and cascadeCreate is false. If there is no additional info in the JSON response, you probably have an error in your URL.
Composite Recommendations
Composite Recommendations return a source entity (e.g., an Item, or Item Segment) and a list of related recommendations in a single response, enabling multi-layered, highly personalized suggestions, such as Because You Watched … in streaming services or Top Products from Your Favorite Brand … in e-commerce.
post
Composite Recommendation
Allowed on Client-Side
Composite Recommendation returns both a source entity (e.g., an Item or Item Segment) and a list of related recommendations in a single response.
It is ideal for use cases such as personalized homepage sections (Articles from <category>), Because You Watched <movie>, or Artists Related to Your Favorite Artist <artist>.
Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".
You can set various settings to the scenario in the Admin UI. You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs.
The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.
count
Integer
Located in: body
Required: Yes
Since version: 6.0.0
Number of items to be recommended (N for the top-N recommendation).
itemId
String
Located in: body
Required: No
Since version: 6.0.0
ID of the item for which the recommendations are to be generated.
userId
String
Located in: body
Required: No
Since version: 6.0.0
ID of the user for which the recommendations are to be generated.
logic
String
Object
Located in: body
Required: No
Since version: 6.0.0
Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case.
See this section for a list of available logics and other details.
The difference between logic and scenario is that logic specifies mainly behavior, while scenario specifies the place where recommendations are shown to the users.
ID of the segment from contextSegmentationId for which the recommendations are to be generated.
searchQuery
String
Located in: body
Required: No
Since version: 6.2.0
Search query provided by the user. It is used for the full-text search. Only applicable if the scenario corresponds to a search scenario.
cascadeCreate
Boolean
Located in: body
Required: No
Since version: 6.0.0
If the entity for the source recommendation does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows, for example, rotations in the following recommendations for that entity, as the entity will be already known to the system.
sourceSettings
Object
Located in: body
Required: No
Since version: 6.0.0
Parameters applied for recommending the Source stage. The accepted parameters correspond with the recommendation sub-endpoint used to recommend the Source.
resultSettings
Object
Located in: body
Required: No
Since version: 6.0.0
Parameters applied for recommending the Result stage. The accepted parameters correspond with the recommendation sub-endpoint used to recommend the Result.
Count is not a positive integer, provided scenario not found.
404
contextSegmentId not found in the context segmentation, userId not found in the database and cascadeCreate is false, itemId not found in the database and cascadeCreate is false.
Examples
Example Category Sections With Reordering
Suppose you want to recommend three category sections on the homepage, but in a personalized order for each user.
For example, in a news domain, one user might see Politics–Culture–Technology, while another might get Sport–Technology–Politics.
You can achieve this by calling three Composite Recommendations within a single Batch request — retrieving both the personalized categories and the recommended items within each.
The Batch ensures that three distinct categories are returned in the results.
This example shows how to use parameters on both stages:
In sourceSettings, we enable rotation so the source changes over time for the same user.
In resultSettings, we filter out promotions and return basic properties for rendering.
Example response (truncated) with returnProperties=true on results:
{"recommId":"7b8d0f5e-42a4-4a71-b2b7-25f9c0cc0e9a","source":{"id":"article-389"},"recomms":[{"id":"article-1024","values":{"title":"5 Books That Will Change How You Think","url":"newsportal.com/a/1024"}},{"id":"article-2031","values":{"title":"The Psychology of Habit Formation","url":"newsportal.com/a/2031"}}],"numberNextRecommsCalls":0}
Full-text personalized search. The results are based on the full-text matching of a search query and the preferences of a particular user.
get
Search Items
Allowed on Client-Side
Full-text personalized search. The results are based on the provided searchQuery and also on the user's past interactions (purchases, ratings, etc.) with the items (items more suitable for the user are preferred in the results).
All the string and set item properties are indexed by the search engine.
This endpoint should be used in a search box on your website/app. It can be called multiple times as the user is typing the query in order to get the most viable suggestions based on the current state of the query, or once after submitting the whole query.
The returned items are sorted by relevance (the first item being the most relevant).
Besides the recommended items, also a unique recommId is returned in the response. It can be used to:
Let Recombee know that this search was successful (e.g., user clicked one of the recommended items). See Reported metrics.
Get subsequent search results when the user scrolls down or goes to the next page. See Recommend Next Items.
It is also possible to use POST HTTP method (for example in the case of a very long ReQL filter) - query parameters then become body parameters.
ID of the user for whom personalized search will be performed.
searchQuery
String
Located in: query
Required: Yes
Since version: 3.0.0
Search query provided by the user. It is used for the full-text search.
count
Integer
Located in: query
Required: Yes
Since version: 3.0.0
Number of items to be returned (N for the top-N results).
scenario
String
Located in: query
Required: No
Since version: 3.0.0
Scenario defines a particular search field in your user interface.
You can set various settings to the scenario in the Admin UI. You can also see the performance of each scenario in the Admin UI separately, so you can check how well each field performs.
The AI that optimizes models to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios.
cascadeCreate
Boolean
Located in: query
Required: No
Since version: 3.0.0
If the user does not exist in the database, returns a list of non-personalized search results and creates the user in the database. This allows, for example, rotations in the following recommendations for that user, as the user will be already known to the system.
returnProperties
Boolean
Located in: query
Required: No
Since version: 3.0.0
With returnProperties=true, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used to easily display the recommended items to the user.
Example response:
{"recommId":"ce52ada4-e4d9-4885-943c-407db2dee837","recomms":[{"id":"tv-178","values":{"description":"4K TV with 3D feature","categories":["Electronics","Televisions"],"price":342,"url":"myshop.com/tv-178"}},{"id":"mixer-42","values":{"description":"Stainless Steel Mixer","categories":["Home & Kitchen"],"price":39,"url":"myshop.com/mixer-42"}}],"numberNextRecommsCalls":0}
includedProperties
Array
Located in: query
Required: No
Since version: 3.0.0
Allows specifying which properties should be returned when returnProperties=true is set. The properties are given as a comma-separated list.
Example response for includedProperties=description,price:
{"recommId":"a86ee8d5-cd8e-46d1-886c-8b3771d0520b","recomms":[{"id":"tv-178","values":{"description":"4K TV with 3D feature","price":342}},{"id":"mixer-42","values":{"description":"Stainless Steel Mixer","price":39}}],"numberNextRecommsCalls":0}
filter
String
Located in: query
Required: No
Since version: 2.0.0
Boolean-returning ReQL expression, which allows you to filter recommended items based on the values of their attributes.
Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case.
See this section for a list of available logics and other details.
The difference between logic and scenario is that logic specifies mainly behavior, while scenario specifies the place where recommendations are shown to the users.
A dictionary of ReQL expressions that will be executed for each recommended item.
This can be used to compute additional properties of the recommended items that are not stored in the database.
The keys are the names of the expressions, and the values are the actual ReQL expressions.
Example request:
{"reqlExpressions":{"isInUsersCity":"context_user[\"city\"] in 'cities'","distanceToUser":"earth_distance('location', context_user[\"location\"])"}}
userId does not match ^[a-zA-Z0-9_-:@.]+$, count is not a positive integer, searchQuery is not provided, filter or booster are not valid ReQL expressions, filter expression does not return boolean, booster does not return double or integer.
404
userId not found in the database and cascadeCreate is false. If there is no additional info in the JSON response, you probably have an error in you URL.
get
Search Item Segments
Allowed on Client-Side
Full-text personalized search that returns Segments from a Segmentation. The results are based on the provided searchQuery and also on the user's past interactions (purchases, ratings, etc.).
Based on the used Segmentation, this endpoint can be used for example for:
Searching within categories or brands
Searching within genres or artists
For example if the user is searching for "iPhone" this endpoint can return "cell phones" category.
You need to set the used Segmentation the Admin UI in the Scenario settings prior to using this endpoint.
The returned segments are sorted by relevance (first segment being the most relevant).
It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.
ID of the user for whom personalized search will be performed.
searchQuery
String
Located in: query
Required: Yes
Since version: 4.1.0
Search query provided by the user. It is used for the full-text search.
count
Integer
Located in: query
Required: Yes
Since version: 4.1.0
Number of segments to be returned (N for the top-N results).
scenario
String
Located in: query
Required: No
Since version: 4.1.0
Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".
You can set various settings to the scenario in the Admin UI. You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs.
The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.
cascadeCreate
Boolean
Located in: query
Required: No
Since version: 4.1.0
If the user does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows, for example, rotations in the following recommendations for that user, as the user will be already known to the system.
filter
String
Located in: query
Required: No
Since version: 4.1.0
Boolean-returning ReQL expression which allows you to filter recommended segments based on the segmentationId.
booster
String
Located in: query
Required: No
Since version: 4.1.0
Number-returning ReQL expression which allows you to boost recommendation rate of some segments based on the segmentationId.
logic
String
Object
Located in: query
Required: No
Since version: 4.1.0
Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case.
See this section for a list of available logics and other details.
The difference between logic and scenario is that logic specifies mainly behavior, while scenario specifies the place where recommendations are shown to the users.
A dictionary of ReQL expressions that will be executed for each recommended Item Segment.
This can be used to compute additional properties of the recommended Item Segments.
The keys are the names of the expressions, and the values are the actual ReQL expressions.
userId does not match ^[a-zA-Z0-9_-:@.]+$, count is not a positive integer, searchQuery is not provided, filter or booster is not valid ReQL expressions, filter expression does not return boolean, booster does not return double or integer.
404
userId not found in the database and cascadeCreate is false. If there is no additional info in the JSON response, you probably have an error in your URL.
Synonyms
Define that some words or phrases should be considered equal by the full-text search engine.
When the term is used in the search query, the synonym is also used for the full-text search.
Unless oneWay=true, it works also in the opposite way (synonym -> term).
An example of a synonym can be science fiction for the term sci-fi.
request := client.NewAddSearchSynonym(term string, synonym string)
// optional parameters:
.SetOneWay(oneWay bool)
result, err := request.Send() // result is of the type bindings.SearchSynonym
Copy
POST /{databaseId}/synonyms/items/
Body (application/json):
{
"term" => <string>,
"synonym" => <string>,
"oneWay" => <boolean>
}
Since version
3.2.0
Calls Limit Per Minute
1000
Parameters
databaseId
String
Located in: path
Required: Yes
Since version: 3.2.0
ID of your database.
term
String
Located in: body
Required: Yes
Since version: 3.2.0
A word to which the synonym is specified.
synonym
String
Located in: body
Required: Yes
Since version: 3.2.0
A word that should be considered equal to the term by the full-text search engine.
oneWay
Boolean
Located in: body
Required: No
Since version: 3.2.0
If set to true, only term -> synonym is considered. If set to false, also synonym -> term works.
Default: false.
Responses
201
Successful operation. Returns data about the added synonym (including id).
synonym and term pair already exists in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.
get
List Search Synonyms
Gives the list of synonyms defined in the database.
request := client.NewListSearchSynonyms()
// optional parameters:
.SetCount(count int)
.SetOffset(offset int)
result, err := request.Send() // result is of the type bindings.ListSearchSynonymsResponse
Copy
GET /{databaseId}/synonyms/items/?count=<integer>
&offset=<integer>
Calls Limit Per Minute
60
Parameters
databaseId
String
Located in: path
Required: Yes
ID of your database.
count
Integer
Located in: query
Required: No
The number of synonyms to be listed.
offset
Integer
Located in: query
Required: No
Specifies the number of synonyms to skip (ordered by term).
Items in the catalog may be organized into series, expressing an explicit, known ordering of items, if there is any. Typical examples of series may be consecutive TV show episodes, book titles, etc.
Each item may be added to zero or more series, and a series may also be added into another series, resulting in a "meta-series". This may be useful for modeling ordered seasons of a TV show that has the episodes in each season themselves ordered.
Series definition
Methods for managing series - creating, listing, and deleting them.
PUT /{databaseId}/series/{seriesId}
Body (application/json):
{
"cascadeCreate" => <boolean>
}
Parameters
databaseId
String
Located in: path
Required: Yes
ID of your database.
seriesId
String
Located in: path
Required: Yes
ID of the series to be created.
cascadeCreate
Boolean
Located in: body
Required: No
If set to true, the item will be created with the same ID as the series. Default is true.
Responses
201
Successful operation.
400
The seriesId does not match ^[a-zA-Z0-9_-:@.]+$.
409
Series of the given seriesId is already present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.
delete
Delete Series
Deletes the series of the given seriesId from the database.
Deleting a series will only delete assignment of items to it, not the items themselves!
DELETE /{databaseId}/series/{seriesId}
Body (application/json):
{
"cascadeDelete" => <boolean>
}
Parameters
databaseId
String
Located in: path
Required: Yes
ID of your database.
seriesId
String
Located in: path
Required: Yes
ID of the series to be deleted.
cascadeDelete
Boolean
Located in: body
Required: No
If set to true, item with the same ID as seriesId will be also deleted. Default is false.
Responses
200
Successful operation.
400
The seriesId does not match ^[a-zA-Z0-9_-:@.]+$.
404
Series of the given seriesId is not present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been deleted from the database since the series was already not present. If there is no additional info in the JSON response, you probably have an error in your URL.
get
List Series
Gets the list of all the series currently present in the database.
Series of the given seriesId is not present in the database. If there is no additional info in the JSON response, you probably have an error in your URL.
post
Insert to Series
Inserts an existing item/series into a series of the given seriesId at a position determined by time.
POST /{databaseId}/series/{seriesId}/items/
Body (application/json):
{
"itemType" => <string>,
"itemId" => <string>,
"time" => <number>,
"cascadeCreate" => <boolean>
}
Parameters
databaseId
String
Located in: path
Required: Yes
ID of your database.
seriesId
String
Located in: path
Required: Yes
ID of the series to be inserted into.
itemType
String
Located in: body
Required: Yes
item iff the regular item from the catalog is to be inserted, series iff series is inserted as the item.
itemId
String
Located in: body
Required: Yes
ID of the item iff itemType is item. ID of the series iff itemType is series.
time
Number
Located in: body
Required: Yes
Time index used for sorting items in the series. According to time, items are sorted within series in ascending order. In the example of TV show episodes, the episode number is a natural choice to be passed as time.
cascadeCreate
Boolean
Located in: body
Required: No
Indicates that any non-existing entity specified within the request should be created (as if corresponding PUT requests were invoked). This concerns both the seriesId and the itemId. If cascadeCreate is set to true, the behavior also depends on the itemType. In case of item, an item is created, in case of series a series + corresponding item with the same ID is created.
Responses
200
Successful operation.
400
seriesId or itemId does not match ^[a-zA-Z0-9_-:@.]+$, or itemType∉{item,series}, or time is not a real number.
404
Series of the given seriesId is not present in the database. Item of the given itemId is not present in the database if itemType is item. Series of the given itemId is not present in the database if itemType is series. If there is no additional info in the JSON response, you probably have an error in your URL.
409
A series item of the exact same (itemType, itemId, time) is already present in the series of seriesId. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.
ID of the series from which a series item is to be removed.
itemType
String
Located in: body
Required: Yes
Type of the item to be removed.
itemId
String
Located in: body
Required: Yes
ID of the item iff itemType is item. ID of the series iff itemType is series.
Responses
200
Successful operation.
400
The seriesId or itemId does not match ^[a-zA-Z0-9_-:@.]+$ or itemType∉{item, series}.
404
Series of the given seriesId is not present in the database. Series item given by pair (itemType, itemId) is not present in series of seriesId. If there is no additional info in the JSON response, you probably have an error in your URL.
Segmentations Definition
Segmentations allow you to group the Items into various segments: For example segment articles or products by categories, segment movies by genres, etc.
The Segmentations can be used in recommendations (e.g. return the most relevant categories for a user).
Property-based Segmentation groups the Items by the value of a particular property. See this section for more info.
put
Create Property Based Segmentation
Creates a Segmentation that splits the items into segments based on values of a particular item property.
A segment is created for each unique value of the property.
In case of set properties, a segment is created for each value in the set. Item belongs to all these segments.
ID of the Segmentation from which the Segment should be deleted
segmentId
String
Located in: path
Required: Yes
Since version: 4.1.0
ID of the Segment that should be deleted
Responses
201
successful operation
400
segmentationId or segmentId does not match ^[a-zA-Z0-9_-:@.]+$. Segmentation is of wrong type.
404
Segmentation with given ID does not exist. Segment with given ID does not exist in the Segmentation.
Auto ReQL Segmentation
Auto ReQL Segmentation is specified by a ReQL expression that for each Item returns a set of Segments to which the Item belongs. See this section for more info.
ListSegmentationsResponse result = client.Send(ListSegmentations(string sourceType));
Copy
Initialization
request := client.NewListSegmentations(sourceType string)
result, err := request.Send() // result is of the type bindings.ListSegmentationsResponse
Copy
GET /{databaseId}/segmentations/list/?sourceType=<string>
Since version
4.1.0
Calls Limit Per Minute
60
Parameters
databaseId
String
Located in: path
Required: Yes
Since version: 4.1.0
ID of your database.
sourceType
String
Located in: query
Required: Yes
Since version: 4.1.0
List Segmentations based on a particular type of data. Currently only items are supported.
Responses
200
{"segmentations":[{"segmentationId":"category","sourceType":"items","segmentationType":"property","title":"Category Segmentation","description":"Groups items by their category"},{"segmentationId":"homepage-rows","sourceType":"items","segmentationType":"manualReQL","title":"Homepage Rows","description":"Defines individual content rows that can be shown on the homepage"}]}
Segmentation result = client.Send(GetSegmentation(string segmentationId));
Copy
Initialization
request := client.NewGetSegmentation(segmentationId string)
result, err := request.Send() // result is of the type bindings.Segmentation
Copy
GET /{databaseId}/segmentations/list/{segmentationId}
Since version
4.1.0
Parameters
databaseId
String
Located in: path
Required: Yes
Since version: 4.1.0
ID of your database.
segmentationId
String
Located in: path
Required: Yes
Since version: 4.1.0
ID of the Segmentation that should be returned
Responses
200
{"segmentationId":"category","sourceType":"items","segmentationType":"property","title":"Category Segmentation","description":"Groups items by their category"}
Batch processing allows you to submit arbitrary sequence of requests within a single HTTPS request.
Any type of request from the above documentation may be used in the Batch, and the Batch may combine different types of requests arbitrarily as well.
Using Batch requests is beneficial for example, when synchronizing the catalog of items or uploading historical interaction data, as sending the data in Batch is considerably faster than sending the individual requests (thanks to optimizations and reducing network and HTTPS overhead).
request := client.NewBatch(reqs requests.Request[])
// optional parameters:
.SetDistinctRecomms(distinctRecomms bool)
result, err := request.Send() // result is of the type []bindings.BatchResponse
Copy
POST /{databaseId}/batch/
Body (application/json):
{
"requests" => <array>,
"distinctRecomms" => <boolean>
}
Parameters
databaseId
String
Located in: path
Required: Yes
ID of your database.
requests
Array
Located in: body
Required: Yes
JSON array containing the requests.
distinctRecomms
Boolean
Located in: body
Required: No
Since version: 1.2.4
Makes all the recommended items for a certain user distinct among multiple recommendation requests in the batch.
Responses
200
Successful operation. There is an array with responses. The order of the responses in the array follows the order of the sent requests.
Many possibilities, see the error description in the result JSON. Examples: invalid or missing Content-type (not application/json), request body is not a valid JSON, request JSON does not have the prescribed structure.
404
There is at least one request in the batch with an invalid (non-existing) URL. In such a case, the batch as a whole is not executed and you'll get HTTP 404, because the batch is apriori erroneous.
413
Too large batch (containing more than 10,000 requests in case of a server side request).
Examples
Example Sending multiple requests in a single Batch request
# If you use the REST API directly, than the body of a batch request consists of a JSON object.
# The individual requests are given as a JSON array associated with key *requests*.
#
# In the array, each request is encoded as a JSON object containing the following fields:
#
# * method – required string with HTTP method of the request (one of PUT, POST, GET, DELETE, case insensitive),
# * path – required string with path of the request from the root of the database, excluding the query string,
# * params – optional (or required if also required by the request type) object containing values
# of the request's parameters (GET or POST, depending on the request type)
#
# The `params` property may be omitted if there are no attributes to be passed for the request;
# if some attributes are optional, you may or may not include them as in regular request,
#
# Example of executing three requests (setting the item values, adding a detail view,
# and getting user based recommendation) in a batch:
{
"requests": [
{
"method": "POST",
"path": "/items/item-24",
"params": {
"product_description": "4K TV with 3D feature",
"categories": ["Electronics", "Televisions"],
"price_usd": 342,
"!cascadeCreate": true
}
},
{
"method": "POST",
"path": "/detailviews/",
"params": {
"userId": "user-123",
"itemId": "item-x",
"timestamp": 1404727253,
"cascadeCreate": true
}
},
{
"method": "GET",
"path": "/recomms/users/user-123/items/",
"params": {
"count": 3
}
}
]
}
Example Checking the result of the individual requests
You should check that the requests in the Batch succeeded. A request can fail for example due to invalid parameters - the returned error mesage gives you a hint what went wrong.
try {
const responses = await client.send(new recombee.Batch(reqs));
for (const response of responses) {
if (response.code < 200 || response.code > 299) {
// A request in the Batch did not succeedconsole.log(response);
}
}
} catch (error) {
// The whole Batch request failed
}
Copy
val result = client.sendAsync(Batch(requests))
result.onSuccess {batchResponses: List<BatchResponse> ->
// Check individual requests
batchResponses.forEach { response ->
if (!response.successful) {
// A request in the Batch did not succeed// response.getResponse() will throw corresponding ApiException
}
}
}.onFailure { exception -> // ApiException// The whole Batch failed
}
Copy
do {
let responses: [BatchResponse<AnyRecombeeBinding>] =tryawait client.send(batchRequest)
// Iterate through each individual batch responsefor responseWrapper in responses {
if!responseWrapper.isSuccessful {
// A request in the Batch did not succeed// Accessing the response property (responseWrapper.response) will throw the corresponding ClientError
}
}
} catch {
// Handle error for the whole batch requestprint("The entire batch request failed: \(error)")
}
Copy
responses = client.send(Batch(requests))
for response in responses:
ifnot (200 <= response["code"] < 300):
# A request in the Batch did not succeedprint(response)
Copy
responses = client.send(Batch.new(requests))
responses.each do |response|
if response['code'] < 200 || response['code'] > 299# A request in the Batch did not succeed
puts response
endend
Copy
// Send the Batch to the Recombee API
BatchResponse[] responses = client.send(batch);
// Check if the Batch was successfulfor (BatchResponse response : responses) {
if (!response.isSuccessful()) {
// A request in the Batch did not succeed// response.getResponse() will throw corresponding ApiException
}
}
Copy
try {
const responses = await client.send(new rqs.Batch(reqs));
for (const response of responses) {
if (response.code < 200 || response.code > 299) {
// A request in the Batch did not succeedconsole.log(response);
}
}
} catch (error) {
// The whole Batch request failed
}
Copy
// Send the Batch to the Recombee API$responses = $client->send($batch);
// Check if the Batch was successfulforeach ($responsesas$response) {
if (200 < $response["code"] || $response["code"] >= 300) {
// A request in the Batch did not succeedprint($response);
}
}
Copy
var responses = client.Send(batch);
for (int i = 0; i < responses.StatusCodes.Length; i++)
{
if (((int)responses.StatusCodes[i]) < 200 || ((int)responses.StatusCodes[i]) >= 300)
{
// A request in the Batch did not succeed// Accessing responses[i] will throw corresponding ApiException
}
}
Copy
batchRes, err := client.NewBatch(requestsBatch).Send()
if err != nil {
fmt.Println(err)
panic(err)
}
for i, resp := range batchRes {
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
fmt.Printf("Request #%d failed with status code %d: %s\n", i, resp.StatusCode, resp.Error.ErrorMessage)
}
}
Example Using distinctRecomms parameter to deduplicate results in multiple boxes
If you show multiple boxes with recommendations on a single page, you may want to ensure that the same item is not recommended in multiple boxes. You can achieve that by specifying distinctRecomms=true.
Executing the requests in a Batch is equivalent as if they were executed one-by-one individually; there are, however, many optimizations to make batch execution as fast as possible.
The status code of the Batch request itself is 200 even if the individual requests result in error – you have to inspect the code values in the resulting array.
If the status code of the whole batch is not 200, then there is an error in the Batch request itself; in such a case, the error message returned should help you to resolve the problem.
The batch size is limited to 10,000 requests when sent from the server side; if you wish to execute even larger number of requests, please split the Batch into multiple parts. Client libraries do the splitting automatically.
In case of the client side integration, the limit is 30 requests and only the requests that can be called from the client side are allowed.
Completely erases all your data, including items, item properties, series, user database, purchases, ratings, detail views, and bookmarks. Make sure the request is never executed in the production environment! Resetting your database is irreversible.