zanox Web Services & Application Store Blog » HowTo

zanox Connect step by step guide for developers

Francesco Votta — Tue, 15 Sep 2009 08:29:48 +0000

More details can be found here

zanox Web Services Workshop 1.0

Sebastian Wallroth — Wed, 15 Apr 2009 20:40:29 +0000

Welcome 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.



 
  zanox Web Services - Contextual Product Search
 
 
  zanox Web Services - Contextual Product Search

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.


>
>
>zanox Web Services - Contextual Product Search>
>
>
>zanox Web Services - Contextual Product Search>
 id="zxAdList">> 
 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.

// 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 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 .

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.

// 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.

// 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 PRODUCT NAME at ADVERTISER only PRODUCT PRICE
      var item = document.createElement("li");
      item.innerHTML = "" + productItem.name + " at " + productItem.program.$ + " only " + productItem.price.toFixed(2) + " " + productItem.currency + "";
// 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.)

 version="1.0" encoding="UTF-8" standalone="yes"?>
 xmlns="http://api.zanox.com/namespace/2009-02-01/">
 >
    id="76485b5f7021f7bc03b853fbf5debb53">
   >Example product>
   >2008-06-01T17:00:00Z>
   >Description of the example product item>
   >Example Inc.>
    id="333">Example Inc. advertising program>
   >EUR>
   >39.90>
    id="10000">>
   >3817610347>
   >
    >http://www.example.com/productimage/71/BTP/4X_20425_3028.jpg>
    >http://www.example.com/productimage/71/bp/4X_20425_3028.jpg>
    >http://www.example.com/productimage/71/BM/4X_20425_3028.jpg>
   >
   >
     id="1">http://www.zanox-affiliate.de/ppc/77171C831740488ULP=[[000697]]>
     id="2">http://www.zanox-affiliate.de/ppc/77172C832740488ULP=[[000697]]>
     id="3">http://www.zanox-affiliate.de/ppc/77173C833740488ULP=[[000697]]>
   >
   >
  >
>

Please keep in mind that only the attributes

productItem id

name

modified

manufacturer

program id

currency

category id

are always available.

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.

// creating an unordered list 
 
   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

>
 >
>

... and the workshop. See you next time!

How to monetize your blog, part I

Daniel Neubauer — Fri, 03 Apr 2009 14:09:59 +0000

This tutorial shows how to monetize blogs using zanox Web Services.

Part-I of this tutorial will focus on blogger.com.

So everything you’ll need to do is:

Open your Blog Layout at blogger.com (screen 1)

Create a new HTML/Script Gadget (screen 2)

Use the the Widget Source Code from snipplr as content for the HTML/Script Gadget (screen 3)

Replace the ApplicationId in the source example with yours and start writing content.

As you can see at screen 4, the new Gadget shows product data offers as a list of text links, always related to the headline of your blog entry.

Running live example: http://showcaseblog.blogspot.com/

Have fun!

Download updated products with zanox Web Services

mira — Fri, 03 Apr 2009 10:00:36 +0000

How to keep your product data in sync using zanox Web Services and the latest feature “Download by last modified date”. Instead of downloading the hole product data feed, you can just download the latest changes.

More Web Service code examples

Sebastian Wallroth — Fri, 13 Mar 2009 17:19:06 +0000

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 zanox Web Services Wiki. There is a special section “Quick-Start Tutorials” growing day by day. We would like to encourage you to provide some code examples to the zanox Web Service Developer community. Today we picked these three examples.

The product carrousel is a real eyecatcher written in JavaScript.

The Contextual Product Search Example needs a little more than 50 lines of code only to demonstrate a search within the 57 million products of the zanox data base.

The PHP SOAP Account browser showcases the usage of the payment, the report and the adspace resources.

Best of all: these examples are fully functional. Download them, modify the code and bring your monetization 2.0 ideas into being.

How to create dynamic ads using zanox contextual product search

Daniel Neubauer — Fri, 27 Feb 2009 09:57:47 +0000

This article shows how to create dynamic admedia based on the contextual product search, which is part of the zanox Web Services. In general you can follow a server-side or client-side approach. Here we will do this client-side using JS, so all API calls are done by the visitors browser and you don’t need any serious code running on a web-server. This way it’s easy to adopt and integrate it into your next webpage-, blog- or widgets-project.

To develop a dynamic ad, we will take the following steps:

Creating zanox Web Services credentials

RESTful products resource & contextual product search

Crossdomain: Calling zanox Web Services using JSONP

Parse response data

1. Creating zanox Web Services credentials

Login to zanox, click on the new tab “Web Services BETA”. At the Web Services tab, create a new applicationId or grab an existing one. In this article, we just need the applicationId. The applicationId is responsible to get your tracking codes into the dynamic ads. You can make it public but don’t do this with your sharedKey, it’s nearly as mighty as your password.

Please note: If you don’t have an account yet, you have to register to continue. The first time using the Web Services tab, you have to press an apply for “zanox Web Services”-button and to re-enter the Web Services tab again.

2. RESTful products resource & contextual product search

zanox Web Services offer the same functionality for SOAP, REST-XML and REST-JSON, so you can choose case by case what’s matching your requirements. We’re going to use Java Script in our case, so we take the REST-JSON API. The products resource supports the simple URL parameter authentification, which allows to append the applicationId as a URL parameter. To give it a try, just type the following into your browser and replace ABC123 with your applicationId:

http://api.zanox.com/json/products?applicationid=ABC123&q=jeans

The response contains then number of products matching the query and by default shows the first 10 items. For each item there is at least name, price, description, up to three images available. In addition category and EAN if available.

The parameter “q” defines the search query. You can search for products by using a short string or a name of a product, or by using a longer text phrase for contextual matching. To specify the search, there are some more parameters like region, minPrice, maxPrice, category and programs and adspace.

Read more about the products resource in the zanox wiki:

http://wiki.zanox.com/en/Products_Resource#GET:_Contextual_product_search

3. Crossdomain: Calling zanox Web Services using JSONP

In our client-side scenario, the API calls to api.zanox.com are done by the browser of the visitors of your website. To support this scenario, zanox Web Services support JSONP. You just pass the name of a Java Script callback handler function as a parameter when calling the zanox Web Services. The JSON result is wrapped into a Java Script function call.

The idas is to implement the handler function and perform the API-call as a script refenrence from your web page:

< script src="http://api.zanox.com/json/products?applicationid=ABC123&q=jeans&callback=handler" > < / script >

The response will be a call of a function name “handler” and look like this:

handler(...json result of the query…);

To make it more dynamically, you can use the following helper function to add a script reference to your website:

function addScript(url) {
var script = document.createElement(“script”);
script.src = url + ‘&t=’+new Date().getMinutes();
script.type = “text/javascript”;
document.getElementsByTagName(“head”)[0].appendChild(script);
}

Using this helper function, all the functionality of the contextual product search is already implemented in JS:

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;
if (adspace) url += ‘&adspace=’ + adspace;
if (region) url += ‘&region=’ + region;
if (programs) url += ‘&programs=’ + programs;
if (category) url += ‘&category=’ + category;
if (page) url += ‘&page=’ + page;
if (items) url += ‘&items=’ + items;
if (minPrice) url += ‘&minPrice=’ + minPrice;
if (maxPrice) url += ‘&maxPrice=’ + maxPrice;
if (callback) url += ‘&callback=’ + callback;
if (q) url += ‘&q=’ + q; addScript(url);
}

Read more about the Java Script helper functions and examples at: http://wiki.zanox.com/en/JavaScript_Client_Library

4. Parse response data

In order to render the product search response, we have to access the product Items inside of the JSON response. You can just use the following lines of code:

function handler(data) {
if (data.productsResult) {
var productItems = data.productsResult.productItem;

for (var i = 0; i < productItems.length; i++) {
var productItem = productItems[i];
//..do something with productItem
}

}
}

So have fun with this code snippets, I hope this helps you creating widgets and gives you some ideas of integrating our contextual product search into your websites. Feel free to comment some of your implementations in our blog.

zanox PHP API Client released

dka — Fri, 26 Sep 2008 06:59:05 +0000

In order to use the zanox Web Services with PHP zanox released a PHP API Client Toolkit.

To accelerate your development efforts we provide a PHP API Client that you can download and use to simplify monetization of your application.

Please see the wiki for how to install and use this official zanox PHP API client.

Getting Started Tutorials online

dka — Sun, 20 Jul 2008 15:28:44 +0000

Dear Developers,
those of you which haven’t yet started to monetize their traffic and online resources with zanox webservices can now start immediately by using one of our freshly released Getting Started Tutorials.

They are intended to newbies on webservices. Examples for PHP/Rest and Lasso/Rest are included already. SOAP-Examples will follow soon.

So get started now! Develop your applications with the zanox webservices.