Recombee API Client
A Node.js client (SDK) for easy use of the Recombee recommendation API.
If you don't have an account at Recombee yet, you can create a free account here.
Documentation of the API can be found at docs.recombee.com.
For client side (browser, mobile apps ...) .js library please see this repository.
Installation
npm i recombee-api-client --save
Promises / callbacks
The SDK supports both Promises and callbacks, so you can choose the way which suits your coding style and conventions of your project:
client.send(new AddDetailView)
.then((response) => {
})
.catch((error) => {
});
client.send(new AddDetailView,
(error, response) => {
}
);
Examples
Basic example
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
var client = new recombee.ApiClient('--my-database-id--', '--db-private-token--', {region: 'us-west'});
const NUM = 100;
var userIds = Array.apply(0, Array(NUM)).map((_, i) => {
return `user-${i}`;
});
var itemIds = Array.apply(0, Array(NUM)).map((_, i) => {
return `item-${i}`;
});
const PROBABILITY_PURCHASED = 0.1;
var purchases = [];
userIds.forEach((userId) => {
var purchased = itemIds.filter(() => Math.random() < PROBABILITY_PURCHASED);
purchased.forEach((itemId) => {
purchases.push(new rqs.AddPurchase(userId, itemId, {'cascadeCreate': true}))
});
});
client.send(new rqs.Batch(purchases))
.then(() => {
return client.send(new rqs.RecommendItemsToUser('user-25', 5));
})
.then((response) => {
console.log("Recommended items for user-25: %j", response.recomms);
return client.send(new rqs.RecommendNextItems(response.recommId, 3));
})
.then((response) => {
console.log("Next recommended items for user-25: %j", response.recomms);
})
.catch((error) => {
console.error(error);
});
Using property values
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
var client = new recombee.ApiClient('--my-database-id--', '--db-private-token--', {region: 'ap-se'});
const NUM = 100;
client.send(new rqs.Batch([
new rqs.AddItemProperty('price', 'double'),
new rqs.AddItemProperty('num-cores', 'int'),
new rqs.AddItemProperty('description', 'string'),
new rqs.AddItemProperty('time', 'timestamp'),
new rqs.AddItemProperty('image', 'image')
]))
.then((responses) => {
var requests = Array.apply(0, Array(NUM)).map((_, i) => {
return new rqs.SetItemValues(
`computer-${i}`,
{
'price': 600 + 400 * Math.random(),
'num-cores': Math.floor(Math.random() * 8) + 1,
'description': 'Great computer',
'time': new Date().toISOString(),
'image': `http://examplesite.com/products/computer-${i}.jpg`
},
{
'cascadeCreate': true
}
);
});
return client.send(new rqs.Batch(requests));
})
.then((responses) => {
var userIds = Array.apply(0, Array(NUM)).map((_, i) => {
return `user-${i}`;
});
var itemIds = Array.apply(0, Array(NUM)).map((_, i) => {
return `computer-${i}`;
});
const PROBABILITY_PURCHASED = 0.1;
var purchases = [];
userIds.forEach((userId) => {
var purchased = itemIds.filter(() => Math.random() < PROBABILITY_PURCHASED);
purchased.forEach((itemId) => {
purchases.push(new rqs.AddPurchase(userId, itemId, {'cascadeCreate': true}))
});
});
return client.send(new rqs.Batch(purchases));
})
.then((responses) => {
return client.send(new rqs.RecommendItemsToItem('computer-6', 'user-42', 5,
{'filter': "'num-cores' >= 3"}
));
})
.then((recommended) => {
console.log("Recommended items with at least 3 processor cores: %j", recommended);
return client.send(new rqs.RecommendItemsToItem('computer-6', 'user-42', 5,
{'filter': " 'price' > context_item[\"price\"] ",
'returnProperties': true}
));
})
.then((recommended) => {
console.log("Recommended up-sell items: %j", recommended)
return client.send(new rqs.RecommendItemsToItem('computer-6', 'user-42', 5,
{'scenario': "product_detail"}
));
})
.then((recommended) => {
return client.send(new rqs.SearchItems('user-42', 'computers', 5, {'scenario': "search_top"}));
})
.then((matched) => {
console.log("Matched items: %j", matched)
})
.catch((error) => {
console.error(error);
});
Errors handling
Various errors can occur while processing request, for example because of adding an already existing item or submitting interaction of nonexistent user without cascadeCreate set to true. These errors lead to the ResponseError, which is thrown or put to callback function by the send method of the client (depending on using Promises or callbacks). Another reason for errorneous request is a timeout. ApiError is the base class of both ResponseError and TimeoutError.
We are doing our best to provide the fastest and most reliable service, but production-level applications must implement a fallback solution since problems can always happen. The fallback might be, for example, showing the most popular items from the current category, or not displaying recommendations at all.