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:
- 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.
- 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.
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
|
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 thetimeFrame
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 |