Thank you for choosing bitREC as your recommender system provider.
This is bitREC’s API documentation. Please read this document carefully in order to make the integration process smooth and swift.
In case you would need support or more information, do not hesitate to contact our helpful technicians: support@bitrec.com.
Data Upload
This section explains how to properly manage historical data exchange between your systems and bitREC.
Data upload functions are used for regular data (carts, catalog, customers) uploads/updates to bitREC recommender system.
Orders
POST /client-services/data_upload/carts HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/json
[{"customerId" : "14", "orderTimestamp": "2013-07-10T12:20:00.000",
"items": [{"itemId":"Samsung SIII", "price":500.99, "quantity": 2},
{"itemId":"Samsung cover flip", "price":45.50, "quantity": 1},
{"itemId":"auto charger", "price":14.00, "quantity": 1}]}, ...]
# Curl command from shell:
curl -v -H "Content-Type: application/json" -X POST -d '[{"customerId" : "14", "orderTimestamp": "2013-07-10T12:20:00.000",
"items": [{"itemId":"Samsung SIII", "price":500.99, "quantity": 2},
{"itemId":"Samsung cover flip", "price":45.50, "quantity": 1},
{"itemId":"auto charger", "price":14.00, "quantity": 1}]}]' http://user:pass@recs.bitrec.com/client-services/data_upload/carts
This function is used to regularly upload order information. Usually it is enough to upload orders once per 24 hours.
- If orderTimestamp is missing, current time will be used
- If any additional information such as sales channel or internal order id is available it may be added to the UploadCart object described below
HTTP Request
POST https://<usr>:<pssw>@<HOST>/<c_path>/data_upload/carts
Body Parameters
| Parameter |
Required |
Description |
| UploadCart obj. list |
Yes |
List of Cart item objects in JSON format |
UploadCart object
| Field |
Required |
Type |
Description |
| customerId |
No |
String |
ID of customer |
| orderTimestamp |
No |
String (Format for date is “yyyy-MM-ddTHH:mm:ss.ms”) |
Time of cart purchase |
| items |
Yes |
List of UploadCartItem objects |
List of order items |
UploadCartItem object
| Field |
Required |
Type |
Description |
| itemId |
Yes |
String |
ID of item |
| price |
No |
Float |
Price of item |
| quantity |
No |
Integer |
items’ quantity in the cart |
Response
| Code |
Description |
| 204 |
Request was successfully completed |
| 400 |
Bad request – mostly due wrong sending parameters structure |
| 500 |
Internal server error |
Items
POST /client-services/data_upload/items HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/json
[{"itemId" : "456821", "price": 12.4, "categories": ["1544","489","1444"],
"name": "Nikon D3200", "description" : "Nikon D3200 Digital SLR Camera With AF-S DX NIKKOR 18-55mm",
"deliveryTime": 1, "discount": 0.0, "active": true},...]
# Curl command from shell:
curl -v -H "Content-Type: application/json" -X POST -d '[{"itemId" : "456821", "price": 12.4, "categories": ["1544","489","1444"],
"name": "Nikon D3200", "description" : "Nikon D3200 Digital SLR Camera With AF-S DX NIKKOR 18-55mm",
"deliveryTime": 1, "discount": 0.0, "active": true}]' http://user:pass@recs.bitrec.com/client-services/data_upload/items
This function is used to regularly upload or update catalog information. Usually it is enough to upload/update catalog once in 24 hours.
- The only required parameter is itemId. If not provided 400 will be returned
- Repeatedly posting data with the same itemId will update the entry in bitREC system
- If you uploaded carts data with unknown items in bitREC system, you can update item information using this REST function call
- If any additional information such as item dimensions, size or any other is available it may be added to the Item object described below
HTTP Request
POST https://<usr>:<pssw>@<HOST>/<c_path>/data_upload/items
Body Parameters
| Parameter |
Required |
Description |
| Item obj. list |
Yes |
List of Item objects in JSON format |
Item object
| Field |
Required |
Type |
Description |
| itemId |
Yes |
String |
ID of item |
| active |
No |
Boolean |
Defines if item is active right now (can be sold, or at least should be included in recommendations) |
| price |
No |
Float |
Price of item |
| categories |
No |
String Array |
List of categories item belongs to |
| name |
No |
String |
Name of item |
| description |
No |
String |
Description of item |
| deliveryTime |
No |
Integer |
Items’ delivery time in days |
| discount |
No |
Float |
Discount on this item (value in percentage) |
Response
| Code |
Description |
| 204 |
Request was successfully completed |
| 400 |
Bad request – mostly due wrong sending parameters structure |
| 500 |
Internal server error |
Customers
POST /client-services/data_upload/customers HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/json
[{"customerId" : "154", "gender": "male", "birth": "1982-02-20", "location":"Vilnius"}, ...]
# Curl command from shell:
curl -v -H "Content-Type: application/json" -X POST -d '[{"customerId" : "154", "gender": "male", "birth": "1982-02-20", "location":"Vilnius"},
{"customerId" : "155", "gender": "female", "birth": "1985-04-12", "location":"Klaipeda"}]' http://user:pass@recs.bitrec.com/client-services/data_upload/customers
This function is used to regularly upload or update customer information. Usually it is enough to upload/update customers once in 24 hours.
- Required: customerId or 400 will be returned.
- Repeatedly posting data with the same itemId will update the entry in bitREC system
- If you uploaded orders with unknown customers in bitREC system, you can update customer information using this REST function call.
- If any additional information such as company name or ID is available it may be added to the Customer object described below
HTTP Request
https://<usr>:<pssw>@<HOST>/<c_path>/data_upload/customers
Body Parameters
| Parameter |
Required |
Description |
| Customer obj. list |
Yes |
List of Customer objects in JSON format |
Customer object
| Field |
Required |
Type |
Description |
| customerId |
Yes |
String |
ID of customer |
| gender |
No |
String |
Customers gender |
| birth |
No |
String |
Birth of customer (Format for date is “yyyy-MM-dd”) |
| location |
No |
String |
Customers’ location |
Response
| Code |
Description |
| 204 |
Request was successfully completed |
| 400 |
Bad request – mostly due wrong sending parameters structure |
| 500 |
Internal server error |
Recommendations
This section explains how to receive product recommendations in different pages of your webstore.
Personalized Home
POST /client-services/recs/items HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/x-www-form-urlencoded
customer_id=8000160&k=4&cart_tems=12;13;14
# Curl command from shell:
curl -v -d "customer_id=8000160&k=4&cart_tems=12;13;14" http://user:pass@recs.bitrec.com/client-services/recs/items
This function is used to request recommendations for the home page.
- While parameters customer_id and visitor_id are optional, but there is a rule, that at least one of them must be provided.
HTTP Request
POST https://<usr>:<pssw>@<HOST>/<c_path>/recs/items
Body Parameters
| Parameter |
Required |
Type |
Description |
| k |
Yes |
Integer |
number of recommendations to retrieve |
| customer_id |
No |
String |
Customer id. |
| visitor_id |
No |
String |
Visitor id. If Customer is not known, then visitor id should be send. This id points to client browser (for example the logic for visitor id could be taken from cookie). |
| cart_items |
No |
String |
List of cart item IDs separated by ’;’ (for example 12;45;94;14) |
| user_agent |
No |
String |
a string representing the customer’s browser (for example Mozilla 5.0(Windows NT 5.1 rv 1.0) Gecko 20100101 Firefox 31.0) |
| user_ip |
No |
String |
a string with the customer’s IP address (for example 74.125.230.36) |
Response
| Code |
Description |
| 200 |
Request was successfully completed. Returns content of item id list in JSON format. Example: [“45812”, “45212”] |
| 400 |
Bad request – mostly due wrong sending parameters structure |
| 500 |
Internal server error |
Similar Products
POST /client-services/recs/items/viewed/458544 HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/x-www-form-urlencoded
customer_id=8000160&k=4&cart_tems=12;13;14
This function is used to request up-sell recommendations for the item page. Up-Sell items are usually items similar to the current item. A typical label for such recommendations is ‘People who viewed this item also viewed’.
- While parameters customer_id and visitor_id are optional, but there is a rule, that at least one of them must be provided.
HTTP Request
POST https://<usr>:<pssw>@<HOST>/<c_path>/recs/items/viewed/{item_id}
Request Parameters
| Parameter |
Required |
Description |
| item_id |
Yes |
Id of item, which page customer is viewing. |
Body Parameters
| Parameter |
Required |
Type |
Description |
| k |
Yes |
Integer |
number of recommendations to retrieve |
| customer_id |
No |
String |
Customer id. |
| visitor_id |
No |
String |
Visitor id. If Customer is not known, then visitor id should be send. This id points to client browser (for example the logic for visitor id could be taken from cookie). |
| cart_items |
No |
String |
List of cart item IDs separated by ’;’ (for example 12;45;94;14) |
| user_agent |
No |
String |
a string representing the customer’s browser (for example Mozilla 5.0(Windows NT 5.1 rv 1.0) Gecko 20100101 Firefox 31.0) |
| user_ip |
No |
String |
a string with the customer’s IP address (for example 74.125.230.36) |
Response
| Code |
Description |
| 200 |
Request was successfully completed. Returns content of item id list in JSON format. Example: [“45812”, “45212”, “654323”, “7865146”] |
| 400 |
Bad request – mostly due wrong sending parameters structure |
| 500 |
Internal server error |
Cross-Sell
POST /client-services/recs/items/bought/458544 HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/x-www-form-urlencoded
customer_id=8000160&k=4&cart_tems=12;13;14
This function is used to request cross-sell recommendations for the item page. Cross-Sell items are usually complimentary items to the current item. A typical label for such recommendations is 'People who bought this item also bought’.
- While parameters customer_id and visitor_id are optional, but there is a rule, that at least one of them must be provided.
HTTP Request
POST https://<usr>:<pssw>@<HOST>/<c_path>/recs/items/bought/{item_id}
Request Parameters
| Parameter |
Required |
Description |
| item_id |
Yes |
Id of item, which page customer is viewing. |
Body Parameters
| Parameter |
Required |
Type |
Description |
| k |
Yes |
Integer |
number of recommendations to retrieve |
| customer_id |
No |
String |
Customer id. |
| visitor_id |
No |
String |
Visitor id. If Customer is not known, then visitor id should be send. This id points to client browser (for example the logic for visitor id could be taken from cookie). |
| cart_items |
No |
String |
List of cart item IDs separated by ’;’ (for example 12;45;94;14) |
| user_agent |
No |
String |
a string representing the customer’s browser (for example Mozilla 5.0(Windows NT 5.1 rv 1.0) Gecko 20100101 Firefox 31.0) |
| user_ip |
No |
String |
a string with the customer’s IP address (for example 74.125.230.36) |
Response
| Code |
Description |
| 200 |
Request was successfully completed. Returns content of item id list in JSON format. Example: [“45812”, “45212”, “654323”, “7865146”] |
| 400 |
Bad request – mostly due wrong sending parameters structure |
| 500 |
Internal server error |
Frequently Bought Together (FBT)/Product Bundles
POST /client-services/recs/items/bought_together/458544 HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/x-www-form-urlencoded
customer_id=8000160&cart_tems=12;13;14
This function is used to request Frequently Bought Together recommendations for the item page. FBT items are usually complimentary items to the current item and are displayed in a bundled way such as Item1+Item2+Item3=Price and may be added to the basket with a single click. A typical label for such recommendations is 'Frequently Bought Together’.
- While parameters customer_id and visitor_id are optional, but there is a rule, that at least one of them must be provided
- If no strong correlations between products are found the request result is empty list
- The number of items returned is chosen by bitREC models. Usualy it is either one, two three items
HTTP Request
POST https://<usr>:<pssw>@<HOST>/<c_path>/recs/items/bought_together/{item_id}
Request Parameters
| Parameter |
Required |
Description |
| item_id |
Yes |
Id of item, which page customer is viewing. |
Body Parameters
| Parameter |
Required |
Type |
Description |
| customer_id |
No |
String |
Customer id. |
| visitor_id |
No |
String |
Visitor id. If Customer is not known, then visitor id should be send. This id points to client browser (for example the logic for visitor id could be taken from cookie). |
| cart_items |
No |
String |
List of cart item IDs separated by ’;’ (for example 12;45;94;14) |
| user_agent |
No |
String |
a string representing the customer’s browser (for example Mozilla 5.0(Windows NT 5.1 rv 1.0) Gecko 20100101 Firefox 31.0) |
| user_ip |
No |
String |
a string with the customer’s IP address (for example 74.125.230.36) |
Response
| Code |
Description |
| 200 |
Request was successfully completed. Returns content of item id list in JSON format. Example: [“45812”, “45212”, “654323”, “7865146”] |
| 400 |
Bad request – mostly due wrong sending parameters structure |
| 500 |
Internal server error |
Category
POST /client-services/recs/items/category/3/Cat-46587 HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/x-www-form-urlencoded
customer_id=8000160&k=4&cart_tems=12;13;14
This function is used to request recommendations in category page. A typical label for such recommendations is 'You might be interested in’.
- While parameters customer_id and visitor_id are optional, but there is a rule, that at least one of them must be provided.
HTTP Request
POST https://<usr>:<pssw>@<HOST>/<c_path>/recs/items/category/{cat_level}/{cat_id}
Request Parameters
| Parameter |
Required |
Description |
| cat_level |
Yes |
Category level in hierarchical categories order. |
| cat_id |
Yes |
Category id. |
Body Parameters
| Parameter |
Required |
Type |
Description |
| k |
Yes |
Integer |
number of recommendations to retrieve |
| customer_id |
No |
String |
Customer id. |
| visitor_id |
No |
String |
Visitor id. If Customer is not known, then visitor id should be send. This id points to client browser (for example the logic for visitor id could be taken from cookie). |
| cart_items |
No |
String |
List of cart item IDs separated by ’;’ (for example 12;45;94;14) |
| user_agent |
No |
String |
a string representing the customer’s browser (for example Mozilla 5.0(Windows NT 5.1 rv 1.0) Gecko 20100101 Firefox 31.0) |
| user_ip |
No |
String |
a string with the customer’s IP address (for example 74.125.230.36) |
Response
| Code |
Description |
| 200 |
Request was successfully completed. Returns content of item id list in JSON format. Example: [“45812”, “45212”, “654323”, “7865146”] |
| 400 |
Bad request – mostly due wrong sending parameters structure |
| 500 |
Internal server error |
Checkout page
POST /client-services/recs/items/checkout HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/x-www-form-urlencoded
customer_id=8000160&k=4&cart_tems=12;13;14
This function is used to request recommendations in checkout page. A typical label for such recommendations is 'People who bought this also bought’.
- While parameters customer_id and visitor_id are optional, but there is a rule, that at least one of them must be provided.
HTTP Request
POST https://<usr>:<pssw>@<HOST>/<c_path>/recs/items/checkout
Body Parameters
| Parameter |
Required |
Type |
Description |
| k |
Yes |
Integer |
number of recommendations to retrieve |
| customer_id |
No |
String |
Customer id. |
| visitor_id |
No |
String |
Visitor id. If Customer is not known, then visitor id should be send. This id points to client browser (for example the logic for visitor id could be taken from cookie). |
| cart_items |
No |
String |
List of cart item IDs separated by ’;’ (for example 12;45;94;14) |
| user_agent |
No |
String |
a string representing the customer’s browser (for example Mozilla 5.0(Windows NT 5.1 rv 1.0) Gecko 20100101 Firefox 31.0) |
| user_ip |
No |
String |
a string with the customer’s IP address (for example 74.125.230.36) |
Response
| Code |
Description |
| 200 |
Request was successfully completed. Returns content of item id list in JSON format. Example: [“45812”, “45212”, “654323”, “7865146”] |
| 400 |
Bad request – mostly due wrong sending parameters structure |
| 500 |
Internal server error |
