GET /2015-03-01/report/program/{programid}

Updated on
 
Returns a aggregatedReportList for the given program ID. 
 
The returned object contains aggregated data on a program's performance (clicks, leads, sales, views, true post views and commissions) filtered by time and grouped by time, adspace or admedium, for a given program and for the given time frame defined as URL parameters.
 
The example response response below gives a full list of returned values.
 
We have also developed an example Java and PHP client, which you can use for your own development or test the features of the API from the command line.
 
Getting started

In order to use this API, you will first need:

  1. Your zanox Connect ID
  2. Your zanox Secret Key
  3. The program ID

The program ID you can get from the profile page of the zanox Marketplace. The connect ID and secret key you can get in the section "Links and Tool" under "Web Services".

Once you have connect ID and secret key you can generate your signature for authentication as described in the Authentication section below.
 

Resource URL

https://advertiser.api.zanox.com/advertiser-api/2015-03-01/report/program/{programid}

 

Parameters

programid
required

URL path parameter. The ID of the program to get report for.

Value Type: Integer
Example Value: 1803

groupby
optional

Aggregates data by given property. Day and month can be used only exclusively. Adspace and admedium can be combined.

Value Type: String

Possible values: day, month, adspace, admedium

"day" will show one value per day of the selected time frame

"month" will show one value per month of the selected time frame.

"adspace" groups by publisher's adspace applied to your program

"admedium" groups the values by the advertisement material which was used to generate the values.

Default value: The data is grouped by day if groupby is not defined.

Note: Grouped by adspace (with which the publisher is applied to your program) gives also the publisher name in response as well.

fromdate
required

Earliest date in the report (inclusive).

Value Type: String

Format: yyyy-MM-dd

Example Values 2015-03-04

Note: The fromdate cannot be older than 90 days, means you can go back 90 days on maximum from now.

todate
required

todate - 1 day = last date in the report (exclusive).

Transactions of this date will not be displayed in the result (e.g. until YYYY-MM-DD 00:00:00)

Value Type: String

Format: yyyy-MM-dd

Example Values 2015-03-14

Authentication

API authentication implementation includes the connect ID, secured mhash key (signature) and the timestamp inside the HTTP header or as URL query parameters. The actual building of the signature is taken from the RFC2104 specification.

The signature is built by applying a keyed-HMAC (Hash Message Authentication Code) algorithm to the UTF-8 encoded StringToSign. The secret key has to be provided as a parameter to the keyed-HMAC method.

The signature will be valid for 30 miuntes and can be used just one time. Once you used a signature and nonce to optain data, you need to generate a new one.

Here is the simple explanation of how to generate a signature.

1
Signature = Base64( HMAC-SHA1( UTF-8-Encoding-Of( StringToSign ) ) );

The StringToSign consists of a couple of elements that are concatenated:

1
HTTP-Verb + URI + timestamp + nonce

Where:

  • HTTP Verb - GET, POST, PUT or DELETE
  • URI - The path of specific request, excluding the protocol and domain name, together with path parameters.For example, for the URL 'https://advertiser.api.zanox.com/advertiser-api/2015-03-01/report/program/1803' the URI would be '/report/program/1803'.
  • Timestamp - In GMT in the format "EEE, dd MMM yyyy HH:mm:ss GMT"
  • Nonce - A unique random string, generated at the time of request, valid once, 20 or more characters

To successfully authenticate, connect ID, timestamp, nonce and signature have to be passed either as URL query parameters or as HTTP Headers. The query parameter names are connectiddatenonce and signature respectively (line breaks added for clarity):

1
2
3
4
5
https://advertiser.api.zanox.com/advertiser-api/2015-03-01/report/program/1803
?connectid=389676F47B4F22819102E7A
&date=Mon, 02 Mar 2015 15:31:01 GMT
&nonce=D76DD6AFEFA8312136DC0CE652CD6489
&signature=5enGx16yFtljnaoVmna4bxyWCmU=

As headers, the authentication values must be set in the following way:

1
2
3
Authorization: ZXWS connectid:signature
Date: timestamp
nonce: nonce

Example Request

REST authentication information in our example is added as query parameters

Get report for program ID: 1803, group by days for the time period from 2015-02-10 to 2015-03-01

1

https://advertiser.api.zanox.com/advertiser-api/2015-03-01/report/program/1803?groupby=adspace&fromdate=2015-02-10&todate=2015-03-01&connectid=389676F47B4F22819102E7A&date=Mon,%2002%20Mar%202015%2015:31:01%20GMT&nonce=D76DD6AFEFA8312136DC0CE652CD6489&signature=5enGx16yFtljnaoVmna4bxyWCmU=

 

Please note that the displayed URL above is an example and will not work as it is because it is using an example signatue.

JSON Example Response

         {

  • programId1803,
  • programName"DemoProgram",
  • aggregatedReportList

   [

   {

  • adspace"demoPublisherCashback@zanox.com (http://demo.cashback.zanox.de/)",
  • ppcCommission0,
  • ppcCount2,
  • pplCommission15.24,
  • pplCommissionApproved15.24,
  • pplCommissionConfirmed0,
  • pplCommissionOpen0,
  • pplCommissionRejected0,
  • pplCount2,
  • pplCountApproved2,
  • pplCountConfirmed0,
  • pplCountOpen0,
  • pplCountRejected0,
  • ppsCommission883.76,
  • ppsCommissionApproved18.26,
  • ppsCommissionConfirmed16.39,
  • ppsCommissionOpen849.11,
  • ppsCommissionRejected0,
  • ppsCount43,
  • ppsCountApproved2,
  • ppsCountConfirmed: 2,
  • ppsCountOpen39,
  • ppsCountRejected0,
  • ppvCommission0,
  • ppvCount: 4,
  • tpvCount0

},

    {

  • adspace"demoPublisherBlog@zanox.com (http://demo.blog.zanox.com/)",
  • ppcCommission0,
  • ppcCount: 0,
  • pplCommission233.64,
  • pplCommissionApproved23.34,
  • pplCommissionConfirmed10.12,
  • pplCommissionOpen200.18,
  • pplCommissionRejected0,
  • pplCount23,
  • pplCountApproved2,
  • pplCountConfirmed1,
  • pplCountOpen20,
  • pplCountRejected0,
  • ppsCommission0,
  • ppsCommissionApproved0,
  • ppsCommissionConfirmed0,
  • ppsCommissionOpen: 0,
  • ppsCommissionRejected0,
  • ppsCount0,
  • ppsCountApproved0,
  • ppsCountConfirmed: 0,
  • ppsCountOpen: 0,
  • ppsCountRejected0,
  • ppvCommission0,
  • ppvCount2,
  • tpvCount0

}

   ]

        }

Java and PHP Advertiser Client

Java client and php client are available on GitHub. Clone it and follow the README file to access your program statistics easily. Remember to get the secret key and connect ID first. 

https://github.com/zanox/advertiser-api-client-java

https://github.com/zanox/advertiser-api-client-php

Resource Information

Rate Limited? No
Authentication Requires signature. See
Authentication section
Response Formats json
HTTP Methods GET
Resource family Report
Response Object aggregatedReportList
API Version 2015-03-01