Mintegral Reporting-API Documentation
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 |
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