zanox Web Services Workshop 1.0
Posted by Sebastian Wallroth in HowTo, Widget production, April 15th, 2009Welcome to the workshop. I want to explore with you the possibilities zanox Web Services offers you.
First let’s have a look at this plain product search example taken from our wiki. It consists of a HTML file containing JavaScript code.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>zanox Web Services - Contextual Product Search</title>
</head>
<body>
<h1>zanox Web Services - Contextual Product Search</h1>
<div id="zxAdList"></div> <!-- // DIV HTML element to be filled with product information -->
<script type="text/javascript">
// function to add scripts to html header
function addScript(url) {
var script = document.createElement('script');
// preventing caching of the Web Service call by adding timestamp
script.src = url + '&t=' + new Date().getMinutes();
script.type = 'text/javascript';
document.getElementsByTagName('head')[0].appendChild(script);
}
// function for zanox product search
// for detailed parameter description see
// http://wiki.zanox.com/en/Products_Resource#GET:_Contextual_product_search
function productSearch(version, applicationid, adspace, region, programs, minPrice, maxPrice, category, page, items, q, callback) {
var url = 'http://api.zanox.com/json/' + version + '/products?applicationid=' + applicationid;
// adspace=null returns tracking links for all adspaces
if (adspace) url += '&adspace=' + adspace;
// sales region; e.g. de, fr, it; null means "all countries"
if (region) url += '®ion=' + region;
// program ID
if (programs) url += '&programs=' + programs;
// zanox product category ID; null means "all categories"
if (category) url += '&category=' + category;
// search result is paged
if (page) url += '&page=' + page;
// number of products per page
if (items) url += '&items=' + items;
// minimum price
if (minPrice) url += '&minPrice=' + minPrice;
// maximum price
if (maxPrice) url += '&maxPrice=' + maxPrice;
// handler for the search result
if (callback) url += '&callback=' + callback;
// search term
if (q) url += '&q=' + q;
// adding script to html header
addScript(url);
}
// function for computing of the search result
function handler(data) {
if (data.productsResult) {
var productItems = data.productsResult.productItem;
// accessing the existing div element with the ID "zxAdList"
var theList = document.getElementById('theList');
// looping through the product results
for (var i = 0; i < productItems.length; i++) {
var productItem = productItems[i];
var link = '';
if (productItem.url.adspace instanceof Array) {
// selecting tracking link related to the first adspace
link = productItem.url.adspace[0].$;
}
else {
link = productItem.url.adspace.$;
}
// creating a list item <li><a href="PRODUCT LINK">PRODUCT NAME at ADVERTISER only PRODUCT PRICE</a></li>
var item = document.createElement("li");
item.innerHTML = "<a href='" + link + "'>" + productItem.name + " at " + productItem.program.$ + " only " + productItem.price.toFixed(2) + " " + productItem.currency + "</a>";
// appending item to theList
theList.appendChild(item);
}
}
}
// creating an unordered list <ul id="theList"></ul>
var theList = document.createElement("ul");
theList.setAttribute("id","theList");
// accessing the existing div element with the ID "zxAdList"
var zxAdList = document.getElementById('zxAdList');
// adding theList to zxAdList
zxAdList.appendChild(theList);
// performing the zanox search
productSearch('2009-02-01', 'BE94C4947839E8AB4D67', null, null, '660', null, null, null, 0, 5, 'red towel', 'handler');
</script>
</body>
</html>You can copy this code as it is into a text file, then save the file as a.html and view it in a browser. It should look quite similar to this screenshot: 
Let’s go through the code.
1 2 3 4 5 6 7 8 9 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> <title>zanox Web Services - Contextual Product Search</title> </head> <body> <h1>zanox Web Services - Contextual Product Search</h1> <div id="zxAdList"></div> <!-- // DIV HTML element to be filled with product information --> <script type="text/javascript"> |
The first lines are the HTML part of the file. In line 7 the huge headline is created and in line 8 a DIV container is placed to be filled with our Web Service output.
10 11 12 13 14 15 16 17 | // function to add scripts to html header function addScript(url) { var script = document.createElement('script'); // preventing caching of the Web Service call by adding timestamp script.src = url + '&t=' + new Date().getMinutes(); script.type = 'text/javascript'; document.getElementsByTagName('head')[0].appendChild(script); } |
The function addScript() starting at line 11 takes a given URL. Then it creates in line 12 a new script in our HTML document like if we would add a <script></script> tag into the HTML code. In line 14 the parameter src is added to the script object and filled with the given URL like if we would extend the script tag to <script src="url"></script>.
The magic part + '&t=' + new Date().getMinutes() adds a timestamp to the URL. This doesn’t influent the script but prevents caching of the Web Service request. If we would strip the magic code, we would recieve always the same products even if we would use different search terms.In line 16 we add the script to the HTML HEAD section. Do you know why?
- Wouldn’t it work also if we would include the script from within the HTML BODY section?
- We have to add it to the HTML HEAD section, because we are calling a URL of another domain. The script is placed on your server and calls the zanox Web Service URL. If we would put the script into the HTML BODY this would lead to a security warning or an error. But doing it from within the HTML HEAD section there is no problem.
- Why don’t we put the script into the HTML HEAD section manually?
- Because we are programing a widget. Widgets are added to the HTML BODY section per definitionem.
18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 | // function for zanox product search // for detailed parameter description see // http://wiki.zanox.com/en/Products_Resource#GET:_Contextual_product_search function productSearch(version, applicationid, adspace, region, programs, minPrice, maxPrice, category, page, items, q, callback) { var url = 'http://api.zanox.com/json/' + version + '/products?applicationid=' + applicationid; // adspace=null returns tracking links for all adspaces if (adspace) url += '&adspace=' + adspace; // sales region; e.g. de, fr, it; null means "all countries" if (region) url += '®ion=' + region; // program ID if (programs) url += '&programs=' + programs; // zanox product category ID; null means "all categories" if (category) url += '&category=' + category; // search result is paged if (page) url += '&page=' + page; // number of products per page if (items) url += '&items=' + items; // minimum price if (minPrice) url += '&minPrice=' + minPrice; // maximum price if (maxPrice) url += '&maxPrice=' + maxPrice; // handler for the search result if (callback) url += '&callback=' + callback; // search term if (q) url += '&q=' + q; // adding script to html header addScript(url); } |
The function productSearch() performes the zanox product search. Basically we are building a URL calling the product search service and handing over several parameters. Please refer to the zanox wiki to see the complete documentation. In line 22 we are starting to build the URL with http://api.zanox.com/json/, adding the folder of the current version, the method product, and the application ID as the first parameter.
- Where do I get my application ID?
- Go to http://www.zanox.com. Login using the top right form. Activate the tab Web Services (BETA) and grab the application ID from the table or create a new one using the button.
The next parameters are filters for the search. Then in line 40 the handler for the result is defined. Finally in line 44 the prior function addScript() is called to move the Web Services call into the HTML HEAD section which leads to an instant execution of it.
46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 | // function for computing of the search result function handler(data) { if (data.productsResult) { var productItems = data.productsResult.productItem; // accessing the existing div element with the ID "zxAdList" var theList = document.getElementById('theList'); // looping through the product results for (var i = 0; i < productItems.length; i++) { var productItem = productItems[i]; var link = ''; if (productItem.url.adspace instanceof Array) { // selecting tracking link related to the first adspace link = productItem.url.adspace[0].$; } else { link = productItem.url.adspace.$; } // creating a list item <li><a href="PRODUCT LINK">PRODUCT NAME at ADVERTISER only PRODUCT PRICE</a></li> var item = document.createElement("li"); item.innerHTML = "<a href='" + link + "'>" + productItem.name + " at " + productItem.program.$ + " only " + productItem.price.toFixed(2) + " " + productItem.currency + "</a>"; // appending item to theList theList.appendChild(item); } } } |
The function handler(data) catches the result delivered in the container data.productsResult. The products are stored in the array data.productsResult.productItem In line 51 we are creating a handler for the list where we want to put the single product items in. Beginning in line 53 we are looping through the products.
For every product we have the following data. (This is the example from the zanox Web Services documentation in our wiki.)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <response xmlns="http://api.zanox.com/namespace/2009-02-01/"> <productsResult> <productItem id="76485b5f7021f7bc03b853fbf5debb53"> <name>Example product</name> <modified>2008-06-01T17:00:00Z</modified> <description>Description of the example product item</description> <manufacturer>Example Inc.</manufacturer> <program id="333">Example Inc. advertising program</program> <currency>EUR</currency> <price>39.90</price> <category id="10000"></category> <ean>3817610347</ean> <image> <small>http://www.example.com/productimage/71/BTP/4X_20425_3028.jpg</small> <medium>http://www.example.com/productimage/71/bp/4X_20425_3028.jpg</medium> <large>http://www.example.com/productimage/71/BM/4X_20425_3028.jpg</large> </image> <url> <adspace id="1">http://www.zanox-affiliate.de/ppc/77171C831740488ULP=[[000697]]</adspace> <adspace id="2">http://www.zanox-affiliate.de/ppc/77172C832740488ULP=[[000697]]</adspace> <adspace id="3">http://www.zanox-affiliate.de/ppc/77173C833740488ULP=[[000697]]</adspace> </url> </productItem> </productsResult> </response>
Please keep in mind that only the attributes
- productItem id
- name
- modified
- manufacturer
- program id
- currency
- category id
Also the image urls are not supervised by zanox. Sometimes there are no ones. Sometimes the url format is wrong. Sometimes instead of a product image an image with a text like “No image” is delivered.
The description sometime includes (bad) HTML code.
71 72 73 74 75 76 77 | // creating an unordered list <ul id="theList"></ul> var theList = document.createElement("ul"); theList.setAttribute("id","theList"); // accessing the existing div element with the ID "zxAdList" var zxAdList = document.getElementById('zxAdList'); // adding theList to zxAdList zxAdList.appendChild(theList); |
In lines 72 to 77 we are creating a unordered list and appending it to the DIV container established in line 8. (This list is filled with LI items in lines 64 to 67.)
78 79 | // performing the zanox search productSearch('2009-02-01', 'BE94C4947839E8AB4D67', null, null, '660', null, null, null, 0, 5, 'red towel', 'handler'); |
In line 79 the function productSearch() is called handing over the parameters
- Version – the zanox Web Services version –
2009-02-01 - Application ID - place your application ID here; the current is mine (you CAN use, but it’s ME earning the money then ) –
BE94C4947839E8AB4D67 - AdSpace ID - you can append the transactions to a dedicated advertising space of yours –
null - Region – filters the result set to products for one country here, e.g. France or Kenia –
null - Programs – filters the result set to one advertiser –
660 - Minimum price – filters the result set to products mre expensive than this –
null - Maximum price – filters the result set to products cheaper than this –
null - Category – filters the result set to one zanox product category –
null - Page – the result set is splitted into pages; only the products of the page set here will be displayed –
0 - Items – number of products per page –
5 - Search term – what we are searching for –
red towel - callback – access key to the result set –
handler
Playtime! You can play with some filters now. Try this:
productSearch('2009-02-01', 'BE94C4947839E8AB4D67', null, 'de', '660', null, null, null, 0, 25, 'Rolling Stones', 'handler');
productSearch('2009-02-01', 'BE94C4947839E8AB4D67', null, 'se', '660', 8, 20, null, 0, 5, 'Sweater', 'handler');
productSearch('2009-02-01', 'BE94C4947839E8AB4D67', null, 'fr', '660', 200, 500, null, 0, 10, 'South Korean Samsung Electronics plans to launch a new generation refrigerator, equipped with RFID, which detects when its contents are running low or approaching expiration dates', 'handler');
Finally we are closing the file …
80 81 82 | </script> </body> </html> |
... and the workshop. See you next time!
Permalink
As 
Today at the 
On 24 March 2009 zanox, Corporate Finance Partners and Mountain Partners celebrate the 
A lot of ideas whir around here for Web Service code examples. But we have to focus on the development of the Web Services. Nevertheless some nitty gritty pieces of software are to be found in the