EmcienPatterns API Overview

The EmcienPatterns API is implemented as RESTful calls that return JSON over HTTP. Functionality that is exposed consists mainly of our cross-sell up-sell functions, but we are also starting to roll out other functions as requests from customers come in.

The api calls have the following structure:

Basic Call:

http://{Emcien_API_URL}/{Your_Project_Key}/{api_endpoint}.json?param1=value1&param2=value2

• {Your_Project_Key} is a unique 36 character key provided by the system when your data is analyzed. It is a pointer to your unique repository of data and resulting buying patterns. This allows you to have multiple data sets and solutions and get results from them independently.
• {api_endpoint} represents the unique function call to the API you wish to make. These functions cover areas from cross-sell to statistics and are being added to all the time as new abilities are exposed in our technology.
• Results are currently available in JSON format.

EmcienPatterns APIs currently consist of the following api_endpoints:

Cross-Selling

/items/recommendations_for/{item_list}.json
Returns (cross-sell) recommendations for a set of items sent in. “People that bought A, also buy X,Y and Z”

Example Call:

http://{Emcien_API_URL}/{Your_Project_Key}/items/recommendations_for/7385RLGEP2.json?limit=3

This example asks for 3 recommendations of other products that sell well with item ’7385RLGEP2′.

Example Results:

["1593EACOX0","8100BXGEP4","6012EACPM2"]

/clusters/recommendations_for/{item_list}.json
Same as for /items/recommendations_for/, except it returns a list of clusters and additional statistics instead of a just the list of SKUs.

Example Call:

http://{Emcien_API_URL}/{Your_Project_Key}/clusters/recommendations_for/A123,B456.json?limit=3

Example Results:

[{
   "weight_by_month" :[253,201,214,253,191,224],
   "surprise"        :0.51769,
   "created_at"      :"2010/03/18 14:35:43+0000",
   "item_ids"        :["7005SPR8","7002SPR8"],
   "size"            :2,
   "updated_at"      :"2010/03/18 14:35:43 +0000",
   "weight"          :1336,
}]

Product Lookup

/items.json
Returns items that match that string (partial string matches)

Example Call:

http://{Emcien_API_URL}/{Your_Project_Key}/items.json?q=A1&limit=10

Returns 10 items that the item_id start with the characters ‘A1′.

Here is a sample of an item returned from this type of API call:

Example Results:
[{
   "created_at"             :"2010/03/18 14:36:43 +0000",
   "updated_at"             :"2010/03/18 14:36:43 +0000",
   "recommendings_by_month" :["8","9","11","8","8","12"],
   "weight"                 :68,
   "recommendeds"           :4,
   "recommendings"          :56,
   "recommendeds_by_month"  :["1","1","0","1","1","0"],
   "item_id"                :"A10RCMR"
}]

/cluster/{item_list}.json
Returns the basic data about one or more items. This is useful to lookup the frequency of a specific item (rather than what it recommends). The {item_list} is any single item or any number of comma separated items.

Example Call:

http://{Emcien_API_URL}/{Your_Project_Key}/cluster/Climate_Air,Dark_Grey.json

Returns the core data about the records found to have both ‘Climate_Air’ and ‘Dark_Grey’.

Here is a sample of an item returned from this type of API call:

Example Results:
[{
   "weight_min"      :7988,
   "updated_at"      :"2010/04/28 15:47:12 +0000",
   "item_ids"        :["Climate_Air","Dark_Grey"],
   "size"            :2,
   "weight"          :7664,
   "anchor"          :"Climate_Air",
   "compactness"     :0.171799,
   "weight_max"      :9645,
   "delinquency"     :0.040561,
   "weight_by_month" :[1029,813,1118,814,1553,1170,1167],
   "created_at"      :"2010/04/28 15:47:12 +0000"
}]

Product Statistics

/items/by_recommendeds.json
Lists the items that are recommended most often

Example Call:

http://{Emcien_API_URL}/{Your_Project_Key}/items/by_recommendeds.json?limit=10

This example returns the top 10 items that are recommended most often based on the buying patterns. (For example, ‘USB Cables’ are recommended many times by many products like printers, cameras, computers, etc. so they will have a high number of times that they are recommended.)

/items/by_recommendings.json
Lists the items that are making the most recommendations

Example Call:

http://{Emcien_API_URL}/{Your_Project_Key}/items/by_recommendings.json?limit=50

Returns the top 50 items making the most recommendations. (For example, the ‘Printer’ recommends things like ‘USB cable’ and ‘Paper’ but is not recommended much itself.)

/clusters/of_size/{size}.json
Lists the most frequent clusters of the size given by {size}

Example Call:

http://{Emcien_API_URL}/{Your_Project_Key}/clusters/of_size/5.json?limit=20

This example brings back the top 20 clusters/groups of 5 items found together.