NAV
http


Thank you very much 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.

Cart Items

POST /client-services/data_upload/carts HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/json


[{"customerId" : "14", "buId" : "online1","orderTimestamp": "2013-07-10T12:20:00.000", "bonusCode": "ASD4221", "discount": 5.0,
  "items": [{"itemId":"Samsung SIII", "price":500.99, "quantity": 2, "discount": 5.0},
            {"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", "buId" : "online1","orderTimestamp": "2013-07-10T12:20:00.000", "bonusCode": "ASD4221", "discount": 5.0,
  "items": [{"itemId":"Samsung SIII", "price":500.99, "quantity": 2, "discount": 5.0},
            {"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

UploadCart JSON format:

{"customerId" : "<customer id>",
 "buId" : "<business unit>",
 "orderTimestamp": "<order timestamp, format yyyy-MM-ddTHH:mm:ss.ms>", "bonusCode": <cart bonus code>, "discount": <discount>,
 "items": [{"itemId":"<item id>", "price":4.45, "quantity": 2, "discount": <discount>}, ...]
 }

This function is used to regularly upload cart information. Usually it is enough to upload carts once in 24 hours.

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 Yes String ID of customer
orderTimestamp Yes String (Format for date is “yyyy-MM-ddTHH:mm:ss.ms”) Time of cart purchase
buId No String Business unit, where cart was sold
bonusCode No String bonus code for a cart
discount No Float discount on all items in this cart, in money value (not percentage value). Not required, it’s possible to assign discount to whole cart, or set discount for separate cart items.
items Yes List of UploadCartItem objects List of cart items

UploadCartItem object

Field Required Type Description
itemId Yes String ID of item
price Yes Float Price of item
quantity No Integer items’ quantity in the cart
discount No Float discount for this item, in money value (not percentage value).

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, "category1Id": "1544|489|1444", "category2Id": "789|4555|4788",
  "name": "Nikon D3200", "description" : "Nikon D3200 Digital SLR Camera With AF-S DX NIKKOR 18-55mm",
  "deliveryTime": 1, "discount": 0.0, "buIds": ["shop L1", "shop L2"], "active": true},...]
# Curl command from shell:
curl -v -H "Content-Type: application/json" -X POST -d '[{"itemId" : "456821", "price": 12.4, "category1Id": "1544|489|1444", "category2Id": "789|4555|4788",
  "name": "Nikon D3200", "description" : "Nikon D3200 Digital SLR Camera With AF-S DX NIKKOR 18-55mm",
  "deliveryTime": 1, "discount": 0.0, "buIds": ["shop L1", "shop L2"], "active": true}]' http://user:pass@recs.bitrec.com/client-services/data_upload/items

UploadCart JSON format:

{"itemId" : "<item id>",
 "name" : "<item name>",
 "description" : "<item description>",
 "price" : "<price>",
 "category1Id" : "<category hierarchy 1, category IDs separated by | >",
 "category2Id" : "<category hierarchy 2, category IDs separated by | >",
 "category3Id" : "<category hierarchy 3, category IDs separated by | >",
 "category4Id" : "<category hierarchy 4, category IDs separated by | >",
 "category5Id" : "<category hierarchy 5, category IDs separated by | >",
 "category6Id" : "<category hierarchy 6, category IDs separated by | >",
 "deliveryTime": "<time in days for delivery>",
 "discount": "<discount>",
 "buIds": ["<list of business units>"],
 "active": "<boolean value, defines if item is active right now>"
 }

This function is used to regularly upload or update catalog information. Usually it is enough to upload/update catalog once in 24 hours.

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
price Yes Float Price of item
category1Id Yes String Category hierarchy to item. Each category is separated by column symbol, first member is main category ID and goes to items category ID.
category2Id No String Category hierarchy to item. Each category is separated by column symbol, first member is main category ID and goes to items category ID.
category3Id No String Category hierarchy to item. Each category is separated by column symbol, first member is main category ID and goes to items category ID.
category4Id No String Category hierarchy to item. Each category is separated by column symbol, first member is main category ID and goes to items category ID.
category5Id No String Category hierarchy to item. Each category is separated by column symbol, first member is main category ID and goes to items category ID.
category6Id No String Category hierarchy to item. Each category is separated by column symbol, first member is main category ID and goes to items category ID.
name Yes 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)
buIds No List of Strings List of business units where this item belongs
active No Boolean Defines if item is active right now (can be sold, or at least should be included in recommendations)

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

UploadCart JSON format:

{"customerId" : "<customer id>",
 "gender": "<cusotmer gender: 'male' or 'female'>",
 "birth": "<cusotmers birth date>",
 "location":"<customers location>"
 }

This function is used to regularly upload or update customer information. Usually it is enough to upload/update customers once in 24 hours.

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

Business Unit

POST /client-services/data_upload/business_units HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/json


[{"buId":"online", "itemId":"1455522", "active":true},
 {"buId":"offline", "itemId":"1455522", "active":true}, ...]
# Curl command from shell:
curl -v -H "Content-Type: application/json" -X POST -d '[{"buId":"online", "itemId":"1455522", "active":true},
 {"buId":"offline", "itemId":"1455522", "active":true}]' http://user:pass@recs.bitrec.com/client-services/data_upload/business_units

Business unit JSON format:

{"buId":"<business unit id>",
 "itemId":"<itme id>",
 "active":true
}

This function is used to regularly upload or update Business Unit information. Concept of Business Units should be used in several cases:

HTTP Request

https://<usr>:<pssw>@<HOST>/<c_path>/data_upload/business_units

Body Parameters

Parameter Required Description
BU obj. list Yes List of Business unit objects in JSON format

BU object

Field Required Type Description
itemId Yes String ID of item
buId Yes String ID of business unit
active Yes Boolean Defines if item in business unit is active (1 - True, 0 - False)

Response

Code Description
204 Request was successfully completed
400 Bad request – mostly due wrong sending parameters structure
500 Internal server error

Business Units

This section explains how to properly manage item availability on different physical or logical business units. Concept of business units allows retailer to divide catalog items among different physical or logical locations and manage item availability among them. It is also used in order to mark items that are out of stock in cases of single location.

Activate business unit

POST /client-services/business_units/online/15455/activate HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/json

Function is used to activate an item in the given Business Unit.

HTTP Request

https://<usr>:<pssw>@<HOST>/<c_path>/business_units/{buId}/{itemId}/activate

Request Parameters

Parameter Required Description
buId Yes Name of business unit
itemId Yes item id value

Response

Code Description
204 Request was successfully completed
400 Bad request – mostly due wrong sending parameters structure
404 Resource by specified parameters was not found
500 Internal server error

Deactivate business unit

POST /client-services/business_units/online/15455/deactivate HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/json

Function is used to deactivate an item in the given Business Unit.

HTTP Request

https://<usr>:<pssw>@<HOST>/<c_path>/business_units/{buId}/{itemId}/deactivate

Request Parameters

Parameter Required Description
buId Yes Name of business unit
itemId Yes item id value

Response

Code Description
204 Request was successfully completed
400 Bad request – mostly due wrong sending parameters structure
404 Resource by specified parameters was not found
500 Internal server error

Business unit items

POST /client-services/business_units/online/items HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/json


Response:

["14566", "484551", "541222", ...]

Function is used to get a list of items in the given business unit.

HTTP Request

https://<usr>:<pssw>@<HOST>/<c_path>/business_units/{buId}/items

Request Parameters

Parameter Required Description
buId Yes Business unit name

Response

Code Description
200 Request was successfully completed. Returns content of string list in JSON format. Each of those string represents item Id in that business unit.
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.

Top (home page )

POST /client-services/recs/items HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/x-www-form-urlencoded

customer_id=8000160&k=4&bu_id=online&cart_tems=12;13;14
# Curl command from shell:
curl -v -d "customer_id=8000160&k=4&bu_id=online&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.

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).
bu_id No String Business unit id. If this value is not send, then default business unit id will be taken.
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)
ref No String Reference type. Used if item page was opened from other sources, like e-mail or ad form. But this applies only for those cases if items in other sources was taken from our recommendations.
sent_date No String Date when our recommendations was sent to other sources, like e-mail or ad form (for example when e-mail was sent).

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

Personal Basket

POST /client-services/recs/personal_basket HTTP/1.1
Host: recs.bitrec.com
Content-Type: application/x-www-form-urlencoded

customer_id=8000160&k=4&bu_id=online&cart_tems=12;13;14
# Curl command from shell:
curl -v -d "customer_id=8000160&k=4&bu_id=online&cart_tems=12;13;14" http://user:pass@recs.bitrec.com/client-services/recs/personal_basket

This function is used to request recommendations for customer personalized item list. Those recommendations are based on customer orders, viewing history and predicts what customer wants to by at this session.

HTTP Request

POST https://<usr>:<pssw>@<HOST>/<c_path>/recs/personal_basket

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).
bu_id No String Business unit id. If this value is not send, then default business unit id will be taken.
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)
ref No String Reference type. Used if item page was opened from other sources, like e-mail or ad form. But this applies only for those cases if items in other sources was taken from our recommendations.
sent_date No String Date when our recommendations was sent to other sources, like e-mail or ad form (for example when e-mail was sent).

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

Up–Sell

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&bu_id=online&cart_tems=12;13;14

Up–Sell. 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’.

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).
bu_id No String Business unit id. If this value is not send, then default business unit id will be taken.
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)
ref No String Reference type. Used if item page was opened from other sources, like e-mail or ad form. But this applies only for those cases if items in other sources was taken from our recommendations.
sent_date No String Date when our recommendations was sent to other sources, like e-mail or ad form (for example when e-mail was sent).

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&bu_id=online&cart_tems=12;13;14

Cross-Sell 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’.

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).
bu_id No String Business unit id. If this value is not send, then default business unit id will be taken.
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)
ref No String Reference type. Used if item page was opened from other sources, like e-mail or ad form. But this applies only for those cases if items in other sources was taken from our recommendations.
sent_date No String Date when our recommendations was sent to other sources, like e-mail or ad form (for example when e-mail was sent).

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&bu_id=online&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’.

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).
bu_id No String Business unit id. If this value is not send, then default business unit id will be taken.
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)
ref No String Reference type. Used if item page was opened from other sources, like e-mail or ad form. But this applies only for those cases if items in other sources was taken from our recommendations.
sent_date No String Date when our recommendations was sent to other sources, like e-mail or ad form (for example when e-mail was sent).

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&bu_id=online&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’.

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).
bu_id No String Business unit id. If this value is not send, then default business unit id will be taken.
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)
ref No String Reference type. Used if item page was opened from other sources, like e-mail or ad form. But this applies only for those cases if items in other sources was taken from our recommendations.
sent_date No String Date when our recommendations was sent to other sources, like e-mail or ad form (for example when e-mail was sent).

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