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:

  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.

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