---
title: API Reference
language_tabs:
- http
toc_footers:
- bitREC 2018
search: true
---
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
```http
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}]}, ...]
```
```shell
# 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://:@//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
```http
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},...]
```
```shell
# 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://:@//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
```http
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"}, ...]
```
```shell
# 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://:@//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
```http
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
```
```shell
# 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://:@//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
```http
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
```
```php
```
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://:@//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
```http
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
```
```php
```
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://:@//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
```http
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
```
```php
```
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://:@//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
```http
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://:@//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
```http
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://:@//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