advertiser-api-guides | Reporting API Guide

Introduction

This document contains information required to use the InMobi Advertiser Reporting APIs.

The Advertiser Reporting API is an intuitive interface for premium advertisers 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 is InMobi's clients who use the Advertiser Reporting features.

API Key

An API key is required for all in-bound 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 should be provided in every API request. The API version is a part of the request URL.

For example, the URL: https://api-sandbox.inmobi.com/v1.0/reporting/adve... contains the version v1.0.

Going Live

Execute the sample code provided in the following sections in the sandbox for testing. To go live, replace the sandbox URL with the URL provided for going live. For example, https://api.inmobi.com/v1.0/reporting/advertiser

Rate Limits

API usage is rate limited to protect InMobi from abuse. Clients are allowed to make limited calls in a given hour. The policy affects the APIs in the following ways.

Note: Rate limit is not applicable to the beta program.

Default Rate Limiting

Every API request is authenticated. The default rate limit is applied on a combination of inbound IP and API Key to a maximum of 100 calls per hour. If the rate limit exceeds, the API will return an error response. For more information on the error, refer to the section Error Codes.

Feature Rate Limiting

Some API-based feature requests have additional feature limits in conjunction with the default rate limits. Requests to such features will count against both the feature and default rate limit. If either limit exceeds, the API will return an error response. For more information on the error, refer to the section Error Codes.

Note: To avoid exceeding the rate limit, it is recommended that you store the frequently used responses on the local machine.

Getting Started

The following subsections provide information to get started with integrating the Advertiser Reporting APIs.

API Formats and Naming Conventions

The Advertiser Reporting APIs conform to the REST specifications. To get the response in a format of your choice, change the format extension for any request. JSON, XML, and CSV are the formats supported. The format is specified by appending a json/xml/csv extension at the end of the URL.

Naming conventions for elements throughout the API will appear in camel-case. For example − groupBy, filterBy.

Data Formats

The following sections explain the formats used to represent data.

Date and Time

Any reference to date and time in the API request and response is defined in the following format: YYYY-MM-DD and hh:mm:ss.

Note: All the time formats are returned in UTC. The API developer should set the time as required.

Depending on the timeFrame and granularity, the dates are represented in the format as 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

Reporting Format

Today

Hourly

YYYY-MM-DD hh:mm:ss

Yesterday

Hourly/Daily

YYYY-MM-DD hh:mm:ss

<= last 6 months

Daily

YYYY-MM-DD

<= last 12 months

Monthly

YYYY-MM-DD (Starting date of the month)

Currency

Any reference to currency is represented as a string containing decimal values. No location specific format is applied to decimal values. For example, value 1554.67.

Note: The only currency supported in the application is USD.

Request Headers

Following are the required headers for requesting a valid session.

Request Headers

Description

userName

Username of your InMobi account.

password

Password of your InMobi account.

secretKey

The API Key issued by InMobi.

accountId

The 32-character string, which 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.

Parameters Required to Generate Reports

Reports are generated based on parameters including mode, metrics, groupBy, and timeFrame. The report data is filtered and sorted using filterBy, orderBy, and orderType parameters.

mode

The value of mode can either be "event" or "request". By default, the value is set to "request"

For more information on Request Mode Reporting, see here.

metrics

Data is collected for metric parameters and aggregated in columns requested in groupBy.

Parameter

Description

impressions

Aggregate of all impressions served

clicks

Aggregate of all clicks recorded

costPerClick

The average bid across the campaign/ad group/ad.

CTR

Click through rate across the campaign/ad group/ad

adSpend

Aggregate spend for all clicks recorded.

conversions

Aggregate of all downloads recorded.

costPerConversion

Cost per download calculated for the downloads recorded.

BilledClicks

Aggregate of all billed clicks.

Note: Metrics will be aggregated for every unique combination of groupBy parameters.

groupBy

The groupBy parameters define data columns in the requested report.

Parameter

Description

date

Date when the data is aggregated

account

Name and Id of the account

campaign

The name and ID of the campaign.

adGroup

Name, ID, Landing Page and App Id of the ad-group.

ad

Name and ID of the ad.

country

Target country

manufacturer

Target manufacturers

platform

Target platforms

adFormat

Type of ad.

adFormatGroup

The ad format group to which the ad belongs.

deviceType

Specifies if the ad is shown on a smartphone or a tablet.

Site

Reporting by blinded site id, only for site inclusion ad groups.

Concept

Reporting based on concept Ids. Only for appographic targeted adgroups.

Note: The request can contain the maximum possible combination of date, campaign, adGroup, ad, country, and location/manufacturer/platform/carrier. However, reports cannot be generated with a request containing the combination of location/manufacturer/platform/carrier alone.

timeFrame

The timeFrame parameter defines the date range for which the report is requested.

The format to be used when requesting a report for a specific number of days is YYYY-MM-DD : YYYY-MM-DD.

Note: timeFrame is mandatory for every report requested. If the timeFrame is not specified or is entered in an invalid format, the API will return an error response. For more information on the error, refer to the section Error Codes.

If date is requested in groupBy, the granularity is applied as shown in the following matrix.

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

filterBy

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

accountId

IN

String

accountName

LIKE

String

campaignId

IN

String

campaignName

LIKE

String

adGroupId

IN

String

adGroupName

LIKE

String

adId

IN

String

adName

LIKE

String

country

IN

String

manufacturer

IN

String

platform

IN

String

impressions

<, >, <=, >=, <>

Numeric

clicks

<, >, <=, >=, <>

Numeric

costPerClick

<, >, <=, >=, <>

Numeric

CTR

<, >, <=, >=, <>

Numeric

adSpend

<, >, <=, >=, <>

Numeric

conversions

<, >, <=, >=, <>

Numeric

costPerConversion

<, >, <=, >=, <>

Numeric

adFormatId

IN

String

adFormatGroupId

IN

String

billedClicks

<, >, <=, >=, <>

Numeric

orderBy and orderType

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.

orderType

Parameter

Ascending

asc

Descending

desc

Note: If data requested is large, you can paginate the response using length and offset in your request. For this case, please ensure that the orderby is done by date.

Data Policy

The API interprets the granularity based on:

  • groupBy
  • timeFrame

Granularity Based on groupBy Columns

Granularity for the groupBy columns is as shown in the table below:

groupBy/ Granularity

Hourly

Daily

Monthly

date

account

campaign

adGroup

ad

adFormat

adFormatGroup

country

manufacturer

carrier

platform

concept

site

Note: If no data is available for the requested parameters timeFrame and groupBy, this API will send a blank response.

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

Timeframe

Granularity

Auto Correction

Today

Hourly

Current Hour

Yesterday

Hourly/Daily

N.A.

<= last 6 months

Daily

Today

<= last 12 months

Monthly

Current Month

Note: If your request overlaps any of the schedules in timeFrame, then the API returns the greater of the granularity applicable. Depending on the granularity, the timeFrame is auto corrected in the response. For example, if the data requested spans to the previous 5 months, then the response will be consolidated on a monthly basis. In addition, the response will exclude the current week’s data and auto-corrects the timeFrame to the previous week.

It is recommended that the timeFrame sent in the API requests follow the specifications defined in the parameters required to Generated Reports section, to obtain accurate data.

Register for InMobi Account

You must first create an InMobi Account to be able to use the Advertiser Reporting features. If you do not have an InMobi Account, click here to register.

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

Request 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-sandbox.inmobi.com/v1.0/generatesessio...

Response

Sample JSON

		<code>
{
"error": false,
"respList": [
{
"@xsi.type": "sessionObject",
"accountId": "4028####2b18####012b####e676####",
"sessionId": "aef7####6aec####8f81####d5b####"
}
]
}
		

Sample XML

		<code>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<respListxmlns: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>
		

Sample APIs

The following sections provide information on the various advertiser reporting APIs along with sample code snippets.

Requesting a Report

URL: https://api-sandbox.inmobi.com/v1.0/reporting/adve...

Supported Formats: JSON/XML

Sample JAVA Code Snippet

		<code>
public static void getAdvReport() {
PostMethod method = new PostMethod("https://api.inmobi.com/v1.0/reporting/advertiser.json");
String getReportJson = "{\"reportRequest\": {\"timeFrame\":\"2012-08-08:2012-08-10\",\"groupBy\":[\"campaign\",\"date\"],\"orderBy\":[\"date\"]}}";
try {
StringRequestEntityreqEntity = new StringRequestEntity(getReportJson, "application/json", "UTF-8");
method.setRequestEntity(reqEntity);
method.setRequestHeader("Content-Type", "application/json");
method.setRequestHeader("accountId", "4028******676001c");
method.setRequestHeader("secretKey", "7736*****c7cda534");
method.setRequestHeader("sessionId", "89f22******1842ff");
HttpClient client = new HttpClient();
client.executeMethod(method);
String response = method.getResponseBodyAsString();
System.out.println(response);
} catch (Exception e) {
e.printStackTrace();
} 
}
		

Note: The getReportJson changes based on the parameters passed.

JSON Structure

		<code>
{
"reportRequest": 
{
"metrics": [
<list of metrics>
],
"groupBy": [
<list of groupBy>
],
"timeFrame": <start date:end date>,
"orderBy": [
<list of orderBy>
],
"orderType": <asc/desc>
}
}
		

Sample JSON

Request

		<code>
{
"reportRequest": {
"metrics": [
"clicks",
"costPerClick",
"impressions",
"adSpend",
"CTR"
],
"groupBy": [
"date",
"country",
"manufacturer"
],
"timeFrame": "2011-07-02:2011-09-13",
"orderBy": [
"clicks"
],
"orderType": "desc"
}
}
		

Response

		<code>
{
"error": false,
"respList": [
{
"@xsi.type": "advertiserReportResponse",
"adSpend": 0.02,
"CTR": 1.69,
"clicks": 6,
"conversions": 0,
"costPerClick": "0.00",
"costPerConversion": "0.00",
"country": "USA",
"date": "2011-07-04 00:00:00",
"impressions": 355,
"manufacturer": "Huawei"
},
{
"@xsi.type": "advertiserReportResponse",
"adSpend": 0.01,
"CTR": 1.52,
"clicks": 3,
"conversions": 0,
"costPerClick": "0.00",
"costPerConversion": "0.00",
"country": "USA",
"date": "2011-07-04 00:00:00",
"impressions": 198,
"manufacturer": "LG"
}
]
}
		

Sample XML

		<code>
<?xml version="1.0" encoding="UTF-8"?>
<response>
<error>false</error>
<respListxmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="advertiserReportResponse">
<adSpend>0.02</adSpend>
<CTR>1.69</CTR>
<clicks>6</clicks>
<conversions>0</conversions>
<costPerClick>0.00</costPerClick>
<costPerConversion>0.00</costPerConversion>
<country>USA</country>
<date>2011-07-04 00:00:00</date>
<impressions>355</impressions>
<manufacturer>Huawei</manufacturer>
</respList>
<respListxmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="advertiserReportResponse">
<adSpend>0.01</adSpend>
<CTR>1.52</CTR>
<clicks>3</clicks>
<conversions>0</conversions>
<costPerClick>0.00</costPerClick>
<costPerConversion>0.00</costPerConversion>
<country>USA</country>
<date>2011-07-04 00:00:00</date>
<impressions>198</impressions>
<manufacturer>LG</manufacturer>
</respList>
</response>
		

Use Case: Requesting a Report for the Last Three Days

The following sample JSON helps you to request a report for the last three days.

Request

		<code>
{
"reportRequest": {
"timeFrame": "2012-08-08:2012-08-10",
"groupBy": [
"campaign",
"date"
],
"orderBy": [
"date"
]
}
}
		

Reponse

		<code>
{
"error": false,
"respList": [
{
"adSpend": 1.033,
"CTR": 6.25,
"campaignId": "40c5933****************bea6da0",
"campaignName": "campaign-1",
"clicks": 1,
"conversions": 0,
"costPerClick": 0.03,
"costPerConversion": "0.00",
"date": "2012-08-08 00:00:00",
"impressions": 16
},
{
"adSpend": 0.033,
"CTR": 6.25,
"campaignId": "40c5933****************bea6da0",
"campaignName": "campaign-1",
"clicks": 1,
"conversions": 0,
"costPerClick": 0.03,
"costPerConversion": "0.00",
"date": " 2012-08-09 00:00:00",
"impressions": 16
},
{
"adSpend": 0.72,
"CTR": 1.86,
"campaignId": "40c5933****************bea6da0",
"campaignName": "campaign-1",
"clicks": 1,
"conversions": 0,
"costPerClick": 0.03,
"costPerConversion": "0.00",
"date": " 2012-08-10 00:00:00",
"impressions": 215
}
]
}
		

Use Case: Requesting a Report for the Last Three Months

The following sample JSON helps you to request a report for the last three months.

Request

		<code>
{
"reportRequest": {
"timeFrame": "2012-05-01:2012-08-01",
"groupBy": [
"campaign",
"date"
],
"orderBy": [
"date"
]
}
}
		

Response

		<code>
{
"error": false,
"respList": [
{
"adSpend": 1.033,
"CTR": 6.25,
"campaignId": "40c5933****************bea6da0",
"campaignName": "campaign-1",
"clicks": 1,
"conversions": 0,
"costPerClick": 0.03,
"costPerConversion": "0.00",
"date": "2012-05-01 00:00:00",
"impressions": 16
},
{
"adSpend": 0.033,
"CTR": 6.25,
"campaignId": "40c5933****************bea6da0",
"campaignName": "campaign-1",
"clicks": 1,
"conversions": 0,
"costPerClick": 0.03,
"costPerConversion": "0.00",
"date": " 2012-05-01 00:00:00",
"impressions": 16
},
{
"adSpend": 0.72,
"CTR": 1.86,
"campaignId": "40c5933****************bea6da0",
"campaignName": "campaign-1",
"clicks": 1,
"conversions": 0,
"costPerClick": 0.03,
"costPerConversion": "0.00",
"date": " 2012-05-01 00:00:00",
"impressions": 215
}
]
}
		

Use Case: Requesting a Report with Filters

The following sample JSON helps you to request a report using filters.

Request

		<code>
{
"reportRequest": {
"metrics": [
"clicks",
"costPerClick",
"impressions",
"adSpend",
"CTR"
],
"groupBy": [
"date",
"country",
"manufacturer"
],
"timeFrame": "2011-02-02:2011-04-13",
"orderBy": [
"clicks"
],
"filterBy": [
{
"filterName": "clicks",
"comparator": ">",
"filterValue": [
25
]
},
{
"filterName": "campaignName",
"comparator": "in",
"filterValue": [
"campaign-1"
]
}
],
"orderType": "desc"
}
}
		

Response

		<code>
{
"error": false,
"respList": [
{
"adSpend": "0.840",
"CTR": 6.21,
"clicks": 28,
"costPerClick": 0.03,
"country": "Azerbaijan",
"date": "2011-04-01 00:00:00",
"impressions": 451,
"manufacturer": "Nokia"
}
]
}
		

Error Handling

Any error encountered while processing an API request will cause 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

		<code>
{
"error":true,
"errorList":[
{
"code":1004,
"field":"error",
"message":"API Key is mandatory",
"msgKey":"secret.required.key",
"name":"AUTH_SECRETKEY_REQUIRED"
}
]
}
		

Note: Test your code using the API Console.

Sample XML

		<code>
<?xmlversion=”1.0”encoding=”UTF-..8”?>
<response>
<error>true</error>
<errorList>
<code>1004</code>
<message>API Key is mandatory</message>
<msgKey>secret.required.key</msgKey>
<name>AUTH_SECRETKEY_REQUIRED</name>
</errorList>
</response>
		

The following sample code shows an error message when the timeFrame format is invalid.

Sample Request

		<code>
{
"reportRequest": {
"timeFrame": "2012-08-18:2012-08-10",
"groupBy": [
"campaign",
"date"
],
"orderBy": [
"date"
]
}
}
		

Sample Response

		<code>
{
"error": true,
"errorList": [
{
"code": 1017,
"message": "Invalid Time frame"
}
]
}
		

Error Codes

A list of error codes and their descriptions are given in the table below.

Error Codes

Description

1000

Unexpected error in publisher report.

1001

Username is invalid.

1002

Password is invalid.

1003

Account ID is invalid.

1004

API Key is invalid.

1005

Session ID is invalid.

1007

The request is exceeding the maximum number of outstanding sessions allowed per API Key.

1008

Authentication failed. The userName/password/secretKey sent is invalid.

1009

User is not permitted to perform the action.

1010

Session expired. Please try again with a new 'sessionId'.

1012

Invalid client request. Please ensure that the client request is properly formed.

1013

The request contains an unsupported 'metric'.

1014

The request contains an unsupported 'groupBy'.

1015

The request contains an unsupported 'orderBy'.

1017

Invalid 'timeFrame'. Please ensure that the 'timeFrame' is set properly in the request. Ensure that the timeFrame is defined in the format: YYYY-MM-DD: YYYY-MM-DD

1021

The requested service is not available.

1023

The request contains an unsupported 'orderType'.

1024

Invalid 'accountId'. Please ensure that the ‘accountId’ is set properly in the request.

1025

The request contains an unsupported 'filterBy'.

1026

Invalid ‘orderBy’. Please ensure that the ‘orderBy’ is set properly in the request.

1027

The request contains an invalid 'filterBy' on impressions. Ensure that the filter uses the supported comparators and value type.

1028

The request contains an invalid 'filterBy' on clicks. Ensure that the filter uses the supported comparators and value type.

1029

The request contains an invalid 'filterBy' on adSpend. Ensure that the filter uses the supported comparators and value type.

1030

The request contains an invalid 'filterBy' on costPerConversion. Ensure that the filter uses the supported comparators and value type.

1031

The request contains an invalid 'filterBy' on conversions. Ensure that the filter uses the supported comparators and value type.

1032

The request contains an invalid 'filterBy' on costPerClick. Ensure that the filter uses the supported comparators and value type.

1033

The request contains an invalid 'filterBy' on CTR. Ensure that the filter uses the supported comparators and value type.

1034

‘filterBy’ on impressions is not set properly

1035

‘filterBy’ on click is not set properly.

1036

‘filterBy’ on adSpend is not set properly.

1037

‘filterBy’ on costPerConversion is not set properly.

1038

‘filterBy’ on conversions is not set properly.

1039

‘filterBy’ on costPerClick is not set properly.

1040

‘filterBy’ on CTR is not set properly.

1041

The request contains an invalid 'filterBy'.

3001

Ensure that the country codes in the request are correct.

3002

Ensure that the locations in the request are correct.

3003

Ensure that the manufacturers in the request are correct.

3004

Ensure that the platforms in the request are correct.

5001

No results were found for the requested report.

5002

Invalid date format. Ensure that the date is defined in the format: YYYY-MM-DD