inmobi-ad-tracker-iat | 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.
Note: API endpoint for all publishers (except those originating from China) is as follows: 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. There are two ways to access the API key:
Important: 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.
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:
- offset (starts with ‘0’)
- 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.
