# 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 | Parameter | Description | Type | Example | | ----------- | ----------------------------------------------------------------------------------------------- | ------ | ---------------------------------- | | api\_key | Your API key. Can be found on the [Reporting API page](https://prodegeads.com/client/api/keys). | 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 #### Timezones The report data can be retrieved in a custom timezone.\ \ Example: \&data\[]=offer\_id\&timezone=America/Los\_Angeles | Value | Descripion | | -------- | -------------------------------------------------------------------------------------------------------------------------------- | | timezone | [IANA](https://www.iana.org/time-zones) Timezone. A list of valid timezones can be found [here](https://nodatime.org/TimeZones). | **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\&data\[]=source | Value | Description | | ------------ | -------------------------------------------------------------------- | | 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 | | source | String representing the ID of the offer wall or publisher sub-source | | aff\_id | Publisher's internal 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 | 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) | | 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 | ### 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.

| #### More Examples **URL:** 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:** 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" } ```