Publisher Reporting API 1.1

This document provides information required to use the InMobi publisher reporting API V1.1.

The InMobi publisher reporting API is an intuitive interface for premium publishers to request for reports directly with REST APIs. The following sections describe the various aspects of the API and steps involved with successful integration.

Target Audience

The intended audience are clients of InMobi who use the Publisher Reporting features.

Getting Started

The following sections provide information on how to start with integrating the publisher reporting APIs.

This guide assumes that you already have a functioning InMobi account.

Important: The users who have signed up with InMobi using the ‘Sign up with Google’ option, please see here.

API Key

An API key is required for all inbound requests. The API key is a 32-character string generated by InMobi. This string is generated once the account is granted API access.

The API key is sent in the request header using the parameter secretKey and is verified by the system on each request.

API Versioning

The API version is provided in every API request. The API version is a part of the request URL.

For example, the URL: https://api.inmobi.com/v1.1/reporting/publisher.json contains the version v1.1

API Formats and Naming Conventions

The publisher APIs confirm to the REST specifications. To get the response in a format of your choice, change the format extension for any request. The supported formats are JSON, and XML. The format is specified by appending a json/xml extension at the end of the URL.

The naming conventions for elements throughout the API will appear in camel-case. For example, timeFrame.

Registering an API Key

To get started, you need to request for an API Key. InMobi issues the API Key on discretion. If you are interested in associating with InMobi, send a request to helpdesk@inmobi.com.

Requesting a Valid Session

Supported Formats: JSON/XML

Description: A valid session is required to authenticate any API request. A session is valid for 24-hours from the time of issue. An API Key can be used to generate up to 15 valid sessions. If the number of valid sessions exceeds 15, a response is generated with an error code.

URL: https://api.inmobi.com/v1.0/generatesession/generate

Note:

1. Request a master API key for managing multiple accounts. The master API Key is generated for the parent account and will be authorized to manage subaccounts.
2. This is a GET request.

Response

Sample JSON

{
    "error": false,
    "respList": [
        {
            "@xsi.type": "sessionObject",
            "accountId": "4028####2b18####012b####e676####",
            "sessionId": "aef7####6aec####8f81####d5b####"
        }
    ]
}
		

Sample XML

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <error>false</error>
  <respList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="sessionObject">
    <accountId>4028####2b18####012b####e676####</accountId>
    <sessionId> aef7####6aec####8f81####d5b####</sessionId>
  </respList>
</response>
		

Going Live

With the API key, you can go live by sending a correctly constructed request to the API endpoint. The API endpoint URL is provided below.

API Endpoint:

The API provides URLs to request for reports. The end point can change depending on the expected format of the response.

JSON: https://api.inmobi.com/v1.1/reporting/publisher.json

XML: https://api.inmobi.com/v1.1/reporting/publisher.xml

This section provides details on the various parameters required to generate reports.

Parameters to Generate Reports

Reports are generated based on the following parameters including metrics, groupBy, and timeFrame. Report data is filtered using Request Headers, filterBy, and sorted using orderBy and orderType parameters.

Request Headers

Following are the required headers for requesting a report:

Note: The content-type:application/json header is mandatory when posting a request to reporting API. If this is not passed, then an error is returned.

Metrics

Data is aggregated for the metric parameters specified in the query for the report. The data is further grouped based on the groupBy constraint in the query.

Note: Metrics will be aggregated for every unique combination of groupBy parameters.

Grouping Reports

The groupBy parameters define data columns in the requested report.

Date Range Reports

The timeFrame parameter defines the date range for which the report is requested. The format to be used when requesting a report is YYYY-MM-DD : YYYY-MM-DD.

Note:

• The timeFrame parameter is mandatory for every report requested. If the timeFrame is not specified, or is entered in an invalid format, then the API will return an error. The "from date" must be lesser than the "to date". For more information on the error, refer to the section Error Codes.

• All time parameters are returned in UTC. The API developer must adjust the time as required.

Depending on the timeFrame and granularity, the dates are represented in the format shown in the table below. For example, if the timeFrame in the request contains today’s date, the response contains data grouped by hour in the format YYYY-MM-DD hh:mm:ss.

Filtering Report

The filterBy parameter defines the filters to be applied to generate the report. The list of filters and its comparators is given in the table below.

Ordering Reports

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

Note: If orderBy is passed, then orderType is mandatory.

Pagination

You can use the length and offset parameters for paging through reports.

Note: The default value of 'length' is 5000, and 'offset' is 0.

Data Granularity

The API interprets the granularity based on groupBy and timeFrame.

Based on the groupBy Columns

Granularity for the groupBy columns is as shown in the table below.

Note: If no data is available for timeFrame and groupBy, then API will send a blank response.

Based on timeFrame

Granularity for timeFrame is as shown in the table below.

Note: This granularity is applicable only if the columns in groupBy include the date parameter.

It is recommended that the timeFrame sent in the API requests follow the specifications defined in the Parameters Required to Generate Reports section, to obtain accurate data.

The following section provides information on the various Publisher Reporting APIs along with sample code snippets.

Requesting a Report

Description: These APIs generate reports as requested by the user.

Supported Formats: JSON/XML

URL: https://api.inmobi.com/v1.1/reporting/publisher.json

Note: This is a POST request

Sample JAVA Code Snippet

public static void getPubReport() {
PostMethod method = new PostMethod("https://api.inmobi.com/v1.1/reporting/publisher.json");
String getReportJson = "{\"reportRequest\": {\"metrics\":[\"clicks\",\"earnings\",\"adImpressions\"],\"timeFrame\":\"2012-08-08:2012-08-10\",\"groupBy\":[\"country\",\"site\",\"date\"],\"orderBy\":[\"date\"]}}";
try {
StringRequestEntity reqEntity = new StringRequestEntity(getReportJson, "application/json", "UTF-8");
method.setRequestEntity(reqEntity);
method.setRequestHeader("Content-Type", "application/json");
method.setRequestHeader("accountId", "4028cb*********************31a9f");
method.setRequestHeader("secretKey", "523f***********************ab439");
method.setRequestHeader("sessionId", "0f**************************ebeb");
HttpClient client = new HttpClient();
                int respCode = client.executeMethod(method);
                String response = method.getResponseBodyAsString();
System.out.println(response);
        } catch (Exception e) {
e.printStackTrace();
        }
		

Note: The getReportJson changes based on the parameters.

JSON Structure

{
    "reportRequest": {
        "metrics": [
        ],
        "groupBy": [
        ],
        "timeFrame": ,
        "orderBy": [
        ],
        "orderType": <asc/desc>,
        "offset": ,
        "length": 
    }
}
		

Response

Sample JSON

{
    "error": false,
    "respList": [
        {
            "adImpressions": 3428973,
            "CTR": 0.11,
            "clicks": 3942,
            "costPerClick": 0.02,
            "earnings": "40.143",
            "siteId": "5768cba63479e2210134d78128b10adf"
        }
    ]
}
		

Sample XML

<?xml version="1.0" encoding="UTF-¬‐8" standalone="yes"?>
<response>
    <error>false</error>
    <respList xmlns:xsi="http://www.w3.org/2001/XMLSchema-¬‐instance" xsi:type="publisherReportResponse">
        <adImpressions>37122</adImpressions>
         <CTR>0.04</CTR>
         <clicks>13</clicks>
         <costPerClick>0.02</costPerClick>
         <earnings>0.17</earnings>
         <siteId>5028cba63479e2210134d78128b10a17</siteId>
         <siteName> site 1</siteName>
    </respList>
    <respList xmlns:xsi="http://www.w3.org/2001/XMLSchema-¬‐instance" xsi:type="publisherReportResponse">
         <adImpressions>0</adImpressions>
         <CTR>0.00</CTR>
         <clicks>0</clicks>
         <costPerClick>0.00</costPerClick>
         <earnings>0</earnings>
         <siteId>5768cba63479e2210134d78128b10adf </siteId>
         <siteName> site 2</siteName>
    </respList>
</response>
		

Use Case: Requesting a Report for the Last Three Days

The following sample JSON helps you request a report for the last three days with offset value as 0 and length as 3.

Request

{
    "reportRequest": {
        "metrics": [
            "clicks",
            "earnings",
            "adImpressions"
        ],
        "timeFrame": "2013-09-09:2013-09-11",
        "groupBy": [
            "country",
            "site",
            "date"
        ],
        "orderBy": [
            "date",
            "country",
            "site"
        ],
        "orderType": "asc",
        "offset": 0,
        "length": 3
    }
}
		

Note: For the above sample request the current date is 2013-09-11.

Response

{
    "error": false,
    "respList": [
        {
            "adImpressions": 1,
            "clicks": 0,
            "country": "China",
            "countryId": 164,
            "date": "2013-09-09 00:00:00",
            "earnings": 0,
            "siteId": "4028cbff36350dab01366ac81b36045e",
            "siteName": "Punjitam (Tigers vs Goats)"
        },
        {
            "adImpressions": 5,
            "clicks": 0,
            "country": "USA",
            "countryId": 94,
            "date": "2013-09-09 00:00:00",
            "earnings": 0,
            "siteId": "4028*****************e",
            "siteName": "P*****************)"
        },
        {
            "adImpressions": 3,
            "clicks": 0,
            "country": "USA",
            "countryId": 94,
            "date": "2013-09-11 00:00:00",
            "earnings": 0,
            "siteId": "4028**********************5e",
            "siteName": "P*******************)"
        }
    ]
}
		

Use Case: Requesting a Report for the Last Three Months

The following sample JSON helps you request for a report for the last three months with the default offset and length values.

Request

{
    "reportRequest": {
        "metrics": [
            "clicks",
            "earnings",
            "adImpressions"
        ],
        "timeFrame": "2013-06-01:2013-08-31",
        "groupBy": [
            "country",
            "site",
            "date"
        ],
        "orderBy": [
            "date"
        ],
        "orderType": "asc"
    }
}
		

Note: For the above sample request the current date is 2013-08-31.

Response

{
    "error": false,
    "respList": [
        {
            "adImpressions": 0,
            "clicks": 0,
            "country": "Morocco",
            "countryId": 249,
            "date": "2013-06-15 00:00:00",
            "earnings": 0,
            "siteId": "0**************************c",
            "siteName": "Y***************N"
        },
        {
            "adImpressions": 1,
            "clicks": 0,
            "country": "China",
            "countryId": 164,
            "date": "2013-06-18 00:00:00",
            "earnings": 0,
            "siteId": "0***********************c",
            "siteName": "Y****************N"
        },
        {
            "adImpressions": 1,
            "clicks": 0,
            "country": "South Korea",
            "countryId": 220,
            "date": "2013-07-07 00:00:00",
            "earnings": 0,
            "siteId": "0***********************c",
            "siteName": "Y*****************N"
        }
    ]
}
		

Use Case: Requesting a Report for the Last Six Months

The following sample JSON will help you to request a report for the last six months.

Request

{
    "reportRequest": {
        "metrics": [
            "clicks",
            "earnings",
            "adImpressions"
        ],
        "timeFrame": "2013-02-01:2013-08-31",
        "groupBy": [
            "country",
            "site",
            "date"
        ],
        "orderBy": [
            "date"
        ],
        "orderType": "asc"
    }
}
		

Response

{
    "error": false,
    "respList": [
        {
            "adImpressions": 0,
            "clicks": 0,
            "country": "Brunei Darussalam",
            "countryId": 152,
            "date": "2013-02-01 00:00:00",
            "earnings": 0,
            "siteId": "4028**********************9",
            "siteName": "h*********e"
        },
        {
            "adImpressions": 0,
            "clicks": 0,
            "country": "Spain",
            "countryId": 55,
            "date": "2013-03-01 00:00:00",
            "earnings": 0,
            "siteId": "4028**********************9",
            "siteName": "h*********e"
        },
        {
            "adImpressions": 0,
            "clicks": 0,
            "country": "Brunei Darussalam",
            "countryId": 152,
            "date": "2013-04-01 00:00:00",
            "earnings": 0,
            "siteId": "4028**********************9",
            "siteName": "h*********e"
        }
    ]
}
		

Use Case: Requesting a Report for a Year

The following sample JSON will help you request a report for one year with default offset and length values.

Request

{
    "reportRequest": {
        "metrics": [
            "clicks",
            "earnings",
            "adImpressions"
        ],
        "timeFrame": "2012-01-01:2012-12-31",
        "groupBy": [
            "country",
            "site",
            "date"
        ],
        "orderBy": [
            "date"
        ],
        "orderType": "asc"
    }
}
		

Note: For the above sample request the current date is 2012-12-31.

Response

{
    "error": false,
    "respList": [
        {
            "adImpressions": 0,
            "clicks": 0,
            "country": "Croatia",
            "countryId": 121,
            "date": "2012-07-01 00:00:00",
            "earnings": 0,
            "siteId": "4028***********************9",
            "siteName": "h********e"
        },
        {
            "adImpressions": 0,
            "clicks": 0,
            "country": "Thailand",
            "countryId": 82,
            "date": "2012-10-01 00:00:00",
            "earnings": 0,
            "siteId": "4028************************4",
            "siteName": "p********k"
        }
    ]
}
}
		

Use Case: When No Record Exists

The following sample JSON response will be returned if records are found for this request.

Request

{
    "reportRequest": {
        "metrics": [
            "clicks",
            "earnings",
            "adImpressions"
        ],
        "timeFrame": "2013-09-09:2013-09-11",
        "groupBy": [
            "country",
            "site",
            "date"
        ],
        "orderBy": [
            "date"
        ],
        "orderType": "asc"
    }
}
		

Response

{
    "error": false
}
		

Use Case: Requesting a report grouped by country and site without filters

The following sample JSON will help you to request for a report grouped by country and site without filters.

Request

{
    "reportRequest": {
        "metrics": [],
        "groupBy": [
            "site",
            "country"
        ],
        "timeFrame": "2012-01-01:2012-06-06"
    }
}
		

Response

{
  "error": false,
  "respList": [
    {
      "adRequests": 30,
      "adImpressions": 24,
      "CTR": 4.17,
      "clicks": 1,
      "costPerClick": 0.02,
      "country": "South Korea",
      "countryId": 220,
      "earnings": "0.0138779999999999992",
      "siteId": "4028**************e2740303ba",
      "siteName": "Sa*************lication"
    },
    {
      "adRequests": 5,
      "adImpressions": 0,
      "CTR": "0.00",
      "clicks": 0,
      "costPerClick": "0.00",
      "country": "Russian Federation",
      "countryId": 117,
      "earnings": 0,
      "siteId": "4028**************e2740303ba",
      "siteName": "Sa*************lication"
    },
    {
      "adRequests": 5,
      "adImpressions": 0,
      "CTR": "0.00",
      "clicks": 0,
      "costPerClick": "0.00",
      "country": "USA",
      "countryId": 94,
      "earnings": 0,
      "siteId": "4028**************e2740303ba",
      "siteName": "Sa*************lication"
    }
  ]
}
		

Use Case: Requesting a Report Grouped by Country and Site with filters

The following sample JSON will help you to request a report grouped by country and site with filters.

Request

{
    "reportRequest": {
        "metrics": [],
        "groupBy": [
            "site",
            "country"
        ],
        "timeFrame": "2012-01-01:2012-06-06",
        "filterBy": [
            {
                "filterName": "siteId",
                "filterValue": [
                    "4028*****************0303ba"
                ],
                "comparator": "in"
            }
        ]
    }
}
		

Response

{
  "error": false,
  "respList": [
    {
      "adRequests": 0,
      "adImpressions": 0,
      "CTR": "0.00",
      "clicks": 0,
      "costPerClick": "0.00",
      "country": "USA",
      "countryId": 94,
      "earnings": 0,
      "siteId": "4028*****************0303ba",
      "siteName": "Sa*************ication"
    },
    {
      "adRequests": 30,
      "adImpressions": 24,
      "CTR": 4.17,
      "clicks": 1,
      "costPerClick": 0.02,
      "country": "South Korea",
      "countryId": 220,
      "earnings": "0.0138779999999999992",
      "siteId": "4028*****************0303ba",
      "siteName": "Sa*************ication"
    }
  ]
}
		

If an error is encountered while processing an API request it causes a failure of the entire operation. The API caller has to take the responsibility of parsing the content of the response to handle errors while receiving an HTTP status code of 200 (OK).

Sample JSON

{
    "error": true,
    "errorList": [
        {
            "code": 1008,
            "message": "Account cannot be authenticated"
        }
    ]
}
		

Sample XML

<?xml version='1.0' encoding='UTF-8' standalone='yes' ?>
<response>
<error>true</error>
<errorList>
<code>1008</code>
<message>Account cannot be authenticated</message>
</errorList>
<respList></respList>
</response>
		

The following sample code shows an error message when the timeFrame format is invalid.

Sample Request

{
    "reportRequest": {
        "metrics": [
            "adImpressions",
            "clicks",
            "ctr"
        ],
        "groupBy": [
            "site",
            "country"
        ],
        "timeFrame": "2012-06-07:2012-0608"
    }
}
		

Sample Response

{
    "error": true,
    "errorList": [
        {
            "code": 2032,
            "message": "The time frame sent in the request is in an invalid format. The expected format is start date:end date( yyyy-MM-dd:yyyy-MM-dd)"
        }
    ]
}
		

Error Codes

A list of error codes and their descriptions are given in the table below.