Mintegral Reporting-API Documentation

Documentation
- Interface Details
  - API
- Appendix
  - Sign
  - Country
  - Ad Format
  - Examaples

Overview

The following documentation aims to provide developers with information on how to complete technical integration. Developers should complete the integration of necessary interfaces according to the below instructions.
There is currently no test environment available for external networks. Please use the interface address for verification.

Interface Details

API

Request Protocol

The interfaces involved in this documentation are subject to the HTTPS protocol. The Content-Type header in all requests is application/x-www-form-urlencoded, and the Content-Type header in all returns is application/json.

Request Method

The GET method is used to request data.

Reporting Api

Make a GET request to the following URL:
API (V1): https://api.mintegral.com/reporting/data
API (V2): https://api.mintegral.com/reporting/v2/data
The different between APIs please refer to API Diff
Request parameters:

Name	Type	Required	Description
skey	string	Yes	The advertiser’s API key for reporting and can be found by going to your account page -> API Tools -> Reporting Api
sign	string	Yes	The signature string, for the generation method please refer to: sign
time	int	Yes	The Unix timestamp of when the request was initiated, valid time is ±300 seconds
page	int	No	The page number, default is 1
limit	int	No	The maximum number of rows returned each time, default is 10000, value range: [1,10000]
start	string	No	The start time of the data, default is the day before the current query date
end	string	No	The end time of the data, default is the day before the current query date
timezone	int	No	The timezone of start date and end date, default is 8, which means GMT +08:00. And timezone should be range from -12 to 12, while -12 means GMT -12:00 and 12 means GMT +12:00.
group_by	string	No	The dimension(s) in which the report data is broken down. Available dimensions include: date, country, app_id, platform, placement_id, unit_id, bidding_type, timestamp where "timestamp" access needs to be applied for separately The default dimension is "date"
app_id	string	No	App ID used when retrieving data for a specific app, corresponds to the app ID in Mintegral’s system Multiple app ID separated by commas, such as: app_id=123,456
app_name	string	No	Expand field used for troubleshooting
app_package	string	No	Expand field used for troubleshooting
placement_id	string	No	Placement ID used when retrieving data for a specific ad placement, corresponds to the ad placement ID in Mintegral’s system Multiple placement ID separated by commas, such as: placement_id=123,456
unit_id	string	No	Unit ID used when retrieving data for a specific ad unit, corresponds to the ad unit ID in Mintegral’s system Multiple unit ID separated by commas, such as: unit_id=123,456
unit_name	string	No	Expand field used for troubleshooting
ad_format	string	No	AD format used when retrieving data for one or more ad formats, corresponds to the AD format in Mintegral’s system Multiple ad formats separated by commas, such as: ad_format=rewarded_video,native,app_wall For all valid AD formats, please refer to AD Format
bidding_type	string	No	Bidding type, corresponds to the Bidding type in Mintegral’s system. Multiple Bidding type separated by commas, such as: bidding_type=traditional,header_bidding Valid values for Bidding type: traditional, header_bidding

Responses:

Name	Type	Description
code	string	The response code OK means that the request has succeeded, any other response codes indicate abnormality
data	json array or json object	The returned data

Data Description:

Name	Type	Description
total	int	The total number of data rows
page	int	The current page number
limit	int	The maximum number of rows returned per page
start	string	Start time
end	string	End time
timezone	int	Timezone
ad_format	string	AD format
total_page	int	The total number of pages
lists	json array	Data details

Lists Description:

Name	Type	Description
date	int	The date of the current data, returned when "date" is found in "group_by"
timestamp	int	Timestamp, the hour of current data, returned when "timestamp" is found in "group_by"
app_id	int	App ID, returned when "app_id is found in "group_by"
app_name	string	App name, returned when "app_id" is found in "group_by"
app_package	string	App package name, returned when "app_id" is found in "group_by"
placement_id	int	Placement ID, returned when "placement_id" is found in "group_by"
placement_name	string	Placement Name, returned when "placement_id" is found in "group_by"
unit_id	int	Unit ID, returned when “unit_id" is found in "group_by"
unit_name	string	Unit Name, returned when "unit_id” is found in "group_by"
ad_format	string	AD format, returned when "unit_id” is found in "group_by"
platform	string	The operating system: Android, iOS or others, returned when "platform" is found in "group_by"
country	string	The country code, returned when "country" is found in “group by”. For country codes, please refer to Country
bidding_type	string	Bidding type: traditional, header_bidding, returned when "bidding_type" is found in “group by"
filled	int	Number of times filled
fill_rate	float	Fill rate
request	int	Number of requests
impression	int	Number of impressions
click	int	Number of clicks
est_revenue	float	Revenue
ecpm	float	Effective cost per mille
ctr	float	Click-Through-Rate
hb_load	int	Number of times header bidding load, returned when "bidding_type" = header_bidding or when "bidding_type" is found in "group_by"
hb_load_filled	int	Number of times header bidding load filled, returned when "bidding_type" = header_bidding or when "bidding_type" is found in "group_by"

Interface Description:

The interface can only pull up to 7 days’ worth of data in one request.
Data can be pulled from up to 60 days ago.

Response example:

    {
        "code": "ok",
        "data": {
             "total": 320,
             "start": "20190506",
             "end": "20190506",
             "timezone": 8,
             "ad_format": "",
             "page": 1,
             "limit": 100,
             "total_page": 4,
             "lists": [
                {
                    "date": 20190506,
                    "filled": 123,
                    "request": 123,
                    "impression": 123,
                    "click": 123,
                    "est_revenue": 123.26,
                    "fill_rate": 11.09,
                    "ecpm": 0.22,
                    "ctr": 0.52,
                    "hb_load": 123,
                    "hb_load_filled": 123
                }
             ]
        }
    }

Appendix

Sign

The signature string is an important identifier for integration. Developers are required to verify the use of tokens. The generation rule is: md5(SECRETmd5(time))

skey: The agreed private key, which can be found by going to your account page -> API Tools -> Report API
SECRET: The agreed private key, which can be found by going to your account page -> API Tools -> Report API -> Secret
time: The Unix timestamp of when the request was initiated, valid for ±300 seconds

Example

1. Request parameters:

$parameters = [
    'skey'=> '7e353e0f4adc628a5545b231e629ca84',
    'group_by'=> 'date,app_id,country',
    'time'=> '1557389456',
];
$secret = '99b50cfa3e2ae9ebb276f4e16e26f04b';

2. Sign generation:

md5(SECRETmd5(time)), the generated sign:

b5f74c77dce15a7ebecb73eb33cc5493

PHP Example Code:

$time = 1557389456;
$secret = '99b50cfa3e2ae9ebb276f4e16e26f04b';
$sign = md5($secret.md5($time)); // b5f74c77dce15a7ebecb73eb33cc5493

3. Request url:

https://api.mintegral.com/reporting/data?group_by=date%2Capp_id%2Ccountry&skey=7e353e0f4adc628a5545b231e629ca84&time=1557389456&sign=b5f74c77dce15a7ebecb73eb33cc5493

The SECRET of the above example is: 99b50cfa3e2ae9ebb276f4e16e26f04b

Country

For country codes, please refer to Wikipedia:https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
Use country code "OTH" to indicate other regions or countries whose data we are unable to locate due to special reasons

AD Format

AD Format(For query)	AD Format Name(For display)	Traffic type
app_wall	App Wall	Native SDK
native	Native	Native SDK & Online api
rewarded_video	Rewarded Video	Native SDK
offerwall	Offer Wall	Native SDK
interstitial	Static Interstitial	Native SDK
interstitial_video	Interstitial Video	Native SDK
new_interstitial New (View explanation and query example below)	New Interstitial	Native SDK
interactive_ads	Interactive Ads	Native SDK
sdk_banner	Banner	Native SDK
online_api_banner	Banner(Online API)	Online api
online_api_video	Online Video	Online api
full_screen_video	Fullscreen Video	JavaScript SDK
js_native_video	JS Native Video	JavaScript SDK
js_banner_video	JS Banner Video(300x250)	JavaScript SDK
splash_ad	Splash AD	Native SDK
automatic_rendering_native	Native(Auto Rendering)	Native SDK

Query Example: Data query for New Interstitial (former Interstitial Video) ad placement.

Whether to use the AD FORMAT request field	Yes, ad_format = 'interstitial_video'	Yes, ad_format = 'new_interstitial'	No
API (V1): reporting/data	Response1 example:[ { "unit_id": 1, "est_revenue": 0.5, "unit_name": "unitA", "ad_format": "interstitial_video" }, { "unit_id": 2, "est_revenue": 0.5, "unit_name": "unitB", "ad_format": "interstitial_video" } ]	Response2 example: [ { "unit_id": 1, "est_revenue": 0.5, "unit_name": "unitA", "ad_format": "new_interstitial" }, { "unit_id": 2, "est_revenue": 0.5, "unit_name": "unitB", "ad_format": "new_interstitial" } ]	same as Response1
API (V2): reporting/v2/data	same as Response2	same as Response2	same as Response2

Whether to use the AD FORMAT request field

Yes, ad_format = 'interstitial_video'

Yes, ad_format = 'new_interstitial'

API (V1): reporting/data

Response1 example:[
  {
    "unit_id": 1,
    "est_revenue": 0.5,
    "unit_name": "unitA",
    "ad_format": "interstitial_video"
  },
  {
    "unit_id": 2,
    "est_revenue": 0.5,
    "unit_name": "unitB",
    "ad_format": "interstitial_video"
  }
]

Response2 example:
[
  {
    "unit_id": 1,
    "est_revenue": 0.5,
    "unit_name": "unitA",
    "ad_format": "new_interstitial"
  },
  {
    "unit_id": 2,
    "est_revenue": 0.5,
    "unit_name": "unitB",
    "ad_format": "new_interstitial"
  }
]

same as Response1

API (V2): reporting/v2/data

same as Response2

same as Response2

same as Response2

Examples

Example 1 of requested parameters:
array (
  'end' => '20190509',
  'group_by' => 'date,app_id',
  'limit' => '200',
  'page' => '2',
  'skey' => '7e353e0f4adc628a5545b231e629ca84',
  'start' => '20190508',
  'time' => 1557484375,
)
The request url of example 1:
https://api.mintegral.com/reporting/data?end=20190509&group_by=date%2Capp_id&limit=200&page=2&skey=7e353e0f4adc628a5545b231e629ca84&start=20190508&time=1557484375&sign=e8f0529ef5e7bf91bf1360b4ba36cf8b


Example 2 of requested parameters:
array (
  'app_id' => '91458',
  'group_by' => 'date,country',
  'skey' => '7e353e0f4adc628a5545b231e629ca84',
  'start' => '20180506',
  'end' => '20190508',
  'time' => 1557484742,
)
The request url of example 2:
https://api.mintegral.com/reporting/data?app_id=91458&end=20190508&group_by=date%2Ccountry&skey=7e353e0f4adc628a5545b231e629ca84&start=20180506&time=1557484742&sign=3a546dbc0b63c6146fab86794981808b

The SECRET of the above examples is: 99b50cfa3e2ae9ebb276f4e16e26f04b