Publisher 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/affiliate/report

Required Parameters

Parameter

Description

Type

Example

aff

Your affiliate 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

offer_id

AdGate's internal offer ID (default)

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

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

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

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

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/affiliate/report?aff=AFFID&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/affiliate/report?aff=AFFID&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"
}

Last updated