Advertiser Reporting API
Use Cases
The API described on this page is for fetching reports.
All monetary values are in dollars as decimals.
Please allow for long timeouts for each request as responses are not instant.
Reports are updated approximately every half hour, so requesting the same report within that timeframe will return the same result set.
API
Method: GET
Base URL: https://api.adgatemedia.com/v1/advertiser/report
Required Parameters
start_date
Start date of report in mm-dd-YYYY format
String
01-30-2020
end_date
End date of report in mm-dd-YYYY format
String
02-01-2020
Optional Parameters
Timezones
The report data can be retrieved in a custom timezone. Example: &data[]=offer_id&timezone=America/Los_Angeles
Note: If timezone is not provided in the request, the data will be retrieved in America/Los_Angeles timezone by default.
Data Column Grouping
The data columns to display and group data by.
Example: &data[]=offer_id&data[]=country.
offer_id
Prodege's internal offer ID (default)
offer_event
Offer event name*
country
Country
is_mobile
Is mobile or tablet traffic (boolean)
browser
Browser
os
Operating System
device
Device
(*) Offer events: because the offer event is only known upon conversion and does not apply to clicks, the click counts are duplicated for each offer event. For example, if an offer gets 10 clicks, each offer event in the report will display 10 clicks. Furthermore, if there are only clicks and no conversions, expect the offer_event to be null. We may remove results without conversions in the future.
Date Interval Grouping
Group response by specific time periods.
Example: &intervals[]=m&intervals[]=dt
m
Month
dt
Day
h
Hour
Filters
Request to only include reports that match certain criteria. Separate multiple values for each filter using commas.
Example: &filters[offer_id]=11045,112340
offer_id
Filter by specified offer IDs
country
Filter by specified countries using ISO standards (&filters[country]=US,GB)
is_mobile
Filter by mobile/tablet traffic. Use 0 for desktop traffic, 1 for mobile/tablet traffic only.
Additional Data
Optional data that can be added to the response.
Example: &options[]=impressions&options[]=cpm
offer_impressions
Include offer impression data
user_impressions
Include user impression data
cpm
Include cost per thousand impressions
app_id
Include App ID value in addition to offer ID
offer_wall_position_avg
Include the average position of an offer on the offer wall for the given data set
Response
Note that country abbreviations use the ISO standard, e.g. GB instead of UK.
Sample Response
{
"data": {
"results": [
{
"offer_id": 15506,
"offer_name": "Survey Sample Savings - Burger King (US) (Incentive)",
"is_mobile": true,
"unique_impressions_count": 91879,
"unique_clicks_count": 34268,
"conversions_count": 3105,
"costs": 5589,
"cpm": 60.83,
"rpc": 0.16,
"country_code": "US"
},
{
"offer_id": 17192,
"offer_name": "Lifesum iPhone Burst (US) (Incentive)",
"is_mobile": true,
"unique_impressions_count": 25527,
"unique_clicks_count": 7552,
"conversions_count": 3442,
"costs": 1652.16,
"cpm": 64.72,
"rpc": 0.21,
"country_code": "US"
}
],
"totalColumns": {
"unique_impressions_count": 117406,
"unique_clicks_count": 41820,
"conversions_count": 6547,
"cost": 7241.16,
"cpm": 61.68,
"calculated_cpc": 0.17,
}
},
"status": "success"
}Errors
Request limit: Only 3 requests are allowed per minute.
{
"data": [],
"status": "error",
"error": {
"code": 400,
"message": "Three reporting API requests have been made with this API key. Please try again in a minute."
}
}Invalid Data: Invalid data field(s) were requested [ &data[]=wrong ].
{
"data": [],
"status": "error",
"error": {
"code": 400,
"message": "Invalid Data column(s) [ &data[]=wrong ]."
}
}Invalid Interval: Invalid interval is passed [ &interval[]=month ].
{
"data": [],
"status": "error",
"error": {
"code": 400,
"message": "Invalid interval [ &interval[]=month ]."
}
}Invalid Options: Invalid option(s) are passed [ &option[]=random ].
{
"data": [],
"status": "error",
"error": {
"code": 400,
"message": "Invalid option [ &option[]=random ]."
}
}Invalid Filters: Invalid filters requested [ &filters['wrong_key']=check ].
{
"data": [],
"status": "error",
"error": {
"code": 400,
"message": "Invalid filters [ &filters['wrong_key']=check ]."
}
}Invalid Timezone: Invalid timezone is passsed [ &timezone[]=wrongtimezone ].
{
"data": [],
"status": "error",
"error": {
"code": 400,
"message": "Timezone wrongtimezone is invalid. Please use a valid timezone."
}
}Maximum groupings: Maximum 5 data grouping columns are allowed.
{
"data": [],
"status": "error",
"error": {
"code": 400,
"message": "Maximum 5 groupings (data + intervals) can be applied at a time."
}
}Response Fields
Each row may contain any of the following keys and values, depending on the options passed to the API:
offer_id
Prodege's internal offer ID
offer_name
Campaign Name
app_id
Offer's App ID (from Apple AppStore or Google Play)
country_code
2-letter ISO Country Code
is_mobile
Whether the device used was mobile/tablet (boolean)
browser
Browser used to click the offer
os
Operating system of the device by which offer was clicked
offer_event
Offer event name used as an identifier internally
offer_event_label
Offer event label used in the offer walls
device
Device by which offer was clicked
m
Month
dt
Day of month
h
Hour
unique_clicks_count
Click count, uniques by IP within the time interval requested
conversions_count
Number of conversion within the time span requested
unique_impressions_count
Impressions count, uniques by IP within the time interval requested
costs
Payout
rpc
Cost per click
cpm
Earnings per thousand impressions.
offer_wall_position_avg
Include the average position of an offer on the offer wall for the given data set
totalColumns
The calculations here apply only to the current result set.
unique_impressions_count: Total unique impressions.
unique_clicks_count: Total unique clicks.
conversions_count: Total conversions.
cost: Total payout.
calculated_cpc: Average cost per click.
cpm: Average earnings per thousand impressions.
More Examples
URL: https://api.adgatemedia.com/v1/advertiser/report?api_key=APIKEY&start_date=11-22-2020&end_date=12-22-2020&data[]=country&data[]=offer_id
This request will group data by (offer_id, country) for the last month. The result set will be empty if there was no traffic during this time period.
Example Response
{
"data": {
"results": [
{
"offer_id": 15506,
"offer_name": "Survey Sample Savings - Burger King (US) (Incentive)",
"unique_clicks_count": 34347,
"conversions_count": 3116,
"costs": 5608.8,
"rpc": 0.16,
"country_code": "US"
},
{
"offer_id": 17192,
"offer_name": "Lifesum iPhone Burst (US) (Incentive)",
"unique_clicks_count": 7552,
"conversions_count": 3442,
"costs": 1652.16,
"rpc": 0.21,
"country_code": "US"
}
],
"totalColumns": {
"unique_clicks_count": 41899,
"conversions_count": 6558,
"cost": 7260.96,
"calculated_cpc": 0.17,
}
},
"status": "success"
}URL: https://api.adgatemedia.com/v1/advertiser/report?api_key=APIKEY&start_date=2018-01-01&end_date=2018-01-02&options[]=impressions&intervals[]=dt&options[]=cpm&filters[offer_id]=16146,15506
This request will get a date report that includes impressions and CPM data only for offers 16146 and 15506, grouped by day. Rows for each corresponding day are returned even if there was no traffic during that time frame.
Example Response
{
"data": {
"results": [
{
"dt": "2015-06-02",
"unique_impressions_count": 23976,
"unique_clicks_count": 8595,
"conversions_count": 721,
"costs": 1297.8,
"cpm": 54.13,
"rpc": 0.15
},
{
"dt": "2015-06-01",
"unique_impressions_count": 1632,
"unique_clicks_count": 286,
"conversions_count": 12,
"costs": 21.6,
"cpm": 13.24,
"rpc": 0.07
}
],
"totalColumns": {
"unique_impressions_count": 25608,
"unique_clicks_count": 8881,
"conversions_count": 733,
"cost": 1319.4,
"cpm": 51.52,
}
},
"status": "success"
}Last updated
Was this helpful?