API Reference
This section lists all the available API endpoints, that allow you to manage item catalog, users, their interactions and get recommendations.
- Version:
5.0.0
- Base URL: Based on the region of your database
- API consumes:
application/json
- API produces:
application/json
- Authentication: HMAC (already implemented in the SDKs)
Items
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.
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.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.AddItem(itemId));
client.send(AddItem(item_id))
client.send(AddItem.new(itemId))
client.send(new AddItem(String itemId));
<?php
$client->send(new AddItem($item_id));
?>
client.Send(AddItem(string itemId));
request := client.NewAddItem(itemId string)
_, err := request.Send()
PUT /{databaseId}/items/{itemId}
Parameters
ID of your database.
ID of the item to be created.
Responses
Successful operation.
The itemId
does not match ^[a-zA-Z0-9_-:@.]+$.
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 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.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.DeleteItem(itemId));
client.send(DeleteItem(item_id))
client.send(DeleteItem.new(itemId))
client.send(new DeleteItem(String itemId));
<?php
$client->send(new DeleteItem($item_id));
?>
client.Send(DeleteItem(string itemId));
request := client.NewDeleteItem(itemId string)
_, err := request.Send()
DELETE /{databaseId}/items/{itemId}
Parameters
ID of your database.
ID of the item to be deleted.
Responses
Successful operation.
The itemId
does not match ^[a-zA-Z0-9_-:@.]+$.
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.
List Items
Gets a list of IDs of items currently present in the catalog.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.ListItems({
// optional parameters:
'filter': <string>,
'count': <integer>,
'offset': <integer>,
'returnProperties': <boolean>,
'includedProperties': <array>
}))
.then((response) => {
//handle response
})
.catch((error) => {
//handle error
});
result = client.send(ListItems(
# optional parameters:
filter=<string>,
count=<integer>,
offset=<integer>,
return_properties=<boolean>,
included_properties=<array>
)
)
result = client.send(ListItems.new({
# optional parameters:
:filter => <string>,
:count => <integer>,
:offset => <integer>,
:return_properties => <boolean>,
:included_properties => <array>
})
)
Item[] result = client.send(new ListItems()
.setFilter(String filter)
.setCount(long count)
.setOffset(long offset)
.setReturnProperties(boolean returnProperties)
.setIncludedProperties(String[] includedProperties)
);
<?php
$result = $client->send(new ListItems([
// optional parameters:
'filter' => <string>,
'count' => <integer>,
'offset' => <integer>,
'returnProperties' => <boolean>,
'includedProperties' => <array>
])
);
?>
IEnumerable<Item> result = client.Send(ListItems(
// optional parameters:
filter: <string>,
count: <long>,
offset: <long>,
returnProperties: <bool>,
includedProperties: <string[]>
)
);
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
GET /{databaseId}/items/list/?filter=<string>
&count=<integer>
&offset=<integer>
&returnProperties=<boolean>
&includedProperties=<array>
Parameters
ID of your database.
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.
The number of items to be listed.
Specifies the number of items to skip (ordered by itemId
).
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"
}
]
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
Successful operation.
[
"item-1",
"item-2",
"item-3"
]
If present, filter
contains a non-existing item property.
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.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.DeleteMoreItems(filter))
.then((response) => {
//handle response
})
.catch((error) => {
//handle error
});
result = client.send(DeleteMoreItems(filter))
result = client.send(DeleteMoreItems.new(filter))
DeleteMoreItemsResponse result = client.send(new DeleteMoreItems(String filter));
<?php
$result = $client->send(new DeleteMoreItems($filter));
?>
DeleteMoreItemsResponse result = client.Send(DeleteMoreItems(string filter));
request := client.NewDeleteMoreItems(filter string)
result, err := request.Send() // result is of the type bindings.DeleteMoreItemsResponse
DELETE /{databaseId}/more-items/
Body (application/json):
{
"filter" => <string>
}
Parameters
ID of your database.
A ReQL expression, which returns true
for the items that shall be updated.
Responses
Successful operation.
{
"itemIds": [
"item-42",
"item-125",
"item-11"
],
"count": 3
}
Invalid filter.
Item Properties
Item properties definition
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.
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.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.AddItemProperty(propertyName, type));
client.send(AddItemProperty(property_name, type))
client.send(AddItemProperty.new(propertyName, type))
client.send(new AddItemProperty(String propertyName, String type));
<?php
$client->send(new AddItemProperty($property_name, $type));
?>
client.Send(AddItemProperty(string propertyName, string type));
request := client.NewAddItemProperty(propertyName string, type string)
_, err := request.Send()
PUT /{databaseId}/items/properties/{propertyName}?type=<string>
Parameters
ID of your database.
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.
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. -
set
- Set of strings. -
image
- URL of an image (jpeg
,png
orgif
). -
imageList
- List of URLs that refer to images.
Responses
Successful operation.
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.
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 Item Property
Deleting an item property is roughly equivalent to removing a column from the table of items.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.DeleteItemProperty(propertyName));
client.send(DeleteItemProperty(property_name))
client.send(DeleteItemProperty.new(propertyName))
client.send(new DeleteItemProperty(String propertyName));
<?php
$client->send(new DeleteItemProperty($property_name));
?>
client.Send(DeleteItemProperty(string propertyName));
request := client.NewDeleteItemProperty(propertyName string)
_, err := request.Send()
DELETE /{databaseId}/items/properties/{propertyName}
Parameters
ID of your database.
Name of the property to be deleted.
Responses
Successful operation.
Property name does not match ^[a-zA-Z0-9_-:]+$.
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.
Get Item Property Info
Gets information about specified item property.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.GetItemPropertyInfo(propertyName))
.then((response) => {
//handle response
})
.catch((error) => {
//handle error
});
result = client.send(GetItemPropertyInfo(property_name))
result = client.send(GetItemPropertyInfo.new(propertyName))
PropertyInfo result = client.send(new GetItemPropertyInfo(String propertyName));
<?php
$result = $client->send(new GetItemPropertyInfo($property_name));
?>
PropertyInfo result = client.Send(GetItemPropertyInfo(string propertyName));
request := client.NewGetItemPropertyInfo(propertyName string)
result, err := request.Send() // result is of the type bindings.PropertyInfo
GET /{databaseId}/items/properties/{propertyName}
Parameters
ID of your database.
Name of the property about which the information is to be retrieved.
Responses
Successful operation.
{
"name": "num-processors",
"type": "int"
}
Property name does not match ^[a-zA-Z0-9_-:]+$.
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.
List Item Properties
Gets the list of all the item properties in your database.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.ListItemProperties())
.then((response) => {
//handle response
})
.catch((error) => {
//handle error
});
result = client.send(ListItemProperties())
result = client.send(ListItemProperties.new())
PropertyInfo[] result = client.send(new ListItemProperties());
<?php
$result = $client->send(new ListItemProperties());
?>
IEnumerable<PropertyInfo> result = client.Send(ListItemProperties());
request := client.NewListItemProperties()
result, err := request.Send() // result is of the type []bindings.PropertyInfo
GET /{databaseId}/items/properties/list/
Parameters
ID of your database.
Responses
Successful operation.
[
{
"name": "tags",
"type": "set"
},
{
"name": "release-date",
"type": "timestamp"
},
{
"name": "description",
"type": "string"
}
]
Invalid URL.
Values of item properties
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.
Set Item Values
Sets/updates (some) property values of the given item. The properties (columns) must be previously created by Add item property.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.SetItemValues(itemId, values, {
// optional parameters:
'cascadeCreate': <boolean>
}));
client.send(SetItemValues(item_id, values,
# optional parameters:
cascade_create=<boolean>
)
)
client.send(SetItemValues.new(itemId, values, {
# optional parameters:
:cascade_create => <boolean>
})
)
client.send(new SetItemValues(String itemId, Map<String, Object> values)
.setCascadeCreate(boolean cascadeCreate)
);
<?php
$client->send(new SetItemValues($item_id, $values, [
// optional parameters:
'cascadeCreate' => <boolean>
])
);
?>
client.Send(SetItemValues(string itemId, Dictionary<string, object> values,
// optional parameters:
cascadeCreate: <bool>
)
);
request := client.NewSetItemValues(itemId string, values map[string]interface{})
// optional parameters:
.SetCascadeCreate(cascadeCreate bool)
_, err := request.Send()
POST /{databaseId}/items/{itemId}
Parameters
ID of your database.
ID of the item which will be modified.
The values for the individual properties.
Example of the body:
{
"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
Successful operation.
Property name does not match ''^[a-zA-Z0-9_-:]+$'', value does not match the property type.
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 Item Values
Gets all the current property values of the given item.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.GetItemValues(itemId))
.then((response) => {
//handle response
})
.catch((error) => {
//handle error
});
result = client.send(GetItemValues(item_id))
result = client.send(GetItemValues.new(itemId))
Map<String, Object> result = client.send(new GetItemValues(String itemId));
<?php
$result = $client->send(new GetItemValues($item_id));
?>
StringBinding result = client.Send(GetItemValues(string itemId));
request := client.NewGetItemValues(itemId string)
result, err := request.Send() // result is of the type map[string]interface{}
GET /{databaseId}/items/{itemId}
Parameters
ID of your database.
ID of the item whose properties are to be obtained.
Responses
Successful operation.
{
"release-date": null,
"tags": [
"electronics",
"laptops"
],
"num-processors": 12,
"description": "Very powerful laptop",
"weight": 1.6
}
The itemId does not match ^[a-zA-Z0-9_-:@.]+$
Item of the given itemId is not present in the catalog. If there is no additional info in the JSON response, you probably have an error in your URL.
Update More Items
Updates (some) property values of all the items that pass the filter.
Example: Setting all the items that are older than a week as unavailable
{
"filter": "'releaseDate' < now() - 7*24*3600",
"changes": {"available": false}
}
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.UpdateMoreItems(filter, changes))
.then((response) => {
//handle response
})
.catch((error) => {
//handle error
});
result = client.send(UpdateMoreItems(filter, changes))
result = client.send(UpdateMoreItems.new(filter, changes))
UpdateMoreItemsResponse result = client.send(new UpdateMoreItems(String filter, Map<String, Object> changes));
<?php
$result = $client->send(new UpdateMoreItems($filter, $changes));
?>
UpdateMoreItemsResponse result = client.Send(UpdateMoreItems(string filter, Dictionary<string, object> changes));
request := client.NewUpdateMoreItems(filter string, changes map[string]interface{})
result, err := request.Send() // result is of the type bindings.UpdateMoreItemsResponse
POST /{databaseId}/more-items/
Body (application/json):
{
"filter" => <string>,
"changes" => <Object>
}
Parameters
ID of your database.
A ReQL expression, which returns true
for the items that shall be updated.
A dictionary where the keys are properties that shall be updated.
Responses
Successful operation. Returns IDs of updated items and their count.
{
"itemIds": [
"item-42",
"item-125",
"item-11"
],
"count": 3
}
Invalid filter, property name does not match ''^[a-zA-Z0-9_-:]+$'', value does not match the property type.
Property of the given name is not present in the database.
Users
The following methods allow you to manage users in your database.
Add User
Adds a new user to the database.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.AddUser(userId));
client.send(AddUser(user_id))
client.send(AddUser.new(userId))
client.send(new AddUser(String userId));
<?php
$client->send(new AddUser($user_id));
?>
client.Send(AddUser(string userId));
request := client.NewAddUser(userId string)
_, err := request.Send()
PUT /{databaseId}/users/{userId}
Parameters
ID of your database.
ID of the user to be added.
Responses
Successful operation.
The userId
does not match ^[a-zA-Z0-9_-:@.]+$.
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 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.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.DeleteUser(userId));
client.send(DeleteUser(user_id))
client.send(DeleteUser.new(userId))
client.send(new DeleteUser(String userId));
<?php
$client->send(new DeleteUser($user_id));
?>
client.Send(DeleteUser(string userId));
request := client.NewDeleteUser(userId string)
_, err := request.Send()
DELETE /{databaseId}/users/{userId}
Parameters
ID of your database.
ID of the user to be deleted.
Responses
Successful operation.
The userId does not match ''^[a-zA-Z0-9_-:@.]+$''.
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.
Merge Users
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.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.MergeUsers(targetUserId, sourceUserId, {
// optional parameters:
'cascadeCreate': <boolean>
}));
client.send(MergeUsers(target_user_id, source_user_id,
# optional parameters:
cascade_create=<boolean>
)
)
client.send(MergeUsers.new(targetUserId, sourceUserId, {
# optional parameters:
:cascade_create => <boolean>
})
)
client.send(new MergeUsers(String targetUserId, String sourceUserId)
.setCascadeCreate(boolean cascadeCreate)
);
<?php
$client->send(new MergeUsers($target_user_id, $source_user_id, [
// optional parameters:
'cascadeCreate' => <boolean>
])
);
?>
client.Send(MergeUsers(string targetUserId, string sourceUserId,
// optional parameters:
cascadeCreate: <bool>
)
);
request := client.NewMergeUsers(targetUserId string, sourceUserId string)
// optional parameters:
.SetCascadeCreate(cascadeCreate bool)
_, err := request.Send()
PUT /{databaseId}/users/{targetUserId}/merge/{sourceUserId}?cascadeCreate=<boolean>
Parameters
ID of your database.
ID of the target user.
ID of the source user.
Sets whether the user targetUserId should be created if not present in the database.
Responses
Successful operation.
The sourceUserId or targetUserId does not match ^[a-zA-Z0-9_-:@.]+$
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.
List Users
Gets a list of IDs of users currently present in the catalog.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.ListUsers({
// optional parameters:
'filter': <string>,
'count': <integer>,
'offset': <integer>,
'returnProperties': <boolean>,
'includedProperties': <array>
}))
.then((response) => {
//handle response
})
.catch((error) => {
//handle error
});
result = client.send(ListUsers(
# optional parameters:
filter=<string>,
count=<integer>,
offset=<integer>,
return_properties=<boolean>,
included_properties=<array>
)
)
result = client.send(ListUsers.new({
# optional parameters:
:filter => <string>,
:count => <integer>,
:offset => <integer>,
:return_properties => <boolean>,
:included_properties => <array>
})
)
User[] result = client.send(new ListUsers()
.setFilter(String filter)
.setCount(long count)
.setOffset(long offset)
.setReturnProperties(boolean returnProperties)
.setIncludedProperties(String[] includedProperties)
);
<?php
$result = $client->send(new ListUsers([
// optional parameters:
'filter' => <string>,
'count' => <integer>,
'offset' => <integer>,
'returnProperties' => <boolean>,
'includedProperties' => <array>
])
);
?>
IEnumerable<User> result = client.Send(ListUsers(
// optional parameters:
filter: <string>,
count: <long>,
offset: <long>,
returnProperties: <bool>,
includedProperties: <string[]>
)
);
request := client.NewListUsers()
// 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.User
GET /{databaseId}/users/list/?filter=<string>
&count=<integer>
&offset=<integer>
&returnProperties=<boolean>
&includedProperties=<array>
Parameters
ID of your database.
Boolean-returning ReQL expression, which allows you to filter users to be listed. Only the users for which the expression is true will be returned.
The number of users to be listed.
Specifies the number of users to skip (ordered by userId
).
With returnProperties=true
, property values of the listed users are returned along with their IDs in a JSON dictionary.
Example response:
[
{
"userId": "user-81",
"country": "US",
"sex": "M"
},
{
"userId": "user-314",
"country": "CAN",
"sex": "F"
}
]
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=country
:
[
{
"userId": "user-81",
"country": "US"
},
{
"userId": "user-314",
"country": "CAN"
}
]
Responses
Successful operation.
[
"user-1",
"user-2",
"user-3"
]
Invalid URL.
User Properties
User properties definition
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.
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.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.AddUserProperty(propertyName, type));
client.send(AddUserProperty(property_name, type))
client.send(AddUserProperty.new(propertyName, type))
client.send(new AddUserProperty(String propertyName, String type));
<?php
$client->send(new AddUserProperty($property_name, $type));
?>
client.Send(AddUserProperty(string propertyName, string type));
request := client.NewAddUserProperty(propertyName string, type string)
_, err := request.Send()
PUT /{databaseId}/users/properties/{propertyName}?type=<string>
Parameters
ID of your database.
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.
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. -
set
- Set of strings.
Responses
Successful operation.
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.
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 User Property
Deleting a user property is roughly equivalent to removing a column from the table of users.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.DeleteUserProperty(propertyName));
client.send(DeleteUserProperty(property_name))
client.send(DeleteUserProperty.new(propertyName))
client.send(new DeleteUserProperty(String propertyName));
<?php
$client->send(new DeleteUserProperty($property_name));
?>
client.Send(DeleteUserProperty(string propertyName));
request := client.NewDeleteUserProperty(propertyName string)
_, err := request.Send()
DELETE /{databaseId}/users/properties/{propertyName}
Parameters
ID of your database.
Name of the property to be deleted.
Responses
Successful operation.
Property name does not match ^[a-zA-Z0-9_-:]+$.
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.
Get User Property Info
Gets information about specified user property.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.GetUserPropertyInfo(propertyName))
.then((response) => {
//handle response
})
.catch((error) => {
//handle error
});
result = client.send(GetUserPropertyInfo(property_name))
result = client.send(GetUserPropertyInfo.new(propertyName))
PropertyInfo result = client.send(new GetUserPropertyInfo(String propertyName));
<?php
$result = $client->send(new GetUserPropertyInfo($property_name));
?>
PropertyInfo result = client.Send(GetUserPropertyInfo(string propertyName));
request := client.NewGetUserPropertyInfo(propertyName string)
result, err := request.Send() // result is of the type bindings.PropertyInfo
GET /{databaseId}/users/properties/{propertyName}
Parameters
ID of your database.
Name of the property about which the information is to be retrieved.
Responses
Successful operation.
{
"name": "country",
"type": "string"
}
Property name does not match ^[a-zA-Z0-9_-:]+$.
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.
List User Properties
Gets the list of all the user properties in your database.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.ListUserProperties())
.then((response) => {
//handle response
})
.catch((error) => {
//handle error
});
result = client.send(ListUserProperties())
result = client.send(ListUserProperties.new())
PropertyInfo[] result = client.send(new ListUserProperties());
<?php
$result = $client->send(new ListUserProperties());
?>
IEnumerable<PropertyInfo> result = client.Send(ListUserProperties());
request := client.NewListUserProperties()
result, err := request.Send() // result is of the type []bindings.PropertyInfo
GET /{databaseId}/users/properties/list/
Parameters
ID of your database.
Responses
Successful operation.
[
{
"name": "country",
"type": "string"
},
{
"name": "sex",
"type": "string"
}
]
Invalid URL.
Values of user properties
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.
Set User Values
Sets/updates (some) property values of the given user. The properties (columns) must be previously created by Add user property.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.SetUserValues(userId, values, {
// optional parameters:
'cascadeCreate': <boolean>
}));
client.send(SetUserValues(user_id, values,
# optional parameters:
cascade_create=<boolean>
)
)
client.send(SetUserValues.new(userId, values, {
# optional parameters:
:cascade_create => <boolean>
})
)
client.send(new SetUserValues(String userId, Map<String, Object> values)
.setCascadeCreate(boolean cascadeCreate)
);
<?php
$client->send(new SetUserValues($user_id, $values, [
// optional parameters:
'cascadeCreate' => <boolean>
])
);
?>
client.Send(SetUserValues(string userId, Dictionary<string, object> values,
// optional parameters:
cascadeCreate: <bool>
)
);
request := client.NewSetUserValues(userId string, values map[string]interface{})
// optional parameters:
.SetCascadeCreate(cascadeCreate bool)
_, err := request.Send()
POST /{databaseId}/users/{userId}
Parameters
ID of your database.
ID of the user which will be modified.
The values for the individual properties.
Example of the body:
{
"country": "US",
"sex": "F"
}
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
Successful operation.
Property name does not match ''^[a-zA-Z0-9_-:]+$'', value does not agree to property type.
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 User Values
Gets all the current property values of the given user.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.GetUserValues(userId))
.then((response) => {
//handle response
})
.catch((error) => {
//handle error
});
result = client.send(GetUserValues(user_id))
result = client.send(GetUserValues.new(userId))
Map<String, Object> result = client.send(new GetUserValues(String userId));
<?php
$result = $client->send(new GetUserValues($user_id));
?>
StringBinding result = client.Send(GetUserValues(string userId));
request := client.NewGetUserValues(userId string)
result, err := request.Send() // result is of the type map[string]interface{}
GET /{databaseId}/users/{userId}
Parameters
ID of your database.
ID of the user whose properties are to be obtained.
Responses
Successful operation.
{
"country": "US",
"sex": "F"
}
The userId does not match ^[a-zA-Z0-9_-:@.]+$
User of the given userId is not present in the catalog. If there is no additional info in the JSON response, you probably have an error in your URL.
User-Item Interactions
The following methods allow adding, deleting, and listing interactions between the users and the items.
Detail Views
Add Detail View
Adds a detail view of the given item made by the given user.
client.send(new recombee.AddDetailView(userId, itemId, {
// optional parameters:
'timestamp': <string / number>,
'duration': <integer>,
'cascadeCreate': <boolean>,
'recommId': <string>
}));
client.send(AddDetailView(userId: String, itemId: String,
// optional parameters:
timestamp: Instant,
duration: Long,
cascadeCreate: Boolean,
recommId: String
)
)
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.AddDetailView(userId, itemId, {
// optional parameters:
'timestamp': <string / number>,
'duration': <integer>,
'cascadeCreate': <boolean>,
'recommId': <string>
}));
client.send(AddDetailView(user_id, item_id,
# optional parameters:
timestamp=<string / number>,
duration=<integer>,
cascade_create=<boolean>,
recomm_id=<string>
)
)
client.send(AddDetailView.new(userId, itemId, {
# optional parameters:
:timestamp => <string / number>,
:duration => <integer>,
:cascade_create => <boolean>,
:recomm_id => <string>
})
)
client.send(new AddDetailView(String userId, String itemId)
.setTimestamp(Date timestamp)
.setDuration(long duration)
.setCascadeCreate(boolean cascadeCreate)
.setRecommId(String recommId)
);
<?php
$client->send(new AddDetailView($user_id, $item_id, [
// optional parameters:
'timestamp' => <string / number>,
'duration' => <integer>,
'cascadeCreate' => <boolean>,
'recommId' => <string>
])
);
?>
client.Send(AddDetailView(string userId, string itemId,
// optional parameters:
timestamp: <DateTime>,
duration: <long>,
cascadeCreate: <bool>,
recommId: <string>
)
);
request := client.NewAddDetailView(userId string, itemId string)
// optional parameters:
.SetTimestamp(timestamp time.Time)
.SetDuration(duration int)
.SetCascadeCreate(cascadeCreate bool)
.SetRecommId(recommId string)
_, err := request.Send()
POST /{databaseId}/detailviews/
Body (application/json):
{
"userId" => <string>,
"itemId" => <string>,
"timestamp" => <string / number>,
"duration" => <integer>,
"cascadeCreate" => <boolean>,
"recommId" => <string>
}
Parameters
ID of your database.
User who viewed the item
Viewed item
UTC timestamp of the view as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
Duration of the view
Sets whether the given user/item should be created if not present in the database.
If this detail view is based on a recommendation request, recommId
is the id of the clicked recommendation.
Responses
Successful operation.
Given userId
or itemId
does not match ^[a-zA-Z0-9_-:@.]+$. timestamp
or duration
is not a real number ≥ 0.
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.
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 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.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.DeleteDetailView(userId, itemId, {
// optional parameters:
'timestamp': <number>
}));
client.send(DeleteDetailView(user_id, item_id,
# optional parameters:
timestamp=<number>
)
)
client.send(DeleteDetailView.new(userId, itemId, {
# optional parameters:
:timestamp => <number>
})
)
client.send(new DeleteDetailView(String userId, String itemId)
.setTimestamp(Date timestamp)
);
<?php
$client->send(new DeleteDetailView($user_id, $item_id, [
// optional parameters:
'timestamp' => <number>
])
);
?>
client.Send(DeleteDetailView(string userId, string itemId,
// optional parameters:
timestamp: <DateTime>
)
);
request := client.NewDeleteDetailView(userId string, itemId string)
// optional parameters:
.SetTimestamp(timestamp time.Time)
_, err := request.Send()
DELETE /{databaseId}/detailviews/?userId=<string>
&itemId=<string>
×tamp=<number>
Parameters
ID of your database.
ID of the user who made the detail view.
ID of the item whose details were viewed.
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
Successful operation.
Given userId
or itemId
does not match ^[a-zA-Z0-9_-:@.]+$, or timestamp
is not a real number ≥ 0.
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.
List Item Detail Views
Lists all the detail views of the given item ever made by different users.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.ListItemDetailViews(itemId))
.then((response) => {
//handle response
})
.catch((error) => {
//handle error
});
result = client.send(ListItemDetailViews(item_id))
result = client.send(ListItemDetailViews.new(itemId))
DetailView[] result = client.send(new ListItemDetailViews(String itemId));
<?php
$result = $client->send(new ListItemDetailViews($item_id));
?>
IEnumerable<DetailView> result = client.Send(ListItemDetailViews(string itemId));
request := client.NewListItemDetailViews(itemId string)
result, err := request.Send() // result is of the type []bindings.DetailView
GET /{databaseId}/items/{itemId}/detailviews/
Parameters
ID of your database.
ID of the item whose detail views are to be listed.
Responses
Successful operation.
[
{
"itemId": "item-x",
"userId": "user-a",
"duration": 14.23,
"timestamp": 1348151906.0
},
{
"itemId": "item-x",
"userId": "user-b",
"duration": null,
"timestamp": 1348239363.0
}
]
The itemId
does not match ^[a-zA-Z0-9_-:@.]+$.
Given itemId
not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.
List User Detail Views
Lists all the detail views of different items ever made by the given user.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.ListUserDetailViews(userId))
.then((response) => {
//handle response
})
.catch((error) => {
//handle error
});
result = client.send(ListUserDetailViews(user_id))
result = client.send(ListUserDetailViews.new(userId))
DetailView[] result = client.send(new ListUserDetailViews(String userId));
<?php
$result = $client->send(new ListUserDetailViews($user_id));
?>
IEnumerable<DetailView> result = client.Send(ListUserDetailViews(string userId));
request := client.NewListUserDetailViews(userId string)
result, err := request.Send() // result is of the type []bindings.DetailView
GET /{databaseId}/users/{userId}/detailviews/
Parameters
ID of your database.
ID of the user whose detail views are to be listed.
Responses
Successful operation.
[
{
"itemId": "item-y",
"userId": "user-a",
"duration": 134.03,
"timestamp": 1348139180.0
},
{
"itemId": "item-x",
"userId": "user-a",
"duration": 14.23,
"timestamp": 1348151906.0
}
]
The userId
does not match ^[a-zA-Z0-9_-:@.]+$.
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.
Purchases
Add Purchase
Adds a purchase of the given item made by the given user.
client.send(new recombee.AddPurchase(userId, itemId, {
// optional parameters:
'timestamp': <string / number>,
'cascadeCreate': <boolean>,
'amount': <number>,
'price': <number>,
'profit': <number>,
'recommId': <string>
}));
client.send(AddPurchase(userId: String, itemId: String,
// optional parameters:
timestamp: Instant,
cascadeCreate: Boolean,
amount: Double,
price: Double,
profit: Double,
recommId: String
)
)
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.AddPurchase(userId, itemId, {
// optional parameters:
'timestamp': <string / number>,
'cascadeCreate': <boolean>,
'amount': <number>,
'price': <number>,
'profit': <number>,
'recommId': <string>
}));
client.send(AddPurchase(user_id, item_id,
# optional parameters:
timestamp=<string / number>,
cascade_create=<boolean>,
amount=<number>,
price=<number>,
profit=<number>,
recomm_id=<string>
)
)
client.send(AddPurchase.new(userId, itemId, {
# optional parameters:
:timestamp => <string / number>,
:cascade_create => <boolean>,
:amount => <number>,
:price => <number>,
:profit => <number>,
:recomm_id => <string>
})
)
client.send(new AddPurchase(String userId, String itemId)
.setTimestamp(Date timestamp)
.setCascadeCreate(boolean cascadeCreate)
.setAmount(double amount)
.setPrice(double price)
.setProfit(double profit)
.setRecommId(String recommId)
);
<?php
$client->send(new AddPurchase($user_id, $item_id, [
// optional parameters:
'timestamp' => <string / number>,
'cascadeCreate' => <boolean>,
'amount' => <number>,
'price' => <number>,
'profit' => <number>,
'recommId' => <string>
])
);
?>
client.Send(AddPurchase(string userId, string itemId,
// optional parameters:
timestamp: <DateTime>,
cascadeCreate: <bool>,
amount: <double>,
price: <double>,
profit: <double>,
recommId: <string>
)
);
request := client.NewAddPurchase(userId string, itemId string)
// optional parameters:
.SetTimestamp(timestamp time.Time)
.SetCascadeCreate(cascadeCreate bool)
.SetAmount(amount float64)
.SetPrice(price float64)
.SetProfit(profit float64)
.SetRecommId(recommId string)
_, err := request.Send()
POST /{databaseId}/purchases/
Body (application/json):
{
"userId" => <string>,
"itemId" => <string>,
"timestamp" => <string / number>,
"cascadeCreate" => <boolean>,
"amount" => <number>,
"price" => <number>,
"profit" => <number>,
"recommId" => <string>
}
Parameters
ID of your database.
User who purchased the item
Purchased item
UTC timestamp of the purchase as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
Sets whether the given user/item should be created if not present in the database.
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 paid by the user for the item. If amount
is greater than 1, the sum of prices of all the items should be given.
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.
If this purchase is based on a recommendation request, recommId
is the id of the clicked recommendation.
Responses
Successful operation.
The userId
or itemId
does not match ^[a-zA-Z0-9_-:@.]+$. timestamp
is not a real number ≥ 0.
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.
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 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.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.DeletePurchase(userId, itemId, {
// optional parameters:
'timestamp': <number>
}));
client.send(DeletePurchase(user_id, item_id,
# optional parameters:
timestamp=<number>
)
)
client.send(DeletePurchase.new(userId, itemId, {
# optional parameters:
:timestamp => <number>
})
)
client.send(new DeletePurchase(String userId, String itemId)
.setTimestamp(Date timestamp)
);
<?php
$client->send(new DeletePurchase($user_id, $item_id, [
// optional parameters:
'timestamp' => <number>
])
);
?>
client.Send(DeletePurchase(string userId, string itemId,
// optional parameters:
timestamp: <DateTime>
)
);
request := client.NewDeletePurchase(userId string, itemId string)
// optional parameters:
.SetTimestamp(timestamp time.Time)
_, err := request.Send()
DELETE /{databaseId}/purchases/?userId=<string>
&itemId=<string>
×tamp=<number>
Parameters
ID of your database.
ID of the user who made the purchase.
ID of the item which was purchased.
Unix timestamp of the purchase. If the timestamp
is omitted, then all the purchases with the given userId
and itemId
are deleted.
Responses
Successful operation.
Given userId
or itemId
does not match ^[a-zA-Z0-9_-:@.]+$, or timestamp
is not a real number ≥ 0.
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.
List Item Purchases
Lists all the ever-made purchases of the given item.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.ListItemPurchases(itemId))
.then((response) => {
//handle response
})
.catch((error) => {
//handle error
});
result = client.send(ListItemPurchases(item_id))
result = client.send(ListItemPurchases.new(itemId))
Purchase[] result = client.send(new ListItemPurchases(String itemId));
<?php
$result = $client->send(new ListItemPurchases($item_id));
?>
IEnumerable<Purchase> result = client.Send(ListItemPurchases(string itemId));
request := client.NewListItemPurchases(itemId string)
result, err := request.Send() // result is of the type []bindings.Purchase
GET /{databaseId}/items/{itemId}/purchases/
Parameters
ID of your database.
ID of the item whose purchases are to be listed.
Responses
Successful operation.
[
{
"itemId": "item-x",
"userId": "user-a",
"timestamp": 1348151906.0
},
{
"itemId": "item-x",
"userId": "user-b",
"timestamp": 1348327154.0
}
]
The itemId
does not match ^[a-zA-Z0-9_-:@.]+$.
Given itemId
not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.
List User Purchases
Lists all the purchases ever made by the given user.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.ListUserPurchases(userId))
.then((response) => {
//handle response
})
.catch((error) => {
//handle error
});
result = client.send(ListUserPurchases(user_id))
result = client.send(ListUserPurchases.new(userId))
Purchase[] result = client.send(new ListUserPurchases(String userId));
<?php
$result = $client->send(new ListUserPurchases($user_id));
?>
IEnumerable<Purchase> result = client.Send(ListUserPurchases(string userId));
request := client.NewListUserPurchases(userId string)
result, err := request.Send() // result is of the type []bindings.Purchase
GET /{databaseId}/users/{userId}/purchases/
Parameters
ID of your database.
ID of the user whose purchases are to be listed.
Responses
Successful operation.
[
{
"itemId": "item-x",
"timestamp": 1348151906.0,
"userId": "user-a"
},
{
"itemId": "item-z",
"timestamp": 1348239363.0,
"userId": "user-a"
}
]
The userId
does not match ^[a-zA-Z0-9_-:@.]+$.
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.
Ratings
Add Rating
Adds a rating of the given item made by the given user.
client.send(new recombee.AddRating(userId, itemId, rating, {
// optional parameters:
'timestamp': <string / number>,
'cascadeCreate': <boolean>,
'recommId': <string>
}));
client.send(AddRating(userId: String, itemId: String, rating: Double,
// optional parameters:
timestamp: Instant,
cascadeCreate: Boolean,
recommId: String
)
)
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.AddRating(userId, itemId, rating, {
// optional parameters:
'timestamp': <string / number>,
'cascadeCreate': <boolean>,
'recommId': <string>
}));
client.send(AddRating(user_id, item_id, rating,
# optional parameters:
timestamp=<string / number>,
cascade_create=<boolean>,
recomm_id=<string>
)
)
client.send(AddRating.new(userId, itemId, rating, {
# optional parameters:
:timestamp => <string / number>,
:cascade_create => <boolean>,
:recomm_id => <string>
})
)
client.send(new AddRating(String userId, String itemId, double rating)
.setTimestamp(Date timestamp)
.setCascadeCreate(boolean cascadeCreate)
.setRecommId(String recommId)
);
<?php
$client->send(new AddRating($user_id, $item_id, $rating, [
// optional parameters:
'timestamp' => <string / number>,
'cascadeCreate' => <boolean>,
'recommId' => <string>
])
);
?>
client.Send(AddRating(string userId, string itemId, double rating,
// optional parameters:
timestamp: <DateTime>,
cascadeCreate: <bool>,
recommId: <string>
)
);
request := client.NewAddRating(userId string, itemId string, rating float64)
// optional parameters:
.SetTimestamp(timestamp time.Time)
.SetCascadeCreate(cascadeCreate bool)
.SetRecommId(recommId string)
_, err := request.Send()
POST /{databaseId}/ratings/
Body (application/json):
{
"userId" => <string>,
"itemId" => <string>,
"timestamp" => <string / number>,
"rating" => <number>,
"cascadeCreate" => <boolean>,
"recommId" => <string>
}
Parameters
ID of your database.
User who submitted the rating
Rated item
UTC timestamp of the rating as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
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.
Sets whether the given user/item should be created if not present in the database.
If this rating is based on a recommendation request, recommId
is the id of the clicked recommendation.
Responses
Successful operation.
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.
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.
A rating 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 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.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.DeleteRating(userId, itemId, {
// optional parameters:
'timestamp': <number>
}));
client.send(DeleteRating(user_id, item_id,
# optional parameters:
timestamp=<number>
)
)
client.send(DeleteRating.new(userId, itemId, {
# optional parameters:
:timestamp => <number>
})
)
client.send(new DeleteRating(String userId, String itemId)
.setTimestamp(Date timestamp)
);
<?php
$client->send(new DeleteRating($user_id, $item_id, [
// optional parameters:
'timestamp' => <number>
])
);
?>
client.Send(DeleteRating(string userId, string itemId,
// optional parameters:
timestamp: <DateTime>
)
);
request := client.NewDeleteRating(userId string, itemId string)
// optional parameters:
.SetTimestamp(timestamp time.Time)
_, err := request.Send()
DELETE /{databaseId}/ratings/?userId=<string>
&itemId=<string>
×tamp=<number>
Parameters
ID of your database.
ID of the user who rated the item.
ID of the item which was rated.
Unix timestamp of the rating. If the timestamp
is omitted, then all the ratings with the given userId
and itemId
are deleted.
Responses
Successful operation.
Given userId
or itemId
does not match ^[a-zA-Z0-9_-:@.]+$, or timestamp
is not a real number ≥ 0.
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.
List Item Ratings
Lists all the ratings of an item ever submitted by different users.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.ListItemRatings(itemId))
.then((response) => {
//handle response
})
.catch((error) => {
//handle error
});
result = client.send(ListItemRatings(item_id))
result = client.send(ListItemRatings.new(itemId))
Rating[] result = client.send(new ListItemRatings(String itemId));
<?php
$result = $client->send(new ListItemRatings($item_id));
?>
IEnumerable<Rating> result = client.Send(ListItemRatings(string itemId));
request := client.NewListItemRatings(itemId string)
result, err := request.Send() // result is of the type []bindings.Rating
GET /{databaseId}/items/{itemId}/ratings/
Parameters
ID of your database.
ID of the item whose ratings are to be listed.
Responses
Successful operation.
[
{
"itemId": "item-x",
"userId": "user-a",
"rating": -0.25,
"timestamp": 1348151906.0
},
{
"itemId": "item-x",
"userId": "user-b",
"rating": 0.0,
"timestamp": 1348239363.0
}
]
The itemId
does not match ^[a-zA-Z0-9_-:@.]+$.
Given itemId
not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.
List User Ratings
Lists all the ratings ever submitted by the given user.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.ListUserRatings(userId))
.then((response) => {
//handle response
})
.catch((error) => {
//handle error
});
result = client.send(ListUserRatings(user_id))
result = client.send(ListUserRatings.new(userId))
Rating[] result = client.send(new ListUserRatings(String userId));
<?php
$result = $client->send(new ListUserRatings($user_id));
?>
IEnumerable<Rating> result = client.Send(ListUserRatings(string userId));
request := client.NewListUserRatings(userId string)
result, err := request.Send() // result is of the type []bindings.Rating
GET /{databaseId}/users/{userId}/ratings/
Parameters
ID of your database.
ID of the user whose ratings are to be listed.
Responses
Successful operation.
[
{
"itemId": "item-y",
"userId": "user-a",
"rating": 0.5,
"timestamp": 1348139180.0
},
{
"itemId": "item-x",
"userId": "user-a",
"rating": -0.25,
"timestamp": 1348151906.0
}
]
The userId
does not match ^[a-zA-Z0-9_-:@.]+$.
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.
Cart Additions
Add Cart Addition
Adds a cart addition of the given item made by the given user.
client.send(new recombee.AddCartAddition(userId, itemId, {
// optional parameters:
'timestamp': <string / number>,
'cascadeCreate': <boolean>,
'amount': <number>,
'price': <number>,
'recommId': <string>
}));
client.send(AddCartAddition(userId: String, itemId: String,
// optional parameters:
timestamp: Instant,
cascadeCreate: Boolean,
amount: Double,
price: Double,
recommId: String
)
)
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.AddCartAddition(userId, itemId, {
// optional parameters:
'timestamp': <string / number>,
'cascadeCreate': <boolean>,
'amount': <number>,
'price': <number>,
'recommId': <string>
}));
client.send(AddCartAddition(user_id, item_id,
# optional parameters:
timestamp=<string / number>,
cascade_create=<boolean>,
amount=<number>,
price=<number>,
recomm_id=<string>
)
)
client.send(AddCartAddition.new(userId, itemId, {
# optional parameters:
:timestamp => <string / number>,
:cascade_create => <boolean>,
:amount => <number>,
:price => <number>,
:recomm_id => <string>
})
)
client.send(new AddCartAddition(String userId, String itemId)
.setTimestamp(Date timestamp)
.setCascadeCreate(boolean cascadeCreate)
.setAmount(double amount)
.setPrice(double price)
.setRecommId(String recommId)
);
<?php
$client->send(new AddCartAddition($user_id, $item_id, [
// optional parameters:
'timestamp' => <string / number>,
'cascadeCreate' => <boolean>,
'amount' => <number>,
'price' => <number>,
'recommId' => <string>
])
);
?>
client.Send(AddCartAddition(string userId, string itemId,
// optional parameters:
timestamp: <DateTime>,
cascadeCreate: <bool>,
amount: <double>,
price: <double>,
recommId: <string>
)
);
request := client.NewAddCartAddition(userId string, itemId string)
// optional parameters:
.SetTimestamp(timestamp time.Time)
.SetCascadeCreate(cascadeCreate bool)
.SetAmount(amount float64)
.SetPrice(price float64)
.SetRecommId(recommId string)
_, err := request.Send()
POST /{databaseId}/cartadditions/
Body (application/json):
{
"userId" => <string>,
"itemId" => <string>,
"timestamp" => <string / number>,
"cascadeCreate" => <boolean>,
"amount" => <number>,
"price" => <number>,
"recommId" => <string>
}
Parameters
ID of your database.
User who added the item to the cart
Item added to the cart
UTC timestamp of the cart addition as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
Sets whether the given user/item should be created if not present in the database.
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 of the added item. If amount
is greater than 1, the sum of prices of all the items should be given.
If this cart addition is based on a recommendation request, recommId
is the id of the clicked recommendation.
Responses
Successful operation.
The userId
or itemId
does not match ^[a-zA-Z0-9_-:@.]+$, timestamp
is not a real number ≥ 0.
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.
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 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.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.DeleteCartAddition(userId, itemId, {
// optional parameters:
'timestamp': <number>
}));
client.send(DeleteCartAddition(user_id, item_id,
# optional parameters:
timestamp=<number>
)
)
client.send(DeleteCartAddition.new(userId, itemId, {
# optional parameters:
:timestamp => <number>
})
)
client.send(new DeleteCartAddition(String userId, String itemId)
.setTimestamp(Date timestamp)
);
<?php
$client->send(new DeleteCartAddition($user_id, $item_id, [
// optional parameters:
'timestamp' => <number>
])
);
?>
client.Send(DeleteCartAddition(string userId, string itemId,
// optional parameters:
timestamp: <DateTime>
)
);
request := client.NewDeleteCartAddition(userId string, itemId string)
// optional parameters:
.SetTimestamp(timestamp time.Time)
_, err := request.Send()
DELETE /{databaseId}/cartadditions/?userId=<string>
&itemId=<string>
×tamp=<number>
Parameters
ID of your database.
ID of the user who made the cart addition.
ID of the item which was added to the cart.
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
Successful operation.
Given userId
or itemId
does not match ^[a-zA-Z0-9_-:@.]+$, or timestamp
is not a real number ≥ 0.
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.
List Item Cart Additions
Lists all the ever-made cart additions of the given item.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.ListItemCartAdditions(itemId))
.then((response) => {
//handle response
})
.catch((error) => {
//handle error
});
result = client.send(ListItemCartAdditions(item_id))
result = client.send(ListItemCartAdditions.new(itemId))
CartAddition[] result = client.send(new ListItemCartAdditions(String itemId));
<?php
$result = $client->send(new ListItemCartAdditions($item_id));
?>
IEnumerable<CartAddition> result = client.Send(ListItemCartAdditions(string itemId));
request := client.NewListItemCartAdditions(itemId string)
result, err := request.Send() // result is of the type []bindings.CartAddition
GET /{databaseId}/items/{itemId}/cartadditions/
Parameters
ID of your database.
ID of the item whose cart additions are to be listed.
Responses
Successful operation.
[
{
"itemId": "item-x",
"userId": "user-a",
"timestamp": 1348151906.0
},
{
"itemId": "item-x",
"userId": "user-a",
"timestamp": 1348327154.0
}
]
The itemId
does not match ^[a-zA-Z0-9_-:@.]+$.
Given itemId
not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.
List User Cart Additions
Lists all the cart additions ever made by the given user.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.ListUserCartAdditions(userId))
.then((response) => {
//handle response
})
.catch((error) => {
//handle error
});
result = client.send(ListUserCartAdditions(user_id))
result = client.send(ListUserCartAdditions.new(userId))
CartAddition[] result = client.send(new ListUserCartAdditions(String userId));
<?php
$result = $client->send(new ListUserCartAdditions($user_id));
?>
IEnumerable<CartAddition> result = client.Send(ListUserCartAdditions(string userId));
request := client.NewListUserCartAdditions(userId string)
result, err := request.Send() // result is of the type []bindings.CartAddition
GET /{databaseId}/users/{userId}/cartadditions/
Parameters
ID of your database.
ID of the user whose cart additions are to be listed.
Responses
Successful operation.
[
{
"itemId": "item-x",
"timestamp": 1348151906.0,
"userId": "user-a"
},
{
"itemId": "item-z",
"timestamp": 1348239363.0,
"userId": "user-a"
}
]
The userId
does not match ^[a-zA-Z0-9_-:@.]+$.
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.
Bookmarks
Add Bookmark
Adds a bookmark of the given item made by the given user.
client.send(new recombee.AddBookmark(userId, itemId, {
// optional parameters:
'timestamp': <string / number>,
'cascadeCreate': <boolean>,
'recommId': <string>
}));
client.send(AddBookmark(userId: String, itemId: String,
// optional parameters:
timestamp: Instant,
cascadeCreate: Boolean,
recommId: String
)
)
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.AddBookmark(userId, itemId, {
// optional parameters:
'timestamp': <string / number>,
'cascadeCreate': <boolean>,
'recommId': <string>
}));
client.send(AddBookmark(user_id, item_id,
# optional parameters:
timestamp=<string / number>,
cascade_create=<boolean>,
recomm_id=<string>
)
)
client.send(AddBookmark.new(userId, itemId, {
# optional parameters:
:timestamp => <string / number>,
:cascade_create => <boolean>,
:recomm_id => <string>
})
)
client.send(new AddBookmark(String userId, String itemId)
.setTimestamp(Date timestamp)
.setCascadeCreate(boolean cascadeCreate)
.setRecommId(String recommId)
);
<?php
$client->send(new AddBookmark($user_id, $item_id, [
// optional parameters:
'timestamp' => <string / number>,
'cascadeCreate' => <boolean>,
'recommId' => <string>
])
);
?>
client.Send(AddBookmark(string userId, string itemId,
// optional parameters:
timestamp: <DateTime>,
cascadeCreate: <bool>,
recommId: <string>
)
);
request := client.NewAddBookmark(userId string, itemId string)
// optional parameters:
.SetTimestamp(timestamp time.Time)
.SetCascadeCreate(cascadeCreate bool)
.SetRecommId(recommId string)
_, err := request.Send()
POST /{databaseId}/bookmarks/
Body (application/json):
{
"userId" => <string>,
"itemId" => <string>,
"timestamp" => <string / number>,
"cascadeCreate" => <boolean>,
"recommId" => <string>
}
Parameters
ID of your database.
User who bookmarked the item
Bookmarked item
UTC timestamp of the bookmark as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
Sets whether the given user/item should be created if not present in the database.
If this bookmark is based on a recommendation request, recommId
is the id of the clicked recommendation.
Responses
Successful operation.
The userId
or itemId
does not match ^[a-zA-Z0-9_-:@.]+$, timestamp
is not a real number ≥ 0.
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.
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 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.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.DeleteBookmark(userId, itemId, {
// optional parameters:
'timestamp': <number>
}));
client.send(DeleteBookmark(user_id, item_id,
# optional parameters:
timestamp=<number>
)
)
client.send(DeleteBookmark.new(userId, itemId, {
# optional parameters:
:timestamp => <number>
})
)
client.send(new DeleteBookmark(String userId, String itemId)
.setTimestamp(Date timestamp)
);
<?php
$client->send(new DeleteBookmark($user_id, $item_id, [
// optional parameters:
'timestamp' => <number>
])
);
?>
client.Send(DeleteBookmark(string userId, string itemId,
// optional parameters:
timestamp: <DateTime>
)
);
request := client.NewDeleteBookmark(userId string, itemId string)
// optional parameters:
.SetTimestamp(timestamp time.Time)
_, err := request.Send()
DELETE /{databaseId}/bookmarks/?userId=<string>
&itemId=<string>
×tamp=<number>
Parameters
ID of your database.
ID of the user who made the bookmark.
ID of the item which was bookmarked.
Unix timestamp of the bookmark. If the timestamp
is omitted, then all the bookmarks with the given userId
and itemId
are deleted.
Responses
Successful operation.
Given userId
or itemId
does not match ^[a-zA-Z0-9_-:@.]+$, or timestamp
is not a real number ≥ 0.
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.
List Item Bookmarks
Lists all the ever-made bookmarks of the given item.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.ListItemBookmarks(itemId))
.then((response) => {
//handle response
})
.catch((error) => {
//handle error
});
result = client.send(ListItemBookmarks(item_id))
result = client.send(ListItemBookmarks.new(itemId))
Bookmark[] result = client.send(new ListItemBookmarks(String itemId));
<?php
$result = $client->send(new ListItemBookmarks($item_id));
?>
IEnumerable<Bookmark> result = client.Send(ListItemBookmarks(string itemId));
request := client.NewListItemBookmarks(itemId string)
result, err := request.Send() // result is of the type []bindings.Bookmark
GET /{databaseId}/items/{itemId}/bookmarks/
Parameters
ID of your database.
ID of the item whose bookmarks are to be listed.
Responses
Successful operation.
[
{
"itemId": "item-x",
"userId": "user-a",
"timestamp": 1348151906.0
},
{
"itemId": "item-x",
"userId": "user-a",
"timestamp": 1348327154.0
}
]
The itemId
does not match ^[a-zA-Z0-9_-:@.]+$.
Given itemId
not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.
List User Bookmarks
Lists all the bookmarks ever made by the given user.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.ListUserBookmarks(userId))
.then((response) => {
//handle response
})
.catch((error) => {
//handle error
});
result = client.send(ListUserBookmarks(user_id))
result = client.send(ListUserBookmarks.new(userId))
Bookmark[] result = client.send(new ListUserBookmarks(String userId));
<?php
$result = $client->send(new ListUserBookmarks($user_id));
?>
IEnumerable<Bookmark> result = client.Send(ListUserBookmarks(string userId));
request := client.NewListUserBookmarks(userId string)
result, err := request.Send() // result is of the type []bindings.Bookmark
GET /{databaseId}/users/{userId}/bookmarks/
Parameters
ID of your database.
ID of the user whose bookmarks are to be listed.
Responses
Successful operation.
[
{
"itemId": "item-x",
"timestamp": 1348151906.0,
"userId": "user-a"
},
{
"itemId": "item-z",
"timestamp": 1348239363.0,
"userId": "user-a"
}
]
The userId
does not match ^[a-zA-Z0-9_-:@.]+$.
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
Set View Portion
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.
client.send(new recombee.SetViewPortion(userId, itemId, portion, {
// optional parameters:
'sessionId': <string>,
'timestamp': <string / number>,
'cascadeCreate': <boolean>,
'recommId': <string>,
'additionalData': <Object>
}));
client.send(SetViewPortion(userId: String, itemId: String, portion: Double,
// optional parameters:
sessionId: String,
timestamp: Instant,
cascadeCreate: Boolean,
recommId: String,
additionalData: Map<String, Any>
)
)
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.SetViewPortion(userId, itemId, portion, {
// optional parameters:
'sessionId': <string>,
'timestamp': <string / number>,
'cascadeCreate': <boolean>,
'recommId': <string>,
'additionalData': <Object>
}));
client.send(SetViewPortion(user_id, item_id, portion,
# optional parameters:
session_id=<string>,
timestamp=<string / number>,
cascade_create=<boolean>,
recomm_id=<string>,
additional_data=<dict>
)
)
client.send(SetViewPortion.new(userId, itemId, portion, {
# optional parameters:
:session_id => <string>,
:timestamp => <string / number>,
:cascade_create => <boolean>,
:recomm_id => <string>,
:additional_data => <Hash>
})
)
client.send(new SetViewPortion(String userId, String itemId, double portion)
.setSessionId(String sessionId)
.setTimestamp(Date timestamp)
.setCascadeCreate(boolean cascadeCreate)
.setRecommId(String recommId)
.setAdditionalData(Map<String, Object> additionalData)
);
<?php
$client->send(new SetViewPortion($user_id, $item_id, $portion, [
// optional parameters:
'sessionId' => <string>,
'timestamp' => <string / number>,
'cascadeCreate' => <boolean>,
'recommId' => <string>,
'additionalData' => <array (map)>
])
);
?>
client.Send(SetViewPortion(string userId, string itemId, double portion,
// optional parameters:
sessionId: <string>,
timestamp: <DateTime>,
cascadeCreate: <bool>,
recommId: <string>,
additionalData: <Dictionary<string, object>>
)
);
request := client.NewSetViewPortion(userId string, itemId string, portion float64)
// optional parameters:
.SetSessionId(sessionId string)
.SetTimestamp(timestamp time.Time)
.SetCascadeCreate(cascadeCreate bool)
.SetRecommId(recommId string)
.SetAdditionalData(additionalData map[string]interface{})
_, err := request.Send()
POST /{databaseId}/viewportions/
Body (application/json):
{
"userId" => <string>,
"itemId" => <string>,
"portion" => <number>,
"sessionId" => <string>,
"timestamp" => <string / number>,
"cascadeCreate" => <boolean>,
"recommId" => <string>,
"additionalData" => <Object>
}
Parameters
ID of your database.
User who viewed a portion of the item
Viewed item
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
.
ID of the session in which the user viewed the item. Default is null
(None
, nil
, NULL
etc., depending on the language).
UTC timestamp of the rating as ISO8601-1 pattern or UTC epoch time. The default value is the current time.
Sets whether the given user/item should be created if not present in the database.
If this view portion is based on a recommendation request, recommId
is the id of the clicked recommendation.
A dictionary of additional data for the interaction.
Responses
Successful operation.
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].
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.
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 View Portion
Deletes an existing view portion specified by (userId
, itemId
, sessionId
) from the database.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.DeleteViewPortion(userId, itemId, {
// optional parameters:
'sessionId': <string>
}));
client.send(DeleteViewPortion(user_id, item_id,
# optional parameters:
session_id=<string>
)
)
client.send(DeleteViewPortion.new(userId, itemId, {
# optional parameters:
:session_id => <string>
})
)
client.send(new DeleteViewPortion(String userId, String itemId)
.setSessionId(String sessionId)
);
<?php
$client->send(new DeleteViewPortion($user_id, $item_id, [
// optional parameters:
'sessionId' => <string>
])
);
?>
client.Send(DeleteViewPortion(string userId, string itemId,
// optional parameters:
sessionId: <string>
)
);
request := client.NewDeleteViewPortion(userId string, itemId string)
// optional parameters:
.SetSessionId(sessionId string)
_, err := request.Send()
DELETE /{databaseId}/viewportions/?userId=<string>
&itemId=<string>
&sessionId=<string>
Parameters
ID of your database.
ID of the user who rated the item.
ID of the item which was rated.
Identifier of a session.
Responses
Successful operation.
Given userId
, itemId
or sessionId
does not match ^[a-zA-Z0-9_-:@.]+$.
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.
List Item View Portions
Lists all the view portions of an item ever submitted by different users.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.ListItemViewPortions(itemId))
.then((response) => {
//handle response
})
.catch((error) => {
//handle error
});
result = client.send(ListItemViewPortions(item_id))
result = client.send(ListItemViewPortions.new(itemId))
ViewPortion[] result = client.send(new ListItemViewPortions(String itemId));
<?php
$result = $client->send(new ListItemViewPortions($item_id));
?>
IEnumerable<ViewPortion> result = client.Send(ListItemViewPortions(string itemId));
request := client.NewListItemViewPortions(itemId string)
result, err := request.Send() // result is of the type []bindings.ViewPortion
GET /{databaseId}/items/{itemId}/viewportions/
Parameters
ID of your database.
ID of the item whose view portions are to be listed.
Responses
Successful operation.
[
{
"itemId": "item-x",
"userId": "user-a",
"sessionId": "ABAD1D",
"portion": 0.5,
"timestamp": 1348151906.0
},
{
"itemId": "item-x",
"userId": "user-b",
"sessionId": null,
"portion": 1,
"timestamp": 1348239363.0
}
]
The itemId
does not match ^[a-zA-Z0-9_-:@.]+$.
Given itemId
not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.
List User View Portions
Lists all the view portions ever submitted by the given user.
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.ListUserViewPortions(userId))
.then((response) => {
//handle response
})
.catch((error) => {
//handle error
});
result = client.send(ListUserViewPortions(user_id))
result = client.send(ListUserViewPortions.new(userId))
ViewPortion[] result = client.send(new ListUserViewPortions(String userId));
<?php
$result = $client->send(new ListUserViewPortions($user_id));
?>
IEnumerable<ViewPortion> result = client.Send(ListUserViewPortions(string userId));
request := client.NewListUserViewPortions(userId string)
result, err := request.Send() // result is of the type []bindings.ViewPortion
GET /{databaseId}/users/{userId}/viewportions/
Parameters
ID of your database.
ID of the user whose view portions are to be listed.
Responses
Successful operation.
[
{
"itemId": "item-x",
"userId": "user-a",
"sessionId": "ABAD1D",
"portion": 0.25,
"timestamp": 1348151906.0
},
{
"itemId": "item-y",
"userId": "user-a",
"sessionId": "EWQKOL",
"portion": 0.1,
"timestamp": 1348239363.0
}
]
The userId
does not match ^[a-zA-Z0-9_-:@.]+$.
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.).
Recommend Items to User
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.
client.send(new recombee.RecommendItemsToUser(userId, count, {
// optional parameters:
'scenario': <string>,
'cascadeCreate': <boolean>,
'returnProperties': <boolean>,
'includedProperties': <array>,
'filter': <string>,
'booster': <string>,
'logic': <string / Object>,
'minRelevance': <string>,
'rotationRate': <number>,
'rotationTime': <number>
})).then(function(res) {
// handle response
});
val result = client.sendAsync(RecommendItemsToUser(userId: String, count: Long,
// optional parameters:
scenario: String,
cascadeCreate: Boolean,
returnProperties: Boolean,
includedProperties: List<String>,
filter: String,
booster: String,
logic: Logic,
minRelevance: String,
rotationRate: Double,
rotationTime: Double
)
)
result.onSuccess { response: RecommendationResponse ->
// Handle response
}.onFailure { exception -> // ApiException
// Handle exception
}
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.RecommendItemsToUser(userId, count, {
// optional parameters:
'scenario': <string>,
'cascadeCreate': <boolean>,
'returnProperties': <boolean>,
'includedProperties': <array>,
'filter': <string>,
'booster': <string>,
'logic': <string / Object>,
'minRelevance': <string>,
'rotationRate': <number>,
'rotationTime': <number>
}))
.then((response) => {
//handle response
})
.catch((error) => {
//handle error
});
result = client.send(RecommendItemsToUser(user_id, count,
# optional parameters:
scenario=<string>,
cascade_create=<boolean>,
return_properties=<boolean>,
included_properties=<array>,
filter=<string>,
booster=<string>,
logic=<string / dict>,
min_relevance=<string>,
rotation_rate=<number>,
rotation_time=<number>
)
)
result = client.send(RecommendItemsToUser.new(userId, count, {
# optional parameters:
:scenario => <string>,
:cascade_create => <boolean>,
:return_properties => <boolean>,
:included_properties => <array>,
:filter => <string>,
:booster => <string>,
:logic => <string / Hash>,
:min_relevance => <string>,
:rotation_rate => <number>,
:rotation_time => <number>
})
)
RecommendationResponse result = client.send(new RecommendItemsToUser(String userId, long count)
.setScenario(String scenario)
.setCascadeCreate(boolean cascadeCreate)
.setReturnProperties(boolean returnProperties)
.setIncludedProperties(String[] includedProperties)
.setFilter(String filter)
.setBooster(String booster)
.setLogic(Logic logic)
.setMinRelevance(String minRelevance)
.setRotationRate(double rotationRate)
.setRotationTime(double rotationTime)
);
<?php
$result = $client->send(new RecommendItemsToUser($user_id, $count, [
// optional parameters:
'scenario' => <string>,
'cascadeCreate' => <boolean>,
'returnProperties' => <boolean>,
'includedProperties' => <array>,
'filter' => <string>,
'booster' => <string>,
'logic' => <string / array (map)>,
'minRelevance' => <string>,
'rotationRate' => <number>,
'rotationTime' => <number>
])
);
?>
RecommendationResponse result = client.Send(RecommendItemsToUser(string userId, long count,
// optional parameters:
scenario: <string>,
cascadeCreate: <bool>,
returnProperties: <bool>,
includedProperties: <string[]>,
filter: <string>,
booster: <string>,
logic: <Logic>,
minRelevance: <string>,
rotationRate: <double>,
rotationTime: <double>
)
);
request := client.NewRecommendItemsToUser(userId string, count int)
// optional parameters:
.SetScenario(scenario string)
.SetCascadeCreate(cascadeCreate bool)
.SetReturnProperties(returnProperties bool)
.SetIncludedProperties(includedProperties []string)
.SetFilter(filter string)
.SetBooster(booster string)
.SetLogic(logic bindings.Logic)
.SetMinRelevance(minRelevance string)
.SetRotationRate(rotationRate float64)
.SetRotationTime(rotationTime float64)
result, err := request.Send() // result is of the type bindings.RecommendationResponse
GET /{databaseId}/recomms/users/{userId}/items/?count=<integer>
&scenario=<string>
&cascadeCreate=<boolean>
&returnProperties=<boolean>
&includedProperties=<array>
&filter=<string>
&booster=<string>
&logic=<string / Object>
&minRelevance=<string>
&rotationRate=<number>
&rotationTime=<number>
Parameters
ID of your database.
ID of the user for whom personalized recommendations are to be generated.
Number of items to be recommended (N for the top-N recommendation).
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.
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.
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
}
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
}
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.
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.
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
.
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
.
Responses
Successful operation.
{
"recommId": "3f6ad2f2-a3f1-4ba1-a690-f4f01f76d4eb",
"recomms": [
{
"id": "item-146"
},
{
"id": "item-462"
},
{
"id": "item-463"
}
],
"numberNextRecommsCalls": 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.
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.
Recommend Items to Item
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.
client.send(new recombee.RecommendItemsToItem(itemId, targetUserId, count, {
// optional parameters:
'scenario': <string>,
'cascadeCreate': <boolean>,
'returnProperties': <boolean>,
'includedProperties': <array>,
'filter': <string>,
'booster': <string>,
'logic': <string / Object>,
'minRelevance': <string>,
'rotationRate': <number>,
'rotationTime': <number>
})).then(function(res) {
// handle response
});
val result = client.sendAsync(RecommendItemsToItem(itemId: String, targetUserId: String, count: Long,
// optional parameters:
scenario: String,
cascadeCreate: Boolean,
returnProperties: Boolean,
includedProperties: List<String>,
filter: String,
booster: String,
logic: Logic,
minRelevance: String,
rotationRate: Double,
rotationTime: Double
)
)
result.onSuccess { response: RecommendationResponse ->
// Handle response
}.onFailure { exception -> // ApiException
// Handle exception
}
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.RecommendItemsToItem(itemId, targetUserId, count, {
// optional parameters:
'scenario': <string>,
'cascadeCreate': <boolean>,
'returnProperties': <boolean>,
'includedProperties': <array>,
'filter': <string>,
'booster': <string>,
'logic': <string / Object>,
'minRelevance': <string>,
'rotationRate': <number>,
'rotationTime': <number>
}))
.then((response) => {
//handle response
})
.catch((error) => {
//handle error
});
result = client.send(RecommendItemsToItem(item_id, target_user_id, count,
# optional parameters:
scenario=<string>,
cascade_create=<boolean>,
return_properties=<boolean>,
included_properties=<array>,
filter=<string>,
booster=<string>,
logic=<string / dict>,
min_relevance=<string>,
rotation_rate=<number>,
rotation_time=<number>
)
)
result = client.send(RecommendItemsToItem.new(itemId, targetUserId, count, {
# optional parameters:
:scenario => <string>,
:cascade_create => <boolean>,
:return_properties => <boolean>,
:included_properties => <array>,
:filter => <string>,
:booster => <string>,
:logic => <string / Hash>,
:min_relevance => <string>,
:rotation_rate => <number>,
:rotation_time => <number>
})
)
RecommendationResponse result = client.send(new RecommendItemsToItem(String itemId, String targetUserId, long count)
.setScenario(String scenario)
.setCascadeCreate(boolean cascadeCreate)
.setReturnProperties(boolean returnProperties)
.setIncludedProperties(String[] includedProperties)
.setFilter(String filter)
.setBooster(String booster)
.setLogic(Logic logic)
.setMinRelevance(String minRelevance)
.setRotationRate(double rotationRate)
.setRotationTime(double rotationTime)
);
<?php
$result = $client->send(new RecommendItemsToItem($item_id, $target_user_id, $count, [
// optional parameters:
'scenario' => <string>,
'cascadeCreate' => <boolean>,
'returnProperties' => <boolean>,
'includedProperties' => <array>,
'filter' => <string>,
'booster' => <string>,
'logic' => <string / array (map)>,
'minRelevance' => <string>,
'rotationRate' => <number>,
'rotationTime' => <number>
])
);
?>
RecommendationResponse result = client.Send(RecommendItemsToItem(string itemId, string targetUserId, long count,
// optional parameters:
scenario: <string>,
cascadeCreate: <bool>,
returnProperties: <bool>,
includedProperties: <string[]>,
filter: <string>,
booster: <string>,
logic: <Logic>,
minRelevance: <string>,
rotationRate: <double>,
rotationTime: <double>
)
);
request := client.NewRecommendItemsToItem(itemId string, targetUserId string, count int)
// optional parameters:
.SetScenario(scenario string)
.SetCascadeCreate(cascadeCreate bool)
.SetReturnProperties(returnProperties bool)
.SetIncludedProperties(includedProperties []string)
.SetFilter(filter string)
.SetBooster(booster string)
.SetLogic(logic bindings.Logic)
.SetMinRelevance(minRelevance string)
.SetRotationRate(rotationRate float64)
.SetRotationTime(rotationTime float64)
result, err := request.Send() // result is of the type bindings.RecommendationResponse
GET /{databaseId}/recomms/items/{itemId}/items/?targetUserId=<string>
&count=<integer>
&scenario=<string>
&cascadeCreate=<boolean>
&returnProperties=<boolean>
&includedProperties=<array>
&filter=<string>
&booster=<string>
&logic=<string / Object>
&minRelevance=<string>
&rotationRate=<number>
&rotationTime=<number>
Parameters
ID of your database.
ID of the item for which the recommendations are to be generated.
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.
Number of items to be recommended (N for the top-N recommendation).
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.
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.
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
}