The API versions system

The API includes several versions: 1, 2 and 2.1.

The version 1 will be permanently cut off at the beginning of July 2013 (i.e. the service on it will be closed and no maintenance service will be done on it). Below are the instructions to migrate to the most recent version.

As soon as the V1 is cut off, the versions system will change:

  • • No need to specify the version in your calls any more: you will get the latest version automatically.
  • Be careful: there is a new version whenever the output format changes, so it can influence your integration. But normally it will simply be some additions in the output, so no problem in general.

 

  • Example :
  • From
  • To

 

  • • If you specify a version in you calls: you will stay only on this version and not access to the new features of the latest version

 

Please note that with the V1 cut-off the category names won’t be available any more (for example: Computers, Audio_Video, Photo…).

 

Here are the tasks you have to fulfill for the shift from V1 to V2.1:

  • •  Update your urls: From searchItem (V1) to v2.1/search/offer (V2.1)
  • Example:
  •  From
  • To
  • • If you use the parameter “nb_offers” in your urls, you have to change it to nb_results
  • Example:
  • From
  • To
  • • Update your code because these parameters changed:
  • nb_products (V1) => nb_tw_objects (V2.1)
  • products (V1) => tw_objects (V2.1)
  • nb_offers (V1) => nb_results (V2.1)
  • offers (V1) => results (V2.1)

 

From V2 to V2.1

  • • Simply update your urls: From v2/search/offer (V2) to v2.1/search/offer (V2.1).
  • Example:
  • From
  • To
The Report API now allows grouping and filtering by geozone

If you run websites in multiple countries and are interested in grouping your reports per offer “geozone”, you now can you use &group=geozone.
For instance,

http://api.affinitad.com/report/v1?start=2013-04-01&end=2013-04-01&group=geozone&format=xml

will return:

<?xml version="1.0"?>
<twenga>
  <results total="3">
    <result>
      <geozone>FR</geozone>
      <impressions>213326</impressions>
      <clicks>214</clicks>
      <keywords>524991</keywords>
      <revenues>16.49</revenues>
      <ctr>0.00</ctr>
      <ecpm>0.08</ecpm>
    </result>
    <result>
      <geozone>NL</geozone>
      <impressions>178491</impressions>
      <clicks>643</clicks>
      <keywords>332192</keywords>
      <revenues>43.08</revenues>
      <ctr>0.00</ctr>
      <ecpm>0.24</ecpm>
    </result>
    <result>
      <geozone>IT</geozone>
      <impressions>784046</impressions>
      <clicks>2765</clicks>
      <keywords>1068064</keywords>
      <revenues>158.50</revenues>
      <ctr>0.00</ctr>
      <ecpm>0.20</ecpm>
    </result>
  </results>
  <totals>
    <impressions>1175863</impressions>
    <clicks>3622</clicks>
    <keywords>1925247</keywords>
    <revenues>218.07</revenues>
  </totals>
  <averages>
    <impressions>391954.33</impressions>
    <clicks>1207.33</clicks>
    <keywords>641749.00</keywords>
    <revenues>72.69</revenues>
    <ctr>0.00</ctr>
    <ecpm>0.06</ecpm>
  </averages>
</twenga>

To filter by a specific geozone, you can use the &geozone=##2-letter ISO Country Code (ISO 3166-1)## query parameter.
For instance, to get detailed statistics for United Kingdom :

http://api.affinitad.com/report/v1?start=2013-04-01&end=2013-04-11&group=day&format=json&geozone=GB

will return:

{
  "results": {
    "result": [
      {
        "date": "2013-04-11",
        "impressions": "3",
        "clicks": "0",
        "keywords": "23",
        "revenues": "0.00",
        "ctr": "0.00",
        "ecpm": "0.00"
      }
    ],
    "@attributes": {
      "total": 1
    }
  },
  "totals": {
    "impressions": "3",
    "clicks": "0",
    "keywords": "23",
    "revenues": "0.00"
  },
  "averages": {
    "impressions": "3.00",
    "clicks": "0.00",
    "keywords": "23.00",
    "revenues": "0.00",
    "ctr": "0.00",
    "ecpm": "0.00"
  }
}
The Report API now allows grouping and filtering by product

If you are interested in grouping your reports per “product” (ie Links, Widgets, …), you now can you use &group=product.
For instance,

http://api.affinitad.com/report/v1?start=2013-02-02&end=2013-03-04&group=product&format=xml

will return:

<?xml version="1.0"?>
<twenga>
  <results total="2">
    <result>
      <product>3</product>
      <impressions>62906</impressions>
      <clicks>388</clicks>
      <keywords>296713</keywords>
      <revenues>36.36</revenues>
      <ctr>0.01</ctr>
      <ecpm>0.58</ecpm>
    </result>
    <result>
      <product>1</product>
      <impressions>65198</impressions>
      <clicks>1747</clicks>
      <keywords>279311</keywords>
      <revenues>87.35</revenues>
      <ctr>0.03</ctr>
      <ecpm>1.34</ecpm>
    </result>
  </results>
  <totals>
    <impressions>128104</impressions>
    <clicks>2135</clicks>
    <keywords>576024</keywords>
    <revenues>123.71</revenues>
  </totals>
  <averages>
    <impressions>1883.88</impressions>
    <clicks>31.40</clicks>
    <keywords>8470.94</keywords>
    <revenues>1.82</revenues>
    <ctr>0.00</ctr>
    <ecpm>0.01</ecpm>
  </averages>
</twenga>

To filter by a specific product, you can use the &product=##ID## query parameter.
For instance, to get detailed statistics on your Links product :

http://api.affinitad.com/report/v1?start=2013-02-02&end=2013-02-04&group=day&format=json&product=3

will return:

{
  "results": {
    "result": [
      {
        "date": "2013-02-02",
        "impressions": "1723",
        "clicks": "10",
        "keywords": "11364",
        "revenues": "1.33",
        "ctr": "0.01",
        "ecpm": "0.77"
      },
      {
        "date": "2013-02-03",
        "impressions": "1802",
        "clicks": "18",
        "keywords": "15711",
        "revenues": "1.92",
        "ctr": "0.01",
        "ecpm": "1.07"
      },
      {
        "date": "2013-02-04",
        "impressions": "1454",
        "clicks": "16",
        "keywords": "13637",
        "revenues": "1.50",
        "ctr": "0.01",
        "ecpm": "1.03"
      }
    ],
    "@attributes": {
      "total": 3
    }
  },
  "totals": {
    "impressions": "4979",
    "clicks": "44",
    "keywords": "40712",
    "revenues": "4.75"
  },
  "averages": {
    "impressions": "1659.67",
    "clicks": "14.67",
    "keywords": "13570.67",
    "revenues": "1.58",
    "ctr": "0.00",
    "ecpm": "0.32"
  }
}
JSON Callback Example


In this post, we give an example on how to integrate an affinitAD widget using the “Json Callback” method.
The main interests of this method are:

  • ability to provide the affinitAD Web Service with a keyword to search for (using the “kw” parameter)
  • more control on the widget display (error code handling, ability to set timeout, …)

The principle is the following:

  • a call is made towards the widget API, specifying a callback function in the “callback” parameter
  • the specified js function is called with a JSON answer as parameter

Now, let’s look into that more precisely.

Calling URL

<script type="text/javascript" src="http://wtpn.twenga.##TLD##/Publisher/Api/widget
?key=##PUBLIC_KEY##
&confkey[]=##CONFIG_KEY##
&kw=##KEYWORD##
&callback=##CALLBACK_FUNCTION##"></script>

where the parameters are the following:

 

Parameter Mandatory Description
key Yes ##PUBLIC_KEY## is specific to each Publisher
confkey[] Yes ##CONFIG_KEY## identifies a given Widget
kw Yes ##KEYWORD## is the product to search for.
callback Yes ##CALLBACK_FUNCTION## is the name of the JavaScript function to which the JSON-formatted answer will be sent.

JSON Answer

##CALLBACK_FUNCTION##({
   "result": 1,
   "iframes": [{
      "confkey": "##CONFIG_KEY##",
      "html": "<iframe height="240" width="320"></iframe>

Attribute description:

Attribute Mandatory Description
result Yes 1:some offers where found. 0: an error occurred
errorCode No A numeric error code
errorMessage No A human-readable error message
iframes No a table of ‘iframe’ whose description is given below

iframe attribute description:

Attribute Mandatory Description
confkey Yes Configuration Key associated with the widget
html Yes HTML code for the iframe to be inserted in the page
twurl Yes URL pointing to a category or search page on Twenga web site

The callback function

Here is the simple callback function used on this page.

function displayWidget(json){
   if( json.result == 0 ) {
      console.log("No widget!!"); 
   } else {
      for(var i in json.iframes) {
         console.log(json.iframes[i]);
         $("#iframeContainer").html(json.iframes[i].html);
         try {
            console.log("Widget added : " + json.iframes[i].confkey);
         }
         catch(e){
         }
      }
   }
};

What does it do ? Quite simple:

  • If there’s no result (json.result == 0), we log some debug information.
  • Else, we go through all the json.iframes (in fact, there can be only one in the current release) to get its html content.
  • The content is used to replace the inner HTML of a specific div present in the page. Note that the <div id="iframeContainer"></div> initially contains an image used as a failover in case the keyword search returns no result.

Et voilà !

Now, let’s play a bit !

tld
keyword


widget.goes.here.250.250