Skip to content

Reporting API

The Reporting API allows Publishers to retrieve performance metrics for their AdGem applications. The query can be customized using fields, groupings and filters in the request url to return data. Please note that all metrics are reported in EST (GMT-5), and currency is reported in USD.

Requirements

Before you Begin

  • Must have an active AdGem account
  • Must have an property to your account
  • Please contact your account manager to utilize the reporting API.

Steps

  1. Generate and Retrieve API Key
  2. Authentication
  3. Prepare Request URL

Step 1 - Generate and Retrieve API Key

  1. Login to your AdGem Dashboard. Navigate to the Reporting API page*.
  2. Generate your API key by clicking the green “+” button at the top of the page (pictured below).
  3. Copy the API key generated in the input field to be used in all future requests. Please note, you will not get another opportunity to view/copy the API key without requiring a refresh of the token.

* If the Reporting API navigation option is not present in your dashboard contact your account manager to request access to utilize the reporting API


Step 2 - Authentication

All requests must include the API key and application type in the header of the request. Please use a GET response to the following endpoint: https://dashboard.adgem.com/v1/report 

https://dashboard.adgem.com/v1/report

'Accept' : "application/json"
'Authorization' : "Bearer < REPLACE WITH YOUR ACCESS TOKEN >"


Step 3 - Prepare Request URL

All requests should be sent using ‘GET’ method to the endpoint listed below and must include the proper authorization headers outlined above. 

https://dashboard.adgem.com/v1/report

Use the request parameters outlined in the table below to customize the data returned in the response.

GET https://dashboard.adgem.com/v1/report

Request Parameters:

Field Name Field Type Notes
group_by Array of Strings REQUIRED FIELD. Options are app_id, date, platform, country, and offer
date_range Object REQUIRED FIELD. Needs the start_date and end_date properties with the value being in ‘Y-m-d H:i:s’ format. Example: ‘2019-11-31 11:54:06’ would be the valid representation of October 31st, 2019 at 11:54:06 PM.
fields Array of Strings An array of fields that you’d like returned in the response. Options are app_id, app_name, country_name, platform_name, date, offer_name, dau (Daily Active Users), payout, offerwall_loads, gross_clicks, distinct_clicks, conversions, ctr (Click Through Rate), cr (Conversion Rate), and ecpm (Effective Cost Per Mille)
filter_by Array of Strings Options are app_id, platform, and country. Note: the strings in the array passed in to country must be the ISO 3166 Alpha-2 code. Please refer to Wikipedia for more details
apps Array of integers The ID’s of the app you would like data on. Requires app_id in the filter_by field to function correctly. Requires app_id in the filter_by field to function correctly
platforms Array of Strings The platforms you would like data on. Requires platform in the filter_by field to function correctly
countries Array of Strings The country short code you would like data on. Requires country in the filter_by field to function correctly

Response Body:

Please note that these are the default fields that are returned in the response.

The following table contains the response fields returned by default. To return specific fields, customize the query url using the fields parameter as outlined in the table above.

Field Name Field Type Notes
app_id integer The ID of your app on AdGem
date String
app_name String The name of your app on AdGem
offer_wall_loads integer
clicks integer Gross clicks
distinct_clicks integer Unique clicks
conversions integer
impressions integer
instruction_views integer Number of offer instruction views
payout double The publisher payout amount
count integer Daily active users count
ctr double Click-through rate
cver double/string Conversion Rate
ecpm double Effective cost per mile

Miscellaneous Details

  • Timezone: All measures are reported in Eastern Standard Timezone (EST)
  • USD Currency: All currency measures are reported in USD
  • Recommended Usage & Rate Limits: Please note the datasource which this API is querying is updated on a 30 minute interval and we recommend usage act in accordance with that knowledge. Max usage rates are 10 requests per minute.

Example Requests:

Default Report Request URL: 

GET https://dashboard.adgem.com /v1/report?group_by[]=app_id&group_by[]=date&date_range[start_date]=2019-12-29%2000%3A00%3A00&date_range[end_date]=2019-12-30%2000%3A00%3A00

Accept: application/json
Authorization: Bearer < REPLACE WITH TOKEN >

Customized Report Request URL: Contains groups, filters, and specific fields to return in the response. 

GET https://dashboard.adgem.com /v1/report?fields[]=app_id&fields[]=date&fields[]=app_name&fields[]=count&group_by[]=app_id&group_by[]=date&filter_by[]=app_id&apps[]=13&date_range[start_date]=2019-12-29%2000%3A00%3A00&date_range[end_date]=2019-12-30%2000%3A00%3A00

Accept: application/json
Authorization: Bearer < REPLACE WITH TOKEN >