Comment on page

Advertiser Reporting API

Use Cases
 The API described on this page is for fetching reports.
All dates and data are calculated in the EST timezone.
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
Parameter
Description
Type
Example
adv
Your advertiser ID. Can be found on the Reporting API page.
Integer
60000
api_key
Your API key. Can be found on the Reporting API page.
String
941bd1fecf7e6596823b895e04df3a0c
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
Data Column Grouping
The data columns to display and group data by.
Example: &data[]=offer_id&data[]=aff_id. 
 Value
Description
aff_id
AdGate's internal ID for the publisher (source of traffic)
offer_id
 AdGate'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
tool
 AdGate Monetization Tool
s1
 SubID 1
s2
 SubID 2
s3
 SubID 3
s4
 SubID 4
s5
 SubID 5
(*) 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
 Value
Description
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
 Value
Description
offer_id
 Filter by specified offer IDs
country
 Filter by specified countries using ISO standards (&filters[country]=US,GB)
s1
 Filter by SubID 1
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
  Value
Description
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
Pagination
Parameter
Description
Type
Example
offset
Starting offset to fetch data, default is 0.
Integer
20
limit
Number of records to return in one page, default is 10,000, maximum is 20,000 records.
Integer
12000
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,
                "payout_sum": 5589,
                "cpm": 60.83,
                "conversion_rate": 0.0906,
                "ppc": 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,
                "payout_sum": 1652.16,
                "cpm": 64.72,
                "conversion_rate": 0.4558,
                "ppc": 0.21,
                "country_code": "US"
            }
        ],
        "totalColumns": {
            "unique_impressions_count": 117406,
            "unique_clicks_count": 41820,
            "conversions_count": 6547,
            "payout_sum": 7241.16,
            "cpm": 61.68,
            "ppc": 0.17,
            "conversion_rate": 0.1565
        },
        "paging": {
            "next": null,
            "prev": null
        }
    },
    "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 ]."
	}
}
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:
Key
Description
aff_id
AdGate's internal ID for the publisher (source of traffic)
offer_id
 AdGate's internal offer ID
offer_name
 AdGate's internal offer 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
device
 Device by which offer was clicked
tool_name
 Name of the monetization tool
s1
 SubID 1
s2
 SubID 2
s3
 SubID 3
s4
 SubID 4
s5
 SubID 5
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
payout_sum
 Payout
ppc
 Average payout per click
conversion_rate
 Average conversion rate, as decimal, e.g. 0.023 is 2.3%.
cpm
 Earnings per thousand impressions.
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.
conversions_rate: Average conversion rate, as decimal, e.g. 0.023 is 2.3%.
payout_sum: Total payout.
ppc: Average payout per click.
cpm: Average earnings per thousand impressions.
paging
 Links to fetch results for the next and previous page.
next: URL to fetch next page.
prev: URL to fetch previous page.
More Examples
URL: https://api.adgatemedia.com/v1/advertiser/report?adv=ADVERTISERID&api_key=APIKEY&start_date=11-22-2020&end_date=12-22-2020&data[]=country&data[]=offer_id&limit=100
This request will group data by (offer_id, country) for the last month, with a limit of 100 results per page. 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,
                "payout_sum": 5608.8,
                "conversion_rate": 0.0907,
                "ppc": 0.16,
                "country_code": "US"
            },
            {
                "offer_id": 17192,
                "offer_name": "Lifesum iPhone Burst (US) (Incentive)",
                "unique_clicks_count": 7552,
                "conversions_count": 3442,
                "payout_sum": 1652.16,
                "conversion_rate": 0.4558,
                "ppc": 0.21,
                "country_code": "US"
            }
        ],
        "totalColumns": {
            "unique_clicks_count": 41899,
            "conversions_count": 6558,
            "payout_sum": 7260.96,
            "ppc": 0.17,
            "conversion_rate": 0.1565
        },
        "paging": {
            "next": null,
            "prev": null
        }
    },
    "status": "success"
}
URL: https://api.adgatemedia.com/v1/advertiser/report?adv=ADVERTISERID&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,
                "payout_sum": 1297.8,
                "cpm": 54.13,
                "conversion_rate": 0.0839,
                "ppc": 0.15
            },
            {
                "dt": "2015-06-01",
                "unique_impressions_count": 1632,
                "unique_clicks_count": 286,
                "conversions_count": 12,
                "payout_sum": 21.6,
                "cpm": 13.24,
                "conversion_rate": 0.042,
                "ppc": 0.07
            }
        ],
        "totalColumns": {
            "unique_impressions_count": 25608,
            "unique_clicks_count": 8881,
            "conversions_count": 733,
            "payout_sum": 1319.4,
            "cpm": 51.52,
            "ppc": 0.15,
            "conversion_rate": 0.0825
        },
        "paging": {
            "next": null,
            "prev": null
        }
    },
    "status": "success"
}

APIs - Previous

Publisher Reporting API

Last modified 2yr ago

Parameter	Description	Type	Example
adv	Your advertiser ID. Can be found on the Reporting API page.	Integer	`60000`
api_key	Your API key. Can be found on the Reporting API page.	String	`941bd1fecf7e6596823b895e04df3a0c`
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`

Value	Description
aff_id	AdGate's internal ID for the publisher (source of traffic)
offer_id	AdGate'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
tool	AdGate Monetization Tool
s1	SubID 1
s2	SubID 2
s3	SubID 3
s4	SubID 4
s5	SubID 5

Value	Description
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