ExpertRec API Documentation

Introduction

ExpertRec APIs facilitates the collection of user behavior from website/mobile app. This user behavior is used to enhance search and make recommendations for the user.

Merchant Id

Merchant_Id is a unique identifier for a shop/market place. Merchant_Id is generated during the signup/activation process. A sample merchant_Id would look like – 557f21f5ecd2312d2de3782d3c13c5

MerchantGroups

MerchantGroups is a way multiple merchant_Ids could be considered a single billing entity. This affects only billing and the data of different merchant_ids are indeed kept separate. Given a Merchant_Id, you can create more subgroup elements by adding “-” and any number to digits.

557f21f5ecd2312d2de3782d3c13c5-1
557f21f5ecd2312d2de3782d3c13c5-2

etc would all be considered
557f21f5ecd2312d2de3782d3c13c5
for billing considerations.

User

User is any unique user of the shop.
UserId typically is his device ID, cookie or any reasonable way of assigning a unique number to the user. This has to be unique (with high probability) within the given shop.

id

id is a unique Item/thing that is to be discovered by the user. e.g. in e-commerce SKU defines an id

Event

Event is any interaction between the user and item.

All data collection happens over https and is secure.

Item Data feed

Meta data is used to attach data about the item, either from the end devices or from the backend. This meta data will be returned in the results. Any data that are to be used in scoring or filtering of search and recommendations should also be present in this. E.g. profit margin for scoring and item categories for filtering has to be attached.

Inserting/Updating complete data

meta data is sent as POST request. Send the array of products as below. Content type should be set to application/json. Primary key should be id. Any old data for the same id will be overwritteni. Include any number of products in the array.

curl https://feed.expertrec.com/full/merchant_id
-X 'POST'
-H 'Content-Type:application/json'
-d '[ { "id": "2001", "name": "ToothBrush", "img": "http://www.nutritionrx.ca/wp-content/uploads/2015/04/ToothbrustTest.jpg", "price":1.20 }, { "id": "2002", "name": "ToothPaste", "img": "http://www.nutritionrx.ca/wp-content/uploads/2015/04/ToothPasteTest.jpg", "price":0.80 }, { ... } ]'

Success 200

HTTP/1.1 200 OK

Attach all the meta data that will be useful to display a particular item.

Updating partial data

Partial updates are useful to change only few fields of an item. Like price, availability, stock etc. Instead of sending the entire data again, only fields that are changed are to be sent in this request. send as POST request with Content type set to application/json. Primary key should be id and is mandatory. Fields present in this request will be updated/added to the old data. Send data as array of objects, where each object describes the partial update for individual product. Include any number of products in the array.

curl https://feed.expertrec.com/partial/merchant_id
-X 'POST'
-H 'Content-Type:application/json'
-d '[ { "id":"2001", "price":2.20 }, { "id":"2002", "qty":19, "discount":"20%" }, { ... } ]'

Success 200

HTTP/1.1 200 OK

Attach all the meta data that will be useful to display a particular item.

Deleting existing Data

Item meta data should be deleted using DELETE request, when it should no longer be recommended. The item id has to be specified. Data is sent as the array as shown below. Include any number of products in the array.

curl https://feed.expertrec.com/partial/merchant_id
-X 'DELETE'
-H 'Content-Type:application/json'
-d '[ {"id":"2001"}, {"id":"2002"}, ..]'

Success 200

HTTP/1.1 200 OK

Requesting Search Data

https://searchv6.expertrec.com/v6/search/merchant_id?q={search query}&size={number of results expected}&page
={page number for paginated results}&fq={facet query}

Parameter Information:

Parameter Description
q

Search Query

size

Number of results expected in a page

page

Expected Page Number for results

fq

Facet Query
When user clicks on facets, send the clicked
facet name as get parameter
fq=<field_name>:<field_value>
where both field_name and field_value are
url encoded

nf

Numeric facet Query
If facet is of numeric type (like a slider), the min and max value can be specified.

nf=<field_name>:<min_value>-<
max_value>

both min_value and max_value are optional.

For price between 500 and 20000 nf=price:500-20000
For Price less than 1000
nf=price:-1000
For Price greater than 1000
nf=price:1000-

The response is a json with results, num of results obtained, etc. Inside “results” key, list of products with their meta data is present. The content-type header is set to “application/json”

                  curl "https://searchv6.expertrec.com/v6/search/merchant_id/?q=samsung&size=16&page=0"
                 

Success 200

HTTP/1.1 200 OK
{ "results": [ { "id": "SAM2017", "name" : "Samsung Galaxy Note, 2017, 2GB 32GB", price":"$200" .... }, { "id": "110SM2017", "name" : "Samsung Galaxy Tab, New, 3GB 64GB", "price":"$300" .... }, .....], "sfacets": { "availability": [ { "count": 136, "name": "in stock" }, ... } }