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:

  • The API key is automatically generated to the registered mail ID after an account is created with InMobi.
  • Additionally, at the account level visit your Admin panel > Account Settings > 5th drop-down is API key > Generate API key.
  • You can also validate to check if the API key is correctly linked to your account as shown below:

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

    • 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 <a href="https://api.inmobi.com/v1.0/generatesession/generate"> https://api.inmobi.com/v1.0/generatesession/gener...</a>  
-H "userName:#######" 
-H "secretKey:########"

    Sample Request 2 

    curl -v <a href="https://api.inmobi.com/v1.0/generatesession/generate"> https://api.inmobi.com/v1.0/generatesession/gener...</a>  
-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":">"}]}}'
<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

    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
    adUnitType Group the reports by ad unit 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 >, <, =, >=, <=
    adImpressions Long Filter by impressions rendered E.g., 100 >, <, =, >=, <=
    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

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

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

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

    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.