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

Optional Parameters

Data Column Grouping

The data columns to display and group data by.

Example: &data[]=offer_id&data[]=aff_id.

(*) 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

Filters

Request to only include reports that match certain criteria. Separate multiple values for each filter using commas.

Example: &filters[offer_id]=11045,112340

Additional Data

Optional data that can be added to the response.

Example: &options[]=impressions&options[]=cpm

Pagination

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:

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"
}

Last updated