API

There is the complete Eltanin-EYE API. You are free to take a look to see all funcionalities provided and working examples. Most of examples have beed done from command line, but you can integrate easily in your app.

REST

Eltanin Eye API is based on a standard RESTful Web API.

REST standard focus in the reuse of the existing HTTP to communicate applications. It is seen as an alternative to SOAP.

REST is loosely typed and usually relies on JSON to encode data. Each URI represents a resource: a collection, an object, a relationship, or an attribute. There are four main verbs available as HTTP commands to access and modify resources: GET, POST, PUT, and DELETE. They are seen as their SQL counterparts SELECT, INSERT, UPDATE, and DELETE.

Examples presented in this section are using the curl command, and $ELTANIN_URL represents the URL that contains your credentials to access to your Eltanin Eye instance.

In this API we avoid POST, we stand for PUT. Using PUT we can guarantee not to create duplicated elements when network problems occur.

Environment

When you are providing your application with Eltanin Eye heroku provides you with the ELTANIN_URL configuration variable. Look here to know how to setup it. To get the value of ELTANIN_URL execute the following command:

:::term
$ heroku config:get ELTANIN_URL
https://user:pass@instance.ip/resourceid

You can also asign it via export as follows:

:::term
$ export ELTANIN_URL=`heroku config:get ELTANIN_URL`

You can test the environment variable by using test case:

:::term
$ curl -XGET $ELTANIN_URL/hello
hello world

Buyers

Buyers can be accessed through $ELTANIN_URL/buyers and each buyer is identified by your id. You can add new buyers, remove old ones, get recommendations, and add social information.

GET /buyers

List all buyers.

:::definition
GET /buyers?offset=:offset&limit=:limit
BODY:
   ---
RESULT:
   [:buyer, ...]
  • :offset: the first element to show from the list (optional, default=0),
  • :limit: maximum number of elements in the list result.
  • :buyer: each buyer id returned in a list,

Example of use

:::term
$ curl -XGET $ELTANIN_URL/buyers\?limit=50
["100003891328699","100001949131998","100000462301393","100003946788426","100001170023440","1051738320","100000286307667","1611310553","100001015302286","100003969403241","100001787133768","100004008392709","1516849870","100003976995751","100000502013002","100003074096293","100002745535015","100002143775610","100004076342216","100004003031020","100003006233760","100004050799876","100002466019100","100003169557432","100003956810651","100003891471234","100003955395665","100004044236855","100003133194033","100003588868187"]
$ curl -XGET $ELTANIN_URL/buyers\?offset=3\&limit=10
["100001170023440","1051738320","100000286307667","1611310553","100001015302286","100003969403241","100001787133768","100004008392709","1516849870","100003976995751"]

Question mark ? and ampersand & have a special meaning in most *nix shells, it must be escaped with a blackslash \? and \&.

Comments

:offset first element is 0 and last element is (GET /buyers!count) - 1. :limit is restricted to 50 elements in most of available [plans]http://addons.heroku.com/eltanin. Combine :offset and :limit to obtain all elements.

Related

GET /buyers!count

Gets the count of buyers present.

:::definition
GET /buyers!count
BODY:
   ---
RESULT:
   [:count]
  • :count: the current number of buyers registered.

Example of use

:::term
$ curl -XGET $ELTANIN_URL/buyers\!count
[50]

The exclamation mark ! has a special meaning in most *nix shells, it must be escaped with a blackslash \!.

Comments

It gets the number of buyers added. This count can be used to iterate over the whole collection using limit and offset.

Related

DELETE /buyers

Removes all buyers.

:::definition
DELETE /buyers
BODY:
   ---
RESULT:
   ---

Example of use

:::term
$ curl -XDELETE $ELTANIN_URL/buyers

Comments

This will destroy all buyers and their associated data. This cannot be undone!

Related

GET /buyers/:buyer

Request the state of a buyer.

:::definition
GET /buyers/:buyer
BODY:
   ---
RESULT:
   { "buyer" : :buyer, "validated" : :validated }
  • :buyer: the buyer id to query,
  • :validated: boolean true if the buyer is has social information.

Example of use

:::term
$ curl -XGET $ELTANIN_URL/buyers/100003891328699
{"buyer":"100003891328699", "validated":true}

Comments

When a buyer is added it is not validated, it is validated when likes are provided. These likes can be added manually, or using a valid access_token for Facebook in order to retrieve the profile. If the Facebook access_token is provided, once the profile is retrieved successfully (done automatically by Eltanin Eye for you), validated becomes true.

Related

PUT /buyers/:buyer

Adds a buyer.

:::definition
PUT /buyers/:buyer
BODY:
   ---
RESULT:
   ---
  • :buyer: your identifier of the buyer to be added.

Example of use

:::term
$ curl -XPUT $ELTANIN_URL/buyers/100003891328699

Comments

It expects a string as id for :buyer. You should use a non empty string containing no slashes /, no sharp code #, neither question mark ?. If the same :buyer is added twice or more, the first time is added, and after this each call returns an error and the buyer remains unaltered.

It is a PUT operation. If the buyer already exists nothing occurs. If the buyer does not exists, the buyer is added. It does not removes or replaces any of the information related to the buyer if it already exists (likes, carts, ...).

Related

DELETE /buyers/:buyer

Deletes one buyer.

:::definition
GET /buyers/:buyer
BODY:
   ---
RESULT:
   ---
  • :buyer: your identifier of the buyer.

Example of use

:::term
$ curl -XDELETE $ELTANIN_URL/buyers/100003891328699

Comments

Error if the buyer does not exists or it is already deleted. It also deletes this buyer from all its products.

Related

Buyers/Products

GET /buyers/:buyer/products

List of products adquired by one buyer.

:::definition
GET /buyers/:buyer/products?offset=:offset&limit=:limit
BODY:
   ---
RESULT:
   [:product, ...]
  • :buyer: identifier of the buyer,
  • :offset: the first element to show from the list (optional, default=0),
  • :limit: maximum number of elements in the list result,
  • :product: each of your product codes registered to this buyer.

Example of use

:::term
$ curl -XGET $ELTANIN_URL/buyers/100003891328699/products\?limit=50
["apple","computer","travel"]

Related

GET /buyers/:buyer/products!count

Gets the count of different products adquireds by one buyer.

:::definition
GET /buyers/:buyer/products!count
BODY:
   ---
RESULT:
   [:count]
  • :buyer: identifier of the buyer,
  • :count: the current number of products registered to this buyer.

Example of use

:::term
$ curl -XGET $ELTANIN_URL/buyers/100003891328699/products\!count
[3]

Related

DELETE /buyers/:buyer/products

Removes all adquisitions of one buyer.

:::definition
DELETE /buyers/:buyer/products
BODY:
   ---
RESULT:
   ---
  • :buyer: identifier of the buyer,
  • :product: each of your product codes registered to this buyer.

Example of use

:::term
$ curl -XGET $ELTANIN_URL/buyers/100003891328699/products\?limit=50

Comments

It removes all adquisitions, but it does not removes products. Since this call will be assumed that this buyer has never made a single bought before.

Related

Explains

Buyers love products because many aspects. Buyers have profiles, but products have profiles too (their tags). Eltanin Eye relates buyers profiles to product profiles and explains the affinity of each buyer to each product aspect.

GET /buyers/:buyer/explain/:product

Gets a detailed match of the buyer against to the product.

:::definition
GET /buyers/:buyer/explain/:product
BODY:
   ---
RESULT:
   { buyer : :buyer,
     product : :product,
     match : :match,
     tags : {
        :tag : :tag_match
        ...
     }
   }
  • :buyer: buyer id to relate,
  • :product: product id to relate,
  • :match: an overal match,
  • :tag: each of the tags related to the product,
  • :tag_match: each of the corresponding matches of tags.

Example of use

:::term
$ curl -XGET $ELTANIN_URL/buyers/100003891328699/product/apple
{"buyer":100003891328699,"product":apple,"match":0.233,"tags":{"workday":0.798,"holyday":0.316}}

Related

Likes

Likes represents the social profile of a buyer. In the current implementation there are two sources of profiles: likes and Facebook. The custom social profile consist of likes, each of one is a simple and plain string, and how many times it is liked (or its strengh). Facebook engine goes beyond plain likes, and considers other information as checkins, subscriptions, friendships, ...

PUT /buyers/:buyer/social/likes

Replaces custom likes of one buyer by new ones.

:::definition
PUT /buyers/:buyer/social/likes
BODY:
   [ { "like" : :like,
       "strength" : :strength
     },
     ...
   ]
RESULT:
   ---
  • :buyer: buyer id to modify,
  • :like: a string with the name of the like,
  • :strength: a decimal number describing the strength of this like.

Example of use

:::term
$ curl -d '[{like:"books",strength:5},{like:"movies",strength:1.5}]' -XPUT $ELTANIN_URL/buyers/100003891328699/social/likes

Comments

These likes will be used eventually to make recommendations. Product recommendations are based in social profiles of their buyers. Changes in products buyers and buyers profiles may change results of recommendations. Some of these changes may be delayed if they are not substantial.

Related

Facebook

Eltanin Eye has a plugin able to work with Facebook social profiles. From these profiles it extracts likes, checkins, subscriptions, friendships, ... All these information will be used to generate recommendations. Information about these profiles are stored in a non-human readable format and optimised for recommendations. It ensures that we will keep the privacy of your buyers. And of course, the Facebook plugin is read-only, it does not change/pollute buyers facebook profiles in any way.

PUT /buyers/:buyer/social/fb

Sets/updates information to access to user's facebook profiles.

:::definition
PUT /buyers/:buyer/social/fb
BODY: 
   { fb_id : :fb_id,
     token : :token
   }
RESULT:
   ---
  • :buyer: buyer id to modify,
  • :fb_id: number of the facebook id associated to your buyer,
  • :token: token to access to the facebook profile of the buyer (also known as access token).

Example of use

:::term
$ TOKEN=AAACEdEose0dCBC0ZJCJqqW0bu2cvrFwC944LbrDau6zhc1LUv0IbIyXWeFsXbv31ud2ILC0uQf51AZoG6arixe0baBZsHEhbY2NdqEd8dyU47QMTcGU
$ curl -d "{\"fb_id\":100003891328699,\"token\":\"$TOKEN\"}" -XPUT $ELTANIN_URL/buyers/100003891328699/social/fb

This example uses the Facebook id as buyer id. It is not mandatory, and it is discouraged if you are planning to use more than one social engine as source for recommendations.

Comments

The retrieval of facebook profile is defferred, use GET /buyers/:buyer validated field to know when the social profile is ready.

You can use https://developers.facebook.com/tools/explorer to obtain a temporary limited facebook access token to make testing with your profile.

Love

Eltanin Eye make great recommendations based on buyers profiles, products (and tags), and sells. Each recommendation has a buyer, a product, and the match. There are three kind of recommendations: cross-selling, up-selling, and social-selling. Cross-selling is used to recommend an alternative to one product that might be more interesting, increasing the profit of the sell, or presenting a more suitable product. Up-selling is used to recommend more products related to a cart in order to increase the volume of the sell. Social-selling is used to recommend products that suits to the buyer's profile, it enables to focus the attention of the user in the most interesting and attrative products.

Recommendations are computed in real-time for each product. Eltanin Eye uses the combination of all profiles of buyers with the product and tags to evaluate the current buyer match to a product. If there is not enough information in the profile of the current user to compute a match, match is 0. It is also possible, although the buyer has adquired one product, that the match from the buyer to the product is low, this is due to this buyer profile is not consistent with the others.

Recommendation lists are ordered by match. Highests matches are likely to be first but, because of the complexity of the computation involved, it is possible to miss some good matches in some queries. Although this situation, the priority is to give good results in computational times below one second. Eltanin Eye will explore all combinations and will improve the result at each use.

The accuracy of this computation can be improved by acquiring higher plans. Theses plans allocates more resources to provide better results. A list of all plans available can be found here.

GET /buyers/:buyer/cross-selling

Gets the cross-selling recommendations related to one product.

:::definition
GET /buyers/:buyer/cross-selling
BODY:
   { "product" : :product
     }
RESULT:
   [ { "buyer"   : :buyer,
       "product" : :cross_product,
       "match"   : :match
     },
     ...
   ]
  • :buyer: buyer id for the recommendation,
  • :product: product id to get related recommendations,
  • :cross_product: each of cross products recommended,
  • :match: each of the corresponding matches value from 1.0 to 0.0.

Example of use

:::example
curl -d '{"product":"apple"}' -XGET /buyers/100003891328699/cross-selling
[{"buyer":"100003891328699","product":"computer","match":0.971},{"buyer":"100003891328699","product":"travel","match":0.153}]

Comments

The match value is how the cross prodcut matches with the buyer and with the product.

Related

GET /buyers/:buyer/up-selling

Gets the up-selling recommendations related to one cart.

:::definition
GET /buyers/:buyer/up-selling
BODY:
   { items : [ {
           "product"  : :product,
           "quantity" : :quantity
         },
         ...
       ]
     }
RESULT:
   [ { "buyer"   : :buyer,
       "product" : :up_product,
       "match"   : :match
     },
     ...
   ]
  • :buyer: buyer id for the recommendation,
  • :product: each of product id to get related recommendations,
  • :quantity: corresponding quantity for each product,
  • :up_product: each of up products recommended,
  • :match: each of the corresponding matches value from 1.0 to 0.0.

Example of use

:::example
curl -d '{"items":[{"product":"apple","quantity":1.5},{"product":"computer","quantity":2}]' -XGET /buyers/100003891328699/cross-selling
[{"buyer":"100003891328699","product":"travel","match":0.513}]

Comments

This query uses a simplified cart as input, but it does not require a cart id neither a buyer id. You can add those fields, but they will be ignored. It is assumed that this cart is not sold and can be improved, thus no cart id is required. And buyer id is provided in the REST uri.

Recommendation is based in the cart itself, considering the buyer, the products involved, and their quantities.

Related

GET /buyers/:buyer/social-selling

Gets recommendations related to one buyer and its social profile.

:::definition
GET /buyers/:buyer/social-selling?tag=:tag
BODY:
   ---
RESULT:
   [ { "buyer"   : :buyer,
       "product" : :product,
       "match"   : :match
     },
     ...
   ]
  • :buyer: buyer id for the recommendation,
  • :tag: optative repeatable tags that must have all recommended products,
  • :product: each of products recommended for the buyer,
  • :match: each of the corresponding matches value from 1.0 to 0.0.

Example of use

:::example
curl -d -XGET /buyers/100003891328699/social-selling
[{"buyer":"100003891328699","product":"computer","match":0.741},{"buyer":"100003891328699","product":"travel","match":0.448},{"buyer":"100003891328699","product":"apple","match":0.233}]

curl -d -XGET /buyers/100003891328699/social-selling?tag=holyday
[{"buyer":"100003891328699","product":"travel","match":0.448},{"buyer":"100003891328699","product":"apple","match":0.233}]

curl -d -XGET /buyers/100003891328699/social-selling?tag=workday&tag=holyday
[{"buyer":"100003891328699","product":"apple","match":0.233}]

Related

Products

Products can be accessed through $ELTANIN_URL/products and each product is identified by your id. You can add new products, remove old ones and update tags.

GET /products

List all products.

:::definition
GET /products?offset=:offset&limit=:limit
BODY:
   ---
RESULT:
   [ :product, ... ]
  • :offset: the first element to show from the list (optional, default=0),
  • :limit: maximum number of elements in the list result,
  • :product: each of product id returned in a list.

Example of use

:::term
$ curl -XGET $ELTANIN_URL/products\?limit=50
["apple","computer","travel"]

Related

GET /products!count

Gets the count of products present.

:::definition
GET /products!count
BODY:
   ---
RESULT:
   [:count]
  • :count: the current number of products registered.

Example of use

:::term
$ curl -X GET $ELTANIN_URL/products\!count
[3]

Related

DELETE /products

Deletes all products.

:::definition
DELETE /products
BODY:
   ---
RESULT:
   ---

Example of use

:::term
$ curl -XDELETE $ELTANIN_URL/products

Comments

It deletes also deletes all carts.

Related

PUT /products/:product

Adds a product.

:::definition
PUT /products/:product
BODY:
   ---
RESULT:
   ---
  • :product: string with your product id.

Example of use

:::term
$ curl -XPUT $ELTANIN_URL/product/laptop

Related

DELETE /products/:product

Removes one product.

:::definition
DELETE /products/:product
DATA:
   ---
RESULT:
   ---
  • code: your product id.

Example of use

:::term
$ curl -XDELETE $ELTANIN_URL/products/laptop

Comments

It deletes also all relationships from the product to buyers and carts.

Related

Products/Tags

Tags are simple strings attached to products. Tags are used to refine search and predict recommendations of new products. They provide a very simple kind of social profile for products.

PUT /products/:product/tags

Adds or replaces tags associated to one product.

:::definition
PUT /products/:product/tags
BODY:
   [ :tag, ... ]
  • :product: product id to modify,
  • :tag: string with a tag name.

Example of use

:::term
$ curl -d '["workday","holyday"]' -XPUT $ELTANIN_URL/products/apple/tags

Comments

The concept of tags for products is analog to the concept of likes for buyers. The main difference is that only few tags should be used, and tags are assigned or not assigned, but not assigned twice or with double strength.

Related

Tags

Tags can be accessed through $ELTANIN_URL/tags and each tag is identified by your id. You can add new tags, remove old ones and update tags.

GET /tags

List all tags.

:::definition
GET /tags?offset=:offset&limit=:limit
BODY:
   ---
RESULT:
   [ :tag, ... ]
  • :offset: the first element to show from the list (optional, default=0),
  • :limit: maximum number of elements in the list result,
  • :tag: each of tag id returned in a list.

Example of use

:::term
$ curl -XGET $ELTANIN_URL/tags\?limit=50
["weekday","holyday"]

Related

GET /tags!count

Gets the count of tags present.

:::definition
GET /tags!count
BODY:
   ---
RESULT:
   [:count]
  • :count: the current number of tags registered.

Example of use

:::term
$ curl -X GET $ELTANIN_URL/tags\!count
[2]

Related

DELETE /tags

Deletes all tags.

:::definition
DELETE /tags
BODY:
   ---
RESULT:
   ---

Example of use

:::term
$ curl -XDELETE $ELTANIN_URL/tags

Related

PUT /tags/:tag

Adds a tag.

:::definition
PUT /tags/:tag
BODY:
   ---
RESULT:
   ---
  • :tag: string with your tag id.

Example of use

:::term
$ curl -XPUT $ELTANIN_URL/tag/weekday

Related

DELETE /tags/:tag

Removes one tag.

:::definition
DELETE /tags/:tag
DATA:
   ---
RESULT:
   ---
  • code: your tag id.

Example of use

:::term
$ curl -XDELETE $ELTANIN_URL/tags/weekday

Comments

It deletes also all relationships from the tag to buyers and carts.

Related

Carts

Your sells are represented as carts. Each cart is a set of products and entities bought by your buyer. Although you can register one cart for each single sell, it is strongly recommended to group all sells made at once in a single cart. This will enable cross-selling and up-selling.

PUT /carts/:cart

Adds or replaces a cart.

:::definition
PUT /carts/:cart
BODY:
   { "buyer" : :buyer,
     "items" : [ {
         "product"  : :product,
         "quantity" : :quantity
       },
       ...
     ]
   }
RESULT:
   ---
  • :cart: your cart id,
  • :buyer: buyer id who bought this cart,
  • :product: each of the products of this cart,
  • :quantity: corresponding quantity for each product.

Example of use

:::term
curl -d '{"buyer":100003891328699,"items":[{"product":"apple","quantity":1.5},{"product":"computer","quantity":2}]' -XPUT /carts/100003891328699X241

Related

Batch

Eltanin Eye includes batch support to execute multiple requests into a single HTTP connection.

One of the biggest issues of using remote connections are network delays. For each remote query your app must wait to transfer the query Eltanin Eye engine, and wait to return of the result. Although Eltanin Eye speed is really awesome, we cannot avoid the pennalty of using the network. Some languages, like Node, use asynchronous calls to minimize the network penalty, but even in this case, the message order arrival cannot be predicted and waits are required to avoid race conditions.

The batch API allows you to make multiple request in a single network transfer, execute all requests in order, and return a result with another single network transfer. It reduces drastically the network overhead and improves the overall performance.

POST /batch

Groups multiple request in a single request and executes them in order.

:::definition
POST /batch
BODY:
   [ { "method" : :method,
       "path"   : :path,
       "body"   : :body
     },
     ...
   ]
RESULT:
   [ { "status"  : :status, 
       "message" : :message, 
       "result"  : :result
     },
     ...
   ]
  • :method: the method for each request ("GET", "PUT", "DELETE", "POST"),
  • :path: relative path for each request (without including $ELTANIN_URL),
  • :body: body for each request (optative if not required),
  • :status: integer number HTML status of each request result,
  • :message: for each request result error message if :status is not 2XX,
  • :result: for each request the result if :status is 2XX.

Example of use

:::term
COUNT='{"method":"GET","path":"/products!count"}'
ADD='{"method":"PUT","path":"/products/laptop"}'
TAGS='{"method":"PUT","path":"/products/laptop/tags","body":["workday"]}'
DEL='{"method":"DELETE","path":"/products/laptop"}'
curl -d "[$COUNT,$ADD,$TAGS,$COUNT,$DEL,$DEL]" -XPOST $ELTANIN_URL/batch
[{"status":200,"result":3},{"status":200,"result":"ok"},{"status":200,"result":"ok"},{"status":200,"result":"4"},{"status":200,"result":"ok"},{"status":400,"result":":product does not exists"}]

Comments

The batch is not atomic. Other petitions made in parallel can be served between two requests. Given de previous example of use, it is possible that the second count gives a count of 5 if other product is added meanwhile the batch is executed.

Requests are executed in order, and outputs respect the same order. The request in the position nth of the array of the body will have the output in the same position nth, but of the result array.

Related