Advanced Performance Reporting

PS: You need to use Token to change the status, for more details, please check Token

Description of the time for pulling report data: The data will be available about 1.5 hours after the day. It is recommended to pull it after 1:30 am the next day. Example: Suppose you pull the data of August 1st in East Eight District, and the data can be retrieved after 1:30 am on August 2 in the East Eight District.

This chapter will introduce Advanced Performance Reporting API. You can adjust the dimension_option parameter to query specific dimensions.Calling this interface is divided into two steps:

1. First you need to set the parameter type = 1 and call the interface. The system will generate data asynchronously on the server. When the interface returns a code = 200, the data has been successfully generated.

1.1 After the request, you need to wait for the data to be generated. You can continue to make the same request with type = 1 (the Token needs to be updated) to get the data generation information.
1.2 When the interface returns code=200, it means the data has been successfully generated.
1.3 If you are retrieving the data for the current day, the data may be incomplete. The data is updated on an hourly basis, so you can wait for n hours until the data is ready, then re-request with type=1 to update data and get the newer data generation information, and then determine whether to use type=2 to update the data.
1.4 Refer to Response(type=1) for the data generation information.

2. After the data is generated, set the parameter type = 2 and call the interface again to download the data directly.

2.1 If the data has not been generated, calling the type = 2 interface will return a code other than 200.
2.2 If the data has been generated, using the type = 2 interface will directly return the file byte stream (Content-Type: application / octet-stream).
2.3 The data is separated by "\t" as columns and "\n" as rows.
2.4 The returned data is the complete data for the current request, not just the incremental data.

Request address

https://ss-api.mintegral.com/api/v2/reports/data

Request method

GET

Request example

GET /api/v2/reports/data?start_time=2024-06-01&end_time=2024-06-01&type=1&dimension_option=Offer
HTTP/1.1 Host: ss-api.mintegral.com

Request Parameter

Fields	Type	Explanations	Default Value	Examples
timezone Optional	string	Timezone	"+8"	"+8"
start_time	string	The start time of the requested data, in the format YYYY-mm-dd. Only supports querying the data of the last half year.	—	"2020-02-01"
end_time	string	End time of the requested data, in the format YYYY-mm-dd. The end and start time spans no more than 7 days.	—	"2020-02-03"
dimension_option	string	Enum field: "Offer", "Campaign", "CampaignPackage", "Creative", "AdType", "Sub", "Package", "Location", "Endcard", "AdOutputType". Separate with commas for multiple fields. dimension_option=>"Offer", Segment data by Offer ID, Offer Name, UUID; dimension_option=>"Campaign", Segment data by Campaign ID; dimension_option=>"CampaignPackage", Segment data by Campaign Package Name; dimension_option=>"Creative", Segment data by Creative ID, Creative Name; dimension_option=>"AdType", Segment data by Ad Type; dimension_option=>"Sub", Segment data by mtgid(Sub ID, Unique id for publisher); dimension_option=>"Package", Segment data by Sub Package Name; dimension_option=>"Location", Segment data by Location; dimension_option=>"Endcard", Segment data by Endcard ID, Endcard Name; dimension_option=>"AdOutputType", Segment data by Ad Output Type; It is not support requesting data with following combinations: Creative & Sub Creative & Package Creative & time_granularity = hourly Endcard & Sub Endcard & Package Endcard & time_granularity = hourly	-	"Offer,Location"
time_granularity Optional	string	Segment data by hour or date. Enum field: "hourly", "daily".	"daily"	"hourly"
type Optional	int	type => 1, pull data request to get data status of current request condition. type => 2, download the data.	1	1

The file headers (fields) returned(type=2)

headers (fields)	Type	Explanations	Examples
Date	int	Date	20220418
Timestamp	int	Timestamp Request with time_granularity = "hourly"	1650270348
Offer Id	int	Offer ID Request with dimension_option contains "Offer"	73332
Offer Uuid	string	Unique offer name generated automatically Request with dimension_option contains "Offer"	ss_xxxx_US_AND_xxx_220112_MTG
Offer Name	string	Offer name Request with dimension_option contains "Offer"	xxxx_US_AND_xxx_220112_MTG
Campaign Id	int	Campaign ID Request with dimension_option contains "Campaign"	1111
Campaign Package	string	Package name of Campaign Request with dimension_option contains "CampaignPackage"	com.xxx.yyy
Creative Id	bigint	Creative ID Request with dimension_option contains "Creative "	2222
Creative Name	string	Creative Name Request with dimension_option contains "Creative"	220301-xxx-US-MTG01.png
Ad Type	string	AD Type Request with dimension_option contains "AdType"	banner
Sub Id	string	App ID (mtgid) from publisher Request with dimension_option contains "Sub"	mtg123456
Package Name	string	Package name of App from publisher Request with dimension_option contains "Package"	com.aaa.bbb
Location	string	Location Request with dimension_option contains "Location"	US
Endcard ID	bigint	Endcard ID Request with dimension_option contains "Endcard"	3333
Endcard Name	string	Endcard NAme Request with dimension_option contains "Endcard"	EC_PL_XXXX_X
Ad Output Type	string	Ad Output Type Request with dimension_option contains "AdOutputType" "standard":Standard，"dynamic":Dynamic Included,"playable":Playable Included	standard
Currency	string	Currency Type, USD/CNY	USD
Impression	bigint	Impression	7777
Click	bigint	CLicks	88888
Conversion	bigint	Conversions	9999
Ecpm	Double	eCPM	11.11
Cpc	Double	CPC	0.03
Ctr	Double	CTR	0.3
Cvr	Double	CVR	0.1
Ivr	Double	IVR	0.05
Spend	Double	Spend	8888.8

Response(type=1)

Fields	Type	Explanations
code	int	200 => Data generation is complete, you can use type = 2 to get the data. 201 => The request was received successfully, waiting to generate data. 202 => Data is being generated. 10000 => Parameter error or insufficient permissions.
msg	string	If success, return corresponding success message. If fail, return to detailed wrong info.
data	json	If success, return to data generation information. If fail, return to detailed wrong info.
hours	int	The number of hours contained in the current data. For example, if start_time = end_time = '2024-06-01' is requested at 2024-06-01 12:00,, the result may return hours=12, because the current data contains the data from 0 to 11 o'clock, which is 12 hours.
is_complete	boolean	TRUE => Data is complete, FALSE => Data is incomplete. For example, if end_time is greater than or equal to the current date, the data may be incomplete.

Response(type=2 and return code is not 200)

Fields	Type	Explanations
code	int	203 => Did not receive the same condition request, please use type = 1 to generate a request to generate data. 204 => Data has not yet been generated, please wait for data to be generated. 205 => The data has expired ( generated data is retained for 1 month ) and is being regenerated. 10000 => Parameter error or insufficient permissions.
msg	string	error msg
data	json	return to detailed wrong info.

Response Example

{
  "code": 200,
  "msg": "success",
  "data": {
    "hours": 24,
    "is_complete": true
  }
}