API Documentation

API Documentation

How to use our API?

There are different components in our API :

  • Recommendation api, api to call the online recommendation engine
  • Collection api, javascript tracker, allowing us to get information about page views
  • Inventory upload, allowing us to identify and compare products
  • Other online services:
    • Search

I – Recommendation api

The recommendation API is very simple and allows to query recommendation on our server, using your credentials, details about the currently viewed product and the user. 

There is a very simple example:

http://reco.ezako.com/reco/?idsite=MY_IDSITE&t=MY_PRIVATE_TOKEN_KEY

This simple call contains only 2 parameters:

  • idsite: Your personnal idsite. For example: ezako.com
  • t: Your personnal privatekey

This is the minimum call in order to get a result. Both of these parameters are available in your profile: 

Additionnal (optional) parameters available:

  • id: The customer identifier. This parameter is mandatory to provide user specific recommendation. If you use ezako tracking system, it will be the parameter contained in the cookie called _pk_id*
  • pid: The currently viewed product id if any. This parameter makes sense on a product page.
  • type: The recommendation type used (defaults to ALL), values are: HOME, PRODUCT, ALL, OFFER, TOP, RANDOM
  • nb: The number of expected results. This is an indication as you could get less or a little more products

And this is a more complex example:

http://reco.ezako.com/reco/?idsite=MY_IDSITE&t=MY_PRIVATE_TOKEN_KEY&pid=657&nb=15&id=abr43254c543

 

The expected result is a very simple JSON document, including a list of product ids:

{ "ids": [6,2,1,5,8,7,4,9,3], "count":9 }



II – Collection api

We use the same logic as Google Analytics or Yahoo! Analytics: our collection api allows transferring browsing information from the client browser directly to our collection servers. This is done in an asynchronous fashion, to make sure that there is no impact of page loading time.

A) Introduction

The collection API must be used on every page of the e-commerce site. This integration is really simple.

For example on a product page, it is as simple as :

<script type="text/javascript">
var _ezaq = _ezaq ||[];
_ezaq.push(['setSiteId', 'MY_IDSITE']);
_ezaq.push(['setTrackerUrl', 'http://reco.ezako.com/pixel/pixel.png']);
_ezaq.push(['setProductView', 42, 'Robe rouge', ['Femmes', 'Robe'], 'Rouge', '40', 'Brand1', 19.99, null]);
_ezaq.push(['trackPageView']);
(function(){
var u=('https:' == document.location.protocol ? 'https://yourserverurl:449' : 'http://yourserverurl') +
/path/to/your/ez-analytics-min.js';
var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0]; g.type='text/javascript';
g.defer=true; g.async=true; g.src=u;
s.parentNode.insertBefore(g,s); })();
</script>

B) Configuration

Download the javascript tracker and make it accessible on your servers: download page

Create a variable as soon as possible in the script (in order to gather various informations) and configure the siteId and the collection url:
var _ezaq = _ezaq || [];
_ezaq.push(['setSiteId', 'MY_IDSITE']);
_ezaq.push(['setTrackerUrl', 'http://reco.ezako.com/pixel/pixel.png']);

Enable tracking :
// Function loading asynchronously tracking, as google analytics
// Specify site url and path to the javascript in variable u
(function(){
var u=('https:' == document.location.protocol ? 'https://yourserver.url:449' : 'http://yourserver.url') +
/path/to/your/ez-analytics-min.js';
var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
g.type='text/javascript'; g.defer=true; g.async=true; g.src=u;
s.parentNode.insertBefore(g,s); })();

C) Configure the tracking of page views

In order to track the various page views, we provide you various javascript methods to use depending on the page contents (home page, product page, basket, …). For instance, in a product view page you would use the following :

_ezaq.push(['setProductView', 42, 'Robe rouge', ['Femmes', 'Robe'], 'Rouge', '40', 'Brand1', 19.99, null]);
_ezaq.push(['trackPageView']);

It is important to do a call to trackPageView in order to enable the tarcking. This allows you to configure additional variables before the call, as we will see in the advanced section.
The complete list of methods is summarized as follows.

Methode Description
setHomeView() Home page
setCategoryView(cat) category names, separated by | from the more generic to the more specific
setProductView(pid, pname, cat, color, size, brand, price, special_price) Product page view

  • pid: unique product identifier – Mandatory
  • pname: product name in its original language
  • cat: category name, or array of categories and subcategory names
  • color: product color
  • size: size (e.g. ‘S’ or ’11’)
  • brand: brand name
  • price: product price
  • special_price: discounted price
setAddToBasket(pid, pname, cat, color, size, brand, price, special_price) Add to basket

  • pid: unique product identifier – Mandatory
  • pname: product name in its original language
  • cat: category name, or array of categories and subcategory names
  • color: product color
  • size: size (e.g. ‘S’ or ’11’)
  • brand: brand name
  • price: product price
  • special_price: discounted price
setViewBasket(pids, total) Basket view

  • pids: unique product identifier or array of product ids if there are more than one – Mandatory
  • total: total basket price
setOrder(pids, total, quantity) Order

  • pids: unique product identfier or array of product ids if there are more than one – Mandatory
  • total: total order price
  • quantity: quantity of each item, as an array if multiple, in the same order as pids
setOrderConf(pids, total, quantity, subtotal, tax, shipping, discount) Order confirmation

  • pids: unique product identfier or array of product ids if there are more than one – Mandatory
  • total: total order price
  • quantity: quantity of each item, as an array if multiple, in the same order as pids
  • subtotal: total price of this order, before additionnal taxes and charges
  • tax: taxes for this order
  • shipping: shipping costs
  • discount: discount for this order

We encourage you to use a maximum number of fields. Nevertheless, it is important to note that fields that are not mandatory can be replace by the value null .

D) Configure recommandation tracking

It is important for our automated learning system to be informed of clicks on recommended products. In order to do so, a simple javascript call must be wrapped in the click.

<a href="#" onclick='javascript:_ezaq.push(["trackRecoClick", 42 ]);'>Product name or image </a>

Methode Description
trackRecoClick(pid) Track recommandation clicked.

  • pid: unique product identifier – Mandatory

E) Track search engine

It is useful to keep track of the various queries of your customers

_ezaq.push(['trackSiteSearch', "sport baskets", false, 8]);

Methode Description
trackSiteSearch(keywords, category, searchCount) Search result tracking

  • keywords: query – Mandatory
  • category: selected category or ‘false’ – Mandatory
  • searchCount: number of search results or 0 – Mandatory

G) Advanced features

If the aforementioned methods do not suit your needs, it is always possible to add custom variables to complete the informations already provided

_ezaq.push(['setCustomVariable', 100, "testvarname1", "000" ]);

Methode Description
setCustomVariable(index, name, value) Add a customer variable

  • index: index number of the variable, linked to the name – Mandatory
  • name: variable name – Mandatory
  • value: variable value – Mandatory

All the variables and their corresponding indices are listed in the table below.

Index Variable name Description Mandatory
1 type type de page: home, category, product, addbasket, viewbasket, order, order_conf, other Mandatory
2 pid unique product identifier Mandatory
3 pname product name in its original language Mandatory
4 pid2 other product identifier Optional
5 cat category names, separated by | from the more generic to the more specific Mandatory
6 color product color (if applicable) Optional
7 size product size (if applicable) Optional
8 brand product brand Optional
9 price product price Optional
10 sprice discounted price Optional
12 total total price (basket and order pages) Optional
13 quantity quantity of products ordered, séparated by | if multiple products ordered Optional
15 sessionid user unique identifier, for instance an id from the server cookie Optional
16 userid user identifier if logged in Optional
20 rclicked product identifier on a recommandation clicked (to track conversions) Optional
22 subtotal total price of this order, before additionnal taxes and charges Optional
23 tax taxes for this order Optional
24 shipping shipping costs Optional
25 discount discount for this order Optional

Please note that the more variables you configure, the better our recommandations algorithms.

H) Advanced example

<html> 
<head> 
... 
<script type="text/javascript"> 
// Init the tracking variable to be able to track in the file 
var _ezaq = _ezaq || []; 
_ezaq.push(['setSiteId', 'MY_IDSITE']); 
_ezaq.push(['setTrackerUrl', 'http://reco.ezako.com/pixel/pixel.png']); 
</script> 
... 
</head> 
<body> 
... 
<script type="text/javascript"> 
// Set some variables in the body (these are only sample - not needed) 
_ezaq.push(['setCustomVariable', 100, "testvarname1", "000" ]); 
_ezaq.push(['setCustomVariable', 101, "testvarname2", "rose" ]); 
_ezaq.push(['setCustomVariable', 102, "testvarname3", "18" ]); 
</script> 
... 
// Track click on a recommendation 
<a href="#" onclick='javascript:_ezaq.push(['trackRecoClick', 5000]);'>Product 5000</a> 
... 
<script type="text/javascript"> 
// If the user is logged in, we might match session id with username (optional) 
_ezaq.push(['setCustomVariable', 16, "userid", "julien123" ]); 
// Add a secondary product name 
_ezaq.push(['setCustomVariable', 4, "pid2", "1223" ]); 
// Now push the standard product view variables. 
// on product page: 12000 
// on categories: 122|345|324|765 
_ezaq.push(['setProductView', 1200, 'baskets sport', [122, 345, 324, 765], 'red', '40', 'Brand1', 108.99, 99.99]); 
// Send out the tracking request. 
// Track page views (required) 
_ezaq.push(['trackPageView']); 
// Function loading asynchronously tracking, as google analytics 
// Specify site url and path to the javascript in variable u 
(function(){ 
var u=('https:' == document.location.protocol ? 'https://yourserver.url:449' : 'http://yourserver.url') + 
'/path/to/your/ez-analytics-min.js'; 
var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0]; 
g.type='text/javascript'; g.defer=true; g.async=true; g.src=u; 
s.parentNode.insertBefore(g,s); })(); 
</script> 
... 
</body> 
</html> 

III – Inventory upload

Our service uses your inventory to guarantee recommending only available products et to provide the best recommendations. This is why product description, availability and other information are collected.

You can upload your inventory as often as you wish, depending on your stock variations. Usually, this is done daily every couple of hours.

We use the feeds google merchant standard as collection format.

The inventory must be sent using the POST method to the following url:
http://reco.ezako.com/pixel/products.txt
The following POST headers must be configured with your information:
idsite: MY_IDSITE
token: MY_PRIVATE_KEY
Content-Type: text/plain; charset=UTF-8 

The contents are in the POST body, the format being text, separated by tabs, one lign for the column names, followed by one lign for each product.

id	title	price	sale_price	condition	link	availability	product_type	image_link	brand	description
1	Matrox G200 MMS	299.9900 USD	new		http://yourserver.url/product_info.php?prod_id=1	in stock	Hardware > Graphics Cards	http://yourserver.url/images/matrox/mg200mms.gif	Matrox  Reinforcing its position as a multi-monitor trailblazer, Matrox Graphics Inc. has once again developed the most flexible and highly advanced solution
2	Matrox G400 32MB	499.9900 USD	new		http://yourserver.url/product_info.php?prod_id=2	in stock	Hardware > Graphics Cards	http://yourserver.url/images/matrox/mg400-32mb.gif	Matrox	Dramatically Different High Performance Graphics Introducing the Millennium G400 Series - a dramatically different, high performance graphics

The information to provide is listed in the following table:

Column name Description
id unique product identifier
title product name in its original language
price product price, format: ii.ii USD or ii.ii EUR. Instance: 226.99 USD
sale_price discounted price
condition product condition: either ‘new’, ‘refurbished’ or ‘used’
link link to the product page
availability availability: either ‘in stock’, ‘available for order’ or ‘out of stock’
product_type product categories. In case of a hierarchy of several categories, use the ‘ > ‘ separator
product_type_id identifier for product categories. In case of a hierarchy of several categories, use the ‘ > ‘ separator
image_link link to a product picture
brand product brand
description product description. Limit to 1024 characters