API Documentation

zferral API


Introduction

Authentication of affiliates

API Objects

Analytics

Methods:

Examples:


All of the Analytics attribute fields are returned from GET (read) operations.

Parameters:

  • type VARCHAR(255) (Read Only) Type of ad
  • date DATE (Read Only) Analytics date
  • affiliate_id INT (Read Only) Unique id of affiliate
  • marketing_tool_id INT (Read Only) Unique id of marketing/ad
  • country VARCHAR(255) (Read Only) Country symbol
  • referer VARCHAR(255) (Read Only) Analytics referer
  • nb_impressions DECIMAL(8,2) (Read Only) Number of impressions
  • nb_clicks DECIMAL(8,2) (Read Only) Number of clicks
  • nb_events DECIMAL(8,2) (Read Only) Number of events
  • conversion DECIMAL(8,6) (Read Only) Conversion (nb_events/nb_impressions)
  • sum_commissions DECIMAL(8,2) (Read Only) Sum of commissions


Methods

list – retrieve list of analytics

URL: "https://<subdomain>.zferral.com/api/<api_key>/analytics.<format>?group_by=<group_by>"
Method: GET
Format: xml or json
Required Parameter: group_by

  • country
  • referer
  • ad_type
  • date
  • affiliate_id
  • marketing_tool_id


Optional Parameters:

  • page,
  • limit,
  • sort_by,
  • sort_type (asc,desc),
  • date_from,
  • date_to,
  • object_type (affiliate_id,marketing_tool_id),
  • object_value,
  • reward_points_type_id


Response: An array of analytics, up to 50 per page
XML and JSON example

list – Usage Example

Scenarios [examples]:

Requirements:

  • Correct <subdomain>
  • Correct <api_key>
  • Correct <group_by>
  • Returned data format <format>


  1. Scenario: Retrieves list of Monetary Analytics


    Request

    URL: "https://<subdomain>.zferral.com/api/<api_key>/analytics.<format>?group_by=<group_by>"


    Response (return status code "200 OK"):

    a) XML 

            <?xml version="1.0" encoding="UTF-8"?>
          <analyticss type="array">
            <analytics>
                <date>2010-07-29</date>
                <nb_impressions>16.00</nb_impressions>
                <nb_clicks>0.00</nb_clicks>
                <nb_events>0.00</nb_events>
                <conversion>0.000000</conversion>
                <sum_commissions>0.00</sum_commissions>
            </analytics>
            <analytics>
                <date>2010-07-28</date>
                <nb_impressions>56.00</nb_impressions>
                <nb_clicks>2.00</nb_clicks>
                <nb_events>0.00</nb_events>
                <conversion>0.000000</conversion>
                <sum_commissions>0.00</sum_commissions>
            </analytics>
            <analytics>
                <date>2010-07-27</date>
                <nb_impressions>91.00</nb_impressions>
                <nb_clicks>1.00</nb_clicks>
                <nb_events>0.00</nb_events>
                <conversion>0.000000</conversion>
                <sum_commissions>0.00</sum_commissions>
            </analytics>
          </analyticss>

    b) JSON 

            {
         "analyticss" : {
            "analytics" : {
              (...)
            },
            "analytics" : {
              (...)
            },
            "analytics" : {
              (...)
            }
        }}


  2. Scenario: Retrieves list of Non-Monetary Analytics


    Request

    URL: "https://<subdomain>.zferral.com/api/<api_key>/analytics.<format>?group_by=<group_by>&reward_points_type_id=<reward_points_type_id>"


    Response (return status code "200 OK"):

    a) XML 

            <?xml version="1.0" encoding="UTF-8"?>
          <analyticss type="array">
           <analytics>
                <date>2010-07-15</date>
                <premium_points_nb_impressions>27.00</premium_points_nb_impressions>
                <premium_points_nb_clicks>0.00</premium_points_nb_clicks>
                <premium_points_nb_events>8.00</premium_points_nb_events>
                <premium_points_conversion>29.629630</premium_points_conversion>
                <premium_points_sum_commissions>74.00</premium_points_sum_commissions>
            </analytics>
            <analytics>
                <date>2010-07-14</date>
                <premium_points_nb_impressions>15.00</premium_points_nb_impressions>
                <premium_points_nb_clicks>2.00</premium_points_nb_clicks>
                <premium_points_nb_events>4.00</premium_points_nb_events>
                <premium_points_conversion>26.666667</premium_points_conversion>
                <premium_points_sum_commissions>0.00</premium_points_sum_commissions>
            </analytics>
            <analytics>
                <date>2010-07-13</date>
                <premium_points_nb_impressions>16.00</premium_points_nb_impressions>
                <premium_points_nb_clicks>1.00</premium_points_nb_clicks>
                <premium_points_nb_events>0.00</premium_points_nb_events>
                <premium_points_conversion>0.000000</premium_points_conversion>
                <premium_points_sum_commissions>0.00</premium_points_sum_commissions>
            </analytics>
            <analytics>
                <date>2010-07-12</date>
                <premium_points_nb_impressions>16.00</premium_points_nb_impressions>
                <premium_points_nb_clicks>1.00</premium_points_nb_clicks>
                <premium_points_nb_events>2.00</premium_points_nb_events>
                <premium_points_conversion>12.500000</premium_points_conversion>
                <premium_points_sum_commissions>10.00</premium_points_sum_commissions>
            </analytics>
          </analyticss>

    b) JSON 

            {
         "analyticss" : {
            "analytics" : {
              (...)
            },
            "analytics" : {
              (...)
            },
            "analytics" : {
              (...)
            }
        }}