monetize | Publisher Reporting API Guide

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

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

API Endpoint:

JSON Response: https://api.inmobi.com/v3.0/reporting/publisher with headers "Content-Type:application/json" and "Accept:application/json"

Follow the simple steps and get started:

Generating an API Key

API key is a credential generated by InMobi.

Use the Account Setting section on your InMobi dashboard to generate an API key.

Please make sure that you copy and save this API key with you for any further use as it will only be visible till you are active on the screen shown above. During future logins, API key will be hidden.

Note: In case your API key is compromised, it can be generated again. However, once you generate a new API key, the previous key will be invalidated immediately.

Validating an API Key

In case you have multiple API keys with you and are not sure which one of them is active, you can validate them as shown below. Follow the steps detailed in the previous section to land on API key screen.

Requesting a Valid Session

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 in 24 hours timeframe.

Sample Request 1

curl -v https://api.inmobi.com/v1.0/generatesession/generate  
-H "userName:#######" 
-H "secretKey:########"
		

Sample Request 2

curl -v https://api.inmobi.com/v1.0/generatesession/generate  
-H "userName:#######" 
-H "password:#########" 
-H "secretKey:########"
		

Note: Password is not mandatory for generating a valid session. Although, 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": []
}
		

Calling the API

All data is returned in GMT time zone. For example, this is the API call to get 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":">"}]}}'
https://api.inmobi.com/v3.0/reporting/publisher
		

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

Following are the metrics, grouping, and filtering parameters 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

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 >, <, =, >=, <=
adImpressions Long Filter by impressions rendered E.g., 100 >, <, =, >=, <=

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”.

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}}'   
https://api.inmobi.com/v3.0/reporting/publisher
		

Response

{
"error":false,
"respList":[
{"clicks":8,"country":"Finland","countryId":105},
{"clicks":0,"country":"Suriname","countryId":290},
{"clicks":0,"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

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"}}'
https://api.inmobi.com/v3.0/reporting/publisher
		

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"}}'  
https://api.inmobi.com/v3.0/reporting/publisher
		

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":"="}]}}' 
https://api.inmobi.com/v3.0/reporting/publisher
		

Response

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

Sample 4: Earnings for a specific app name

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"],"timeFrame":"2017-07-20:2017-07-30", "filterBy":[{ "filterName":"inmobiAppName", "filterValue": "pujia" , "comparator":"="}]}}'   
https://api.inmobi.com/v3.0/reporting/publisher
		

Response

{
"error": false,
"respList": [{
"earnings": 5.282
}]
}
		

Sample 5: Country-wise earnings

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"],"timeFrame":"2017-07-20:2017-07-30","groupBy":["country"]}}'   
https://api.inmobi.com/v3.0/reporting/publisher
		

Response

{
"error": false,
"respList": [{
"country": "Republic Of Moldova",
"countryId": 269,
"earnings": 0
}, {
"country": "Macau",
"countryId": 232,
"earnings": 0.002
}, {
"country": "Burma (Myanmar)",
"countryId": 155,
"earnings": 0.005
}, {
"country": "Argentina",
"countryId": 135,
"earnings": 0
}, {
"country": "Philippines",
"countryId": 67,
"earnings": 0
}, {
"country": "Aruba",
"countryId": 137,
"earnings": 0
}, {
"country": "India",
"countryId": 11,
"earnings": 0.003
}, {
"country": "Vietnam",
"countryId": 109,
"earnings": 0
}, {
"country": "China",
"countryId": 164,
"earnings": 2075.454
}, {
"country": "Mozambique",
"countryId": 250,
"earnings": 0
}, {
"country": "Cameroon",
"countryId": 158,
"earnings": 0
}, {
"country": "Canada",
"countryId": 101,
"earnings": 0.004
}, {
"country": "United Kingdom",
"countryId": 46,
"earnings": 0.043
}, {
"country": "East Timor",
"countryId": 177,
"earnings": 0
}, {
"country": "Egypt",
"countryId": 50,
"earnings": 0
}, {
"country": "Mongolia",
"countryId": 246,
"earnings": 0
}, {
"country": "Peru",
"countryId": 265,
"earnings": 0
}, {
"country": "New Zealand",
"countryId": 119,
"earnings": 0
}, {
"country": "Mauritius",
"countryId": 242,
"earnings": 0
}, {
"country": "Hong Kong",
"countryId": 207,
"earnings": 0.007
}, {
"country": "Belarus",
"countryId": 142,
"earnings": 0
}, {
"country": "Antigua And Barbuda",
"countryId": 134,
"earnings": 0
}, {
"country": "Hungary",
"countryId": 120,
"earnings": 0
}, {
"country": "Kazakhstan",
"countryId": 217,
"earnings": 0
}, {
"country": "Greece",
"countryId": 113,
"earnings": 0
}, {
"country": "Iran, Islamic Republic Of",
"countryId": 209,
"earnings": 0
}, {
"country": "Austria",
"countryId": 110,
"earnings": 0
}, {
"country": "Singapore",
"countryId": 74,
"earnings": 0.002
}, {
"country": "Colombia",
"countryId": 165,
"earnings": 0
},
		

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. Comparators 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].
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.

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 to access 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.

Migration from Reporting API 1.1

If you are migrating from the InMobi publisher reporting API 1.1, the following fields are deprecated:

Metrics costPerClick, CTR, servedImpressions
GroupBy site, refTag, manufacturer, carrier
Filters accountId, siteId, siteName, carrier, manufacturer, refTag, requestedSlotId, platformId, clicks, CostPerClick, CTR

Note:

Access InMobi Publisher Reporting API 1.1 here.