Reporting API

Overview

The InMobi Publisher Reporting API 3.0 lets you automate downloading performance data for your apps. This topic walks you through key API features and use cases.

The publisher reporting API conforms to REST specifications and supports JSON format. To query reporting API, you need to send the API Key in secretKey.

Note

Our API endpoint for all publishers (except those originating from China) is https://api.inmobi.com/v3.0/reporting/publisher with headers "Content-Type:application/json" and "Accept:application/json".


Generating API Key

An API key is a credential generated by InMobi to access Reporting. On sign-up or new user invite, the system automatically sends a mail with an API key to the user.

 

An API Key can only be generated by the Publisher Admin of the account for him or other users. Other user roles will not be able to generate an API Key for themselves or others. Also, only Pub Admin users can reset the keys for other users within the account, other users can only reset their own API key.

Two actions that can be performed on the API Key sub-tab under the Account Settings section:

  1. Generate API Key: Creating an API key for a user for the first time.
  2. Reset API Key: Resetting API Key for a user who has previously generated an API Key.

Generate an API Key

  1. Go to My Account Account Settings.
  2. Go to the API Key tab and click Generate API Key.
  3. Select the user's email ID for which the key is required.

Reset an API Key

If you forget the previously generated API Key, you can reset it by hovering over their email ID on the API Key sub-tab.

The Publisher Admin can reset the API Key for themselves and others, while other User Roles can only reset the API Key for themselves.


Requesting a Valid Session

A valid session is required to authenticate any API request. A session is valid for 8 hours from the time of issue. An API key can be used to generate up to 15 valid sessions in 8 hours timeframe.

Sample Request

curl -v <a href="https://api.inmobi.com/v1.0/generatesession/generate"> https://api.inmobi.com/v1.0/generatesession/gener...</a>   
-H "userName:#######"  
-H "secretKey:########"

Note

The password is not mandatory for generating a valid session, but if you’ve been using it in your request, you will not be affected.

Sample Response

JSON
{
"respList": [{
"sessionId": "b8************************d31942",
"accountId": "4028cb************************14",
"subAccounts": null
}],
"error": false,
"errorList": []
}

The session can be more than 1000 characters long. It is recommended for you to take the appropriate data type.

Calling API

All data is returned in the GMT time zone. For example, this is the API call to get the impression count:

Sample Request

curl -v -X POST   
-H "Content-Type:application/json"  
-H "Accept:application/json"  
-H "accountId:14a************************9e" 
-H "secretKey: ####"  
-H "sessionId: ###"  
-d  '{"reportRequest":{"metrics":["adImpressions"],"timeFrame":"2017-07-20:2017-07-30","groupBy":["date"], "filterBy":[{ "filterName":"adImpressions", "filterValue": "300" , "comparator":">"}]}}' 
<a href="https://api.inmobi.com/v3.0/reporting/publisher"> 
https://api.inmobi.com/v3.0/reporting/publisher 
</a> 

Sample Response

{
"error": false,
"respList": [{
"adImpressions": 1786296,
"date": "2017-07-24 00:00:00"
}, {
"adImpressions": 1951438,
"date": "2017-07-25 00:00:00"
}, {
"adImpressions": 8062637,
"date": "2017-07-29 00:00:00"
}, {
"adImpressions": 11151057,
"date": "2017-07-30 00:00:00"
}, {
"adImpressions": 4190525,
"date": "2017-07-21 00:00:00"
}, {
"adImpressions": 10044183,
"date": "2017-07-27 00:00:00"
}, {
"adImpressions": 3881191,
"date": "2017-07-22 00:00:00"
}, {
"adImpressions": 9841295,
"date": "2017-07-20 00:00:00"
}, {
"adImpressions": 4605890,
"date": "2017-07-26 00:00:00"
}, {
"adImpressions": 6175605,
"date": "2017-07-28 00:00:00"
}, {
"adImpressions": 2247567,
"date": "2017-07-23 00:00:00"
}]
}

Reporting Details

The InMobi Reporting API supports CSV outputs where publishers can retrieve inventory performance data.

The inventory performance data only contains information about apps and ad units. This report includes ad requests, rendered impressions, clicks, and CTR metrics. Customers can calculate inventory fill rate based on request data.

Below are the metrics, grouping, and filtering parameters that are supported.

Metrics

Parameter Description
adRequests Aggregate of all ad requests
adImpressions Aggregate of all impressions rendered
clicks Aggregate of all clicks recorded
earnings The average earnings
servedImpressions Aggregate of all served impressions.
costPerMille eCPM value (cost per thousand impressions)
fillRate The fill rate value

Grouping

Parameter Description
country Group the reports by region
requestSlot Group the reports by the placement size (for instance 480x320)
platform Group the reports by operating system
date Date when the report is aggregated
account Group the reports by accounts (sub-accounts within the publisher’s account)
inmobiAppId Group the reports by App ID (all placements for an app)
placement placement
adUnitType Group the reports by ad unit type
integrationDirect Group reports generated by integration type

Filtering

Parameter Value Type Description Comparator
country String Filter by target country, e.,g, “South Korea” =
inmobiAppId Long Unique identifier for the app, eg., 14999472554## Filter by app id =, IN
inmobiAppName Name Filter by app name, e.g. “Horoscoper” =
placementId Long Unique identifier for a placement under the app e.g, 1478496451110. Filter by placement Id. =
placementName String Filter by placement name,e.g, “Default Interstitial Placement” =
platform String Filter by operating system e.g., IOS, ANDROID =, IN
earnings Long Filter by total earnings, e.g, 100

&gt;, &lt;, =, &gt;=, &lt;=

adImpressions Long Filter by impressions rendered E.g., 100

&gt;, &lt;, =, &gt;=, &lt;=

adUnitType String Filter by ad unit type =, IN

Pagination

Pagination is required if the resulting dataset on a request is potentially more than 5000 rows of data. We have restricted the number of data rows to 5000 on every reporting API call. Pagination can be achieved on request with the following parameters:

  1. offset (starts with ‘0’)
  2. length (number of rows to fetch, should be less than 5000)

To get the complete set of data, offset value of subsequent call should be the sum of (offset + length) on previous call. Last such call should get rows less than or equal to “length”.

"orderBy" and "orderType" must be sent in the request whenever pagination is used, to avoid duplicate records appearing in the response.

  1. "orderBy" supports the following metrics and dimensions :
    clicks, adImpressions, servedImpressions, costPerMille, fillRate, adRequests, earnings, country, platform, date, requestSlot, inmobiAppId, placement
  2. Values for "orderType" : "asc" for Ascending and "desc" for Descending

For instance: Fetching three records

Request

curl -v -X POST  
-H "Content-Type:application/json"  
-H "Accept:application/json"  
-H "accountId:4028cb************************14"  
-H "secretKey: ####"  
-H "sessionId: ####” 
-d  '{"reportRequest":{"metrics":["clicks"],"timeFrame":"2017-07-20:2017-07-30","groupBy":["country"],"offset": 0, "length": 3, "orderBy": ["clicks"], "orderType": "desc"}}'    
<a href="https://api.inmobi.com/v3.0/reporting/publisher"> 
https://api.inmobi.com/v3.0/reporting/publisher 
</a>

Response

{
  "error": false,
  "respList": [
    {
      "clicks": 8,
      "country": "Finland",
      "countryId": 105
    },
    {
      "clicks": 4,
      "country": "Suriname",
      "countryId": 290
    },
    {
      "clicks": 3,
      "country": "Belarus",
      "countryId": 142
    }
  ]
}

Note:

Building on the above example, to retrieve 13000 records, there needs to be 3 reporting calls with the following values of offset and length:

1st call : offset = 0, length = 5000
2nd call : offset = 5000, length = 5000
3rd call : offset = 10000, length = 3000


Examples

Let’s look at some examples of requests and responses with various scenarios of data.

Sample 1: Clicks and earnings for the account

Request

curl -v -X POST   
-H "Content-Type:application/json"  
-H "Accept:application/json"  
-H "accountId:14a************************9e" 
-H "secretKey: ####"  
-H "sessionId: ####” 
-d  '{"reportRequest":{"metrics":["earnings","clicks"],"timeFrame":"2017-07-20:2017-07-30"}}' 
<a href="https://api.inmobi.com/v3.0/reporting/publisher"> 
https://api.inmobi.com/v3.0/reporting/publisher 
</a>

Response

{
"error": false,
"respList": [{
"clicks": 3901721,
"earnings": 2076.485
}]
}

Sample 2: Clicks and earnings for the account group by Date

Request

 curl -v -X POST  
-H "Content-Type:application/json"  
-H "Accept:application/json" 
-H "accountId:4028cb************************14 
-H "secretKey: ####"  
-H "sessionId: ####” 
-d  '{"reportRequest":{"metrics":["earnings","clicks"],"groupBy":["date"],"timeFrame":"2017-07-20:2017-07-30"}}'   
<a href="https://api.inmobi.com/v3.0/reporting/publisher"> 
https://api.inmobi.com/v3.0/reporting/publisher 
</a>

Response

{
"error": false,
"respList": [{
"clicks": 131833,
"date": "2017-07-24 00:00:00",
"earnings": 228.166
}, {
"clicks": 145627,
"date": "2017-07-25 00:00:00",
"earnings": 231.309
}, {
"clicks": 351536,
"date": "2017-07-29 00:00:00",
"earnings": 85.275
}, {
"clicks": 563490,
"date": "2017-07-30 00:00:00",
"earnings": 148.264
}, {
"clicks": 318369,
"date": "2017-07-21 00:00:00",
"earnings": 313.458
}, {
"clicks": 773215,
"date": "2017-07-27 00:00:00",
"earnings": 76.041
}, {
"clicks": 295016,
"date": "2017-07-22 00:00:00",
"earnings": 276.296
}, {
"clicks": 471678,
"date": "2017-07-20 00:00:00",
"earnings": 314.018
}, {
"clicks": 350179,
"date": "2017-07-26 00:00:00",
"earnings": 116.173
}, {
"clicks": 332405,
"date": "2017-07-28 00:00:00",
"earnings": 69.499
}, {
"clicks": 168373,
"date": "2017-07-23 00:00:00",
"earnings": 217.987
}]
}

Sample 3: Ad Requests for a specific app ID

Request

curl -v -X POST   
-H "Content-Type:application/json"  
-H "Accept:application/json"  
-H "accountId:4028cb************************14 
-H "secretKey: ####"  
-H "sessionId: ####” 
-d  '{"reportRequest":{"metrics":["adRequests"],"timeFrame":"2017-07-20:2017-07-30","filterBy":[{ "filterName":"inmobiAppId", "filterValue": "1489455016170" , "comparator":"="}]}}'  
<a href="https://api.inmobi.com/v3.0/reporting/publisher"> 
https://api.inmobi.com/v3.0/reporting/publisher 
</a>

Response

{
"error": false,
"respList": [{
"adRequests": 179623
}]
}


Error Codes

Here is a list of possible error codes 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 is 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 an invalid group by: [List of invalid groupBys].
2023 The request contains an invalid filter by: [List of invalid filters].
2024 The filters on [List of invalid filters] contain invalid comparators. Comparators should have one of the values: [List of valid filters].
2025 The request contains an invalid filter by values for the filter by country: [List of invalid countries].
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]. The 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 the 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 the filter by manufacturer: [List of invalid manufacturers].
2034 The request contains invalid filter by values for the filter by platform: [List of invalid platforms].
2036 The from-date or to-date cannot be after today.

FAQs

1. What is the currency unit of earnings?

The earnings are reported in US dollars.

2. What is the upper limit on the number of requests per session?

There is no limit on the number of requests per session.

3. What is the upper limit on the number of sessions in a day?

You can fetch a maximum of 15 sessions in a day.

4. In case of issues or downtime, what is the usual ETA for accessing the repaired data?

Once the issue is detected, the usual ETA is 24-48 hours.

5. What is the time period of data delay?

The usual data delay is 4-5 hours. Also, InMobi follows the GMT.

6. How far back can publishers retrieve data?

6 months.

Glossary for Reporting Metrics

Metric Definition Calculation
eCPM Effective CPM: Effective cost per Mille

Total earnings /

(Total impressions *1000)
CTR

Click through rates is # of clicks your ad receives

divided by # of times your ad is shown

Total # of clicks /

(Total # of ad impressions)
Total ad requests Total # of ad requests received from publishers # of ad requests
Ad impressions served Ad impressions served by InMobi # of ad impressions served
Ad impressions rendered Ad impressions successfully viewed by the user # of ads rendered
Fill Rate The percentage of ad served from ads requested % of successful impressions / (Total # of requests)
Ad render rate The percentage of served ads rendered

# of ads rendered /

(# of ad impressions served)
Publisher Revenue Total revenue to publisher  

On This Page

Last Updated on: 13 Sep, 2024