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:

ParameterDescription
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 et 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" }, ... } }

Response Information:

KeyDescription
results

Array of items - each a dictionary of meta-data

sfacets

Dictionary of applicable facets. Each facet entry is an array of values and counts in decending order of count.

numeric

numeric facets with max and min value

res

additional meta data regarding the search results.


Requesting Recommendations Data

Once sufficient data flows to the system, the serving APIs automatically gets live. The following table shows the types of recommendation and their required parameter. Multiple recommendation types can be requested in a single request. If multiple types are requested, all the required parameters for all types should be present in the request. If the required parameters are not present, an empty list would be returned in the response for that recommendation type.



Optionally, additional filtering and ranking parameters can be passed with the request (as key=value). This data will be used along with items meta data for filtering/ranking. E.g. user current location can be passed to filter only properties in the given locality.


https://serve.expertrec.com/v2/rec/merchant_id?type={type_id}&user={user}&item={item}

Following are the type ids for different types:

TypeDescriptionRequired Params
2

Viewed Also Viewed

user, item

3

Viewed Ended Buying

user, item

4

Recommended Items

user

5

Similar

item

6

Trending

none

7

Top selling

none


The response is a json with an entry keyed by every requested type. Each entry is a list of items along with their meta data. The content-type header is set to “application/json”


							        			curl "https://serve.expertrec.com/v2/rec/merchant_id?type=2,7&user=cloud&item=book"
							        		

Success 200

HTTP/1.1 200 OK
[
{
item: book
metadata :
{
price: “100”,
currency: “inr”,
.....

}
}
]

Tracking Events

User-Item interaction

Every user interaction with item is to be sent to the following end point with HTTP GET or POST method. The end point has to be constructed with the following elements


https://log.expertrec.com/v2/collect/merchant_id

Parameter

FieldTypeDescription
userString

Unique user of the shop.

itemString

Unique Item/thing that is to be discovered by the user.

eventString

Any interaction between the user and item.


Following are the event ids for different events:

EventDescription
1

User Views Item.

2

User Buys Item

3

User Shortlists Item

4

User Likes Item


note


1. Event ids greater than 100 are user defined events and the significance of that event can be customized per merchant.
2. In case of custom events, extra parameters can be added to the request url.
   {parameter}={val}


							        			curl  "https://log.expertrec.com/v2/collect/merchant_id?user=cloud&item=book&event=1"
							        		

Success 200

HTTP/1.1 200 OK

User – List Interaction

Every user interaction with list of items is to be logged to the following end point with HTTP GET or POST method. The end point has to be constructed with the following elements filled. Standard lists are documented in the table below. Offset is the offset clicked by the user in the list of items and is zero based. This helps the system understand the display characteristics of these lists and accounts for it in the recommendations.


https://log.expertrec.com/v2/collect/merchant_id

Parameter

FieldTypeDescription
userString

Unique user of the shop.

itemString

Unique Item/thing that is to be discovered by the user.

listString

Id of the different types of list

offsetString

Offset clicked by the user in the list of items and is zero based


Following are the list ids for different types of list:

List_IdDescription
1

Search listing.

2

Viewed Also Viewed

3

Viewed Ended Buying

4

Recommended Items

5

Similar

6

Trending

7

Top selling


note


Custom list ids can be sent with values greater than 100.


							        			curl "https://log.expertrec.com/v2/collect/merchant_id?user=cloud&item=book&list=1&offset=1"
							        		

Success 200

HTTP/1.1 200 OK

Conclusion

With simple http requests, the data flow could be setup. The system would start its serving API typically after 20 à 30 days depending on the traffic volume and number of unique items.