Reporting API

From mkMob Developer Wiki
Jump to: navigation, search

This document contains information required to use the mkMob Advertiser Reporting API.

The Advertiser Reporting API is an intuitive interface for advertisers to request for reports directly with REST APIs. The following sections describe the various aspects of the API and steps involved for a successful integration.



Getting Started

You must first create an mkMob Account to be able to use the Advertiser Reporting features. If you do not have an mkMob Account, click here to register.

Get an API Key

An API Key is required to use the Advertiser Reporting API. To get an API Key, login to your Advertiser Dashboard, click the APIs tab and follow the onscreen instructions.


Usage Limits

Usage of the API is rate limited to protect mkMob's system from abuse. Clients are allowed to make limited calls in a given hour.

The default rate limit is applied on a combination of inbound IP and API Key to a maximum of 100 calls per hour. If the rate limit has been exceeded, the API will return an error with the following JSON response schema:

{
  "error": [
    {
     "errcode": 4,
     "errmsg": "Too many API calls."
    }
  ],
  "data": null
}


API Request

All API requests should be made to the following endpoint as a JSON POST request. Request body must contain only JSON string, NOT name=value pair.

https://api.mkmob.com/reporting/advertiser.asm

Request Headers

The following headers are mandatory when making an API request.

Request Headers Description
Content-Type You should pass the value as application/json
secretKey The API Key issued by mkMob.

Parameters Required to Generate Reports

Reports are generated based on parameters including metrics, reportOn, groupBy, and timeFrame. The report data is sorted using orderBy and orderType.

metrics

Parameter Description
impressions Aggregate of all served impressions.
clicks Aggregate of all recorded clicks.
CTR Click through rate across the campaign/ad group/creative.
adSpend Aggregate spend for all clicks recorded.
eCPM The cost per ad 1000 ad impression.
conversions Aggregate of all downloads/installs/actions recorded.
eCPA Cost per conversion calculated for the conversions recorded.


reportOn

The reportOn parameter tells the API if reports should be based on Campaigns, Ad Groups or Creatives.

reportOn Description Example JSON Code
campaigns Run report on ad campaigns
"reportOn": {
    "campaigns": [
        Campaign ID 1,
        Campaign ID 2,
        Campaign ID 3...
    ]
}
adGroups Run report on ad groups
"reportOn": {
    "adGroups": [
        Ad Group ID 1,
        Ad Group ID 2,
        Ad Group ID 3...
    ]
}
creatives Run report on creatives
"reportOn": {
    "creatives": [
        Creative ID 1,
        Creative  ID 2,
        Creative  ID 3...
    ]
}


groupBy

The groupBy parameters define data columns in the requested report.

Parameter Description
date Date when the data is aggregate.
campaign Name and ID of the campaign.
adGroup Name and ID of the ad group.
creative Name and ID of the creative.
country Target countries
carrier Target carriers
manufacturer Target manufacturers
platform Target platforms

Note: The request can only be grouped on a single column basis. That is, a combination of columns cannot be specified.


timeFrame

The timeFrame parameter defines the date range for which the report is requested.

The format to be used when requesting a report for a specific number of days is YYYY-MM-DD : YYYY-MM-DD.

Note: The timeFrame is mandatory for every report requested. If the timeFrame is not specified or is entered in an invalid format, the API will return an error response.


orderBy and orderType

Data can be sorted across multiple metrics and groupBy . Set the orderBy and orderType in the API request to sort the data in a specific order.

IMPORTANT: If you set groupBy to date you may also set orderBy to date. This allows you to sort your data by date. You cannot sort by date when groupBy is set to any other value.

orderType Parameter
Ascending asc
Descending desc


Sample APIs

The following sections provide examples on various API functions along with sample code snippets. The API will return data in JSON format only.

Sample PHP Code Snippet

function getAdvertiserReport() {
    $data = array(
        'reportRequest' => array(
            'metrics' => array(
                'impressions',
                'clicks',
                'adSpend',
            ),
            'reportOn' => array(
                'campaigns' => array(1451579665, 1485313951, 1459233023)
            ),
            'timeFrame' => '2011-07-02:2011-08-13',
            'groupBy' => 'campaign',
            'orderBy' => 'impressions',
            'orderType' => 'desc'
        )
    );
 
    $reportJson = json_encode($data);
    $apiKey = 'YOUR-API-KEY';  
    $options = [ 
        CURLOPT_URL => "https://api.mkmob.com/reporting/advertiser.asm",
        CURLOPT_RETURNTRANSFER => 1,
        CURLOPT_HTTPPROXYTUNNEL => TRUE,
        CURLOPT_HTTPHEADER => ["Content-Type: application/json", "secretKey: $apiKey"],
        CURLOPT_HEADER => 0,
        CURLOPT_CUSTOMREQUEST => "POST",
        CURLOPT_POSTFIELDS => $reportJson
    ];
 
    $request = curl_init();
    curl_setopt_array($request, $options);
    $_response = curl_exec($request);
    curl_close($request);
 
    echo $_response;
}

NOTE: The reportJson variable will change based on the parameters set in the $data variable.

Sample Java Code Snippet

public static void getAdvertiserReport() {
    HttpClient httpClient = new DefaultHttpClient();
 
    try {
        HttpPost request = new HttpPost("https://api.mkmob.com/reporting/advertiser.asm");
        StringEntity reportJson = new StringEntity("{\"reportRequest\":{\"metrics\":[\"impressions\",\"clicks\",\"adSpend\"],\"reportOn\":{\"campaigns\":[1451579665,1485313951,1459233023]},\"timeFrame\":\"2011-07-02:2011-08-13\",\"groupBy\":\"campaign\"}}");
        request.addHeader("Content-Type", "application/json");
        request.addHeader("Accept","application/json");
        request.addHeader("secretKey", "YOUR-API-KEY");
        request.setEntity(reportJson);
        HttpResponse response = httpClient.execute(request);
 
        // handle response here...
    } catch (Exception ex) {
        // handle exception here
    } finally {
        httpClient.getConnectionManager().shutdown();
    }
}

JSON data structure

You must use the following structure when constructing your JSON.

{
    "reportRequest": 
    {
        "metrics": [
            <list of metrics>
        ],
        "reportOn": {
            <list campaigns, ad groups or creatives IDs>
        },
        "timeFrame": <start date:end date>,
        "groupBy": <group by>,
        "orderBy": <order by>,
        "orderType": <asc/desc>
    }
}

Sample JSON

Request
{
    "reportRequest": {
        "metrics": [
            "impressions",
            "clicks",
            "CTR",
            "adSpend",
            "eCPM",
            "conversions",
            "eCPA"
        ]
        "reportOn": {
            "campaigns": [
                1451579665,
                1485313951,
                1390781339,
                1459233023
            ]
        },
        "timeFrame": "2011-07-02:2011-08-13",
        "groupBy": "date",
        "orderBy": "clicks",
        "orderType": "desc"
    }
}
Response
{
    "error": null,
    "data": [
        {
            "date": "2011-07-02",
            "impressions": 198,
            "clicks": 15,
            "CTR": 7.57,
            "adSpend": 3.50,
            "eCPM": "17.67",
            "conversions": 0,
            "eCPA": "0.00"
        },
        {
            "date": "2011-07-04",
            "impressions": 205,
            "clicks": 10,
            "CTR": 4.87,
            "adSpend": 2.50,
            "eCPM": "12.19",
            "conversions": 0,
            "eCPA": "0.00"
        },
        {
            "date": "2011-07-06",
            "impressions": 2000,
            "clicks": 8,
            "CTR": 0.4,
            "adSpend": 0.08,
            "eCPM": "0.04",
            "conversions": 0,
            "eCPA": "0.00"
        },
    ]
}


Error Handling

Any error encountered while processing an API request will cause a failure of the entire operation. The API caller has to take the responsibility of parsing the content of the response to handle errors.

Sample JSON

{
  "error": [
    {
     "errcode": <code>,
     "errmsg": <message>
    }
  ],
  "data": null
}