reporting-api | Publisher Reporting API 1.1

Introduction

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:

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.
This is a GET request.

Request Headers	Description
userName	Username of your InMobi account
password	Password of your InMobi account
secretKey	The API Key issued by InMobi

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

Requesting to Generate Reports

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:

Request Headers	Description
accountId	The 32-character string that is the unique identifier of your account.
secretKey	The API Key issued by InMobi.
sessionId	The valid session ID that is required to authenticate your request.

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.

Parameter	Description
adImpressions	Aggregate of all impressions rendered
adRequests	Aggregate of all ad requests
clicks	Aggregate of all clicks recorded
earnings	The average earnings across sites
CTR	Click through rate across the site
costPerClick	Weighted Average for cost per click for all the clicks recorded

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

Grouping Reports

The groupBy parameters define data columns in the requested report.

Parameter	Description
date	Date when the report is aggregated
account	Group the reports by accounts (sub-accounts within the publisher’s account)
site	Name and ID of the site
placement	Placement
refTag	Name of the `reftag`
country	Target country
requestSlot	The requested slot
manufacturer	Target manufacturers
platform	Targeted platforms

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.

Time Frame/Granularity	Hourly	Daily	Monthly	Quarterly
Today	√
Yesterday	√
Last 7 Days		√
Last 30 Days		√
MTD		√
Last Month		√
QTD		√
Last 3 Months		√
Last 6 Months		√
YTD			√
Last Year				√

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.

Parameter	Comparators	Value Type	Description
accountId		String
siteId		String
siteName		String
placementId		String
placementName		String	The placementName must exactly match the name of the placement. If an account contains multiple placements, the report will contain data for all placements matching this field (unless the placementId is also specified in the request). Example: If the account contains placements with names: BeforeLogin, AfterLogin, DuringLogin & Login and the report request contains a filterBy value of Login, data for the placement with the name Login will be returned and the other ignored.
country		String
manufacturer		String
refTag		String
requestSlotId		String
platform		String
platformId		String
adImpressions	<, >, <=, >=, <>, =	Numeric
clicks	<, >, <=, >=, <>, =	Numeric
costPerClick	<, >, <=, >=, <>, =	Numeric
CTR	<, >, <=, >=, <>, =	Numeric
earnings	<, >, <=, >=, <>, =	Numeric

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.

orderType	Parameter
Ascending	asc
Descending	desc

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.

groupBy/ Granularity	Hourly	Daily	Monthly	Quarterly
date	√	√	√	√
account	√	√	√	√
site	√	√	√	√
country	√	√	√	√
refTag		√	√	√
manufacturer		√	√	√
platform		√	√	√
requestSlot		√	√	√

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.

Time Frame	Granularity
Today	Hourly
Yesterday	Hourly
<= last 6 months	Daily
<= last 12 months	Monthly
> last 12 months	Quarterly

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.

Sample APIs

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"
    }
  ]
}

Error Handling

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.

Error Codes	Description
1000	Unexpected error in the publisher report.
1001	The request object is invalid.
1002	The request contains an invalid offset.
1003	The request contains an invalid length.
1004	Invalid client request. Please make sure the client request is properly formed.
2000	Account ID is missing in the request. Please pass the account ID in the request.
2001	One or more of the account IDs passed by in filter are either invalid, or you are not authorized to access their data : [List of invalid account IDs].
2021	The request contains invalid metrics : [List of invalid metrics].
2022	The request contains invalid group by : [List of invalid groupBys].
2023	The request contains invalid filter by : [List of invalid filters].
2024	The filters on [List of invalid filters] contain invalid comparators. Comprators should have one of the values : [List of valid filters].
2025	The request contains invalid filter by values for filter by country : [List of invalid countries].
2026	The request contains invalid filter by values for filter by site.
2027	The from-date cannot be after the to-date.
2028	The date passed in the request start date and/or end date has an invalid format.
2029	The request contains invalid order by(s) on : [List of invalid orderBys]. Result can only be ordered on the fields sent in metrics or group by
2030	The order type in the request is invalid. Valid values are 'asc' and 'desc'.
2031	The request contains following filters which have no filter values : [List of invalid filters]. Please provide filter values.
2032	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).
2033	The request contains invalid filter by values for filter by manufacturer : [List of invalid manufacturers].
2034	The request contains invalid filter by values for filter by platform : [List of invalid platforms].
2036	The from-date or to-date cannot be after today

reporting-api | Publisher Reporting API 1.1

Introduction

Target Audience

Getting Started

API Key

API Versioning

API Formats and Naming Conventions

Registering an API Key

Requesting a Valid Session

Going Live

API Endpoint:

Requesting to Generate Reports

Parameters to Generate Reports

Request Headers

Metrics

Grouping Reports

Date Range Reports

Filtering Report

Ordering Reports

Pagination

Data Granularity

Based on the groupBy Columns

Based on timeFrame

Sample APIs

Requesting a Report

Use Case: Requesting a Report for the Last Three Days

Use Case: Requesting a Report for the Last Three Months

Use Case: Requesting a Report for the Last Six Months

Use Case: Requesting a Report for a Year

Use Case: When No Record Exists

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

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

Error Handling

Error Codes

Based on the `groupBy` Columns

Based on `timeFrame`