Learn how to run ad monetization reports through the Singular API. To learn about ad monetization, see Setting Up Ad Monetization Reporting.
Ad Monetization Reporting Endpoint (BETA)
GET | https://api.singular.net/api/v2.0/admonetization/reporting |
Usage
Use this endpoint to run custom queries in Singular for aggregated ad monetization statistics. The output format is either JSON (default) or CSV.
Sample Query
import requests
url = "https://api.singular.net/api/v2.0/admonetization/reporting"
params = {
'api_key': "<API KEY>",
'format': 'json',
'start_date': '2020-05-01',
'end_date': '2020-05-08',
'dimensions': 'source,app',
'metrics': 'ad_requests,ad_impressions,ad_revenue,ad_fill_rate',
'time_breakdown': 'all',
'country_code_format': 'iso3'
}
result = requests.get(url=url, params=params)
print result.json()
Query Parameters
Parameter | Required | Format | Description | Example |
Basic Parameters | ||||
api_key | v | String | API key provided in the Singular console | |
start_date | v | Date | ||
end_date | v | Date | ||
dimensions | String | A list of dimensions separated by commas. See Available Dimensions below. | ||
metrics | v | String | A list of metrics separated by commas. You must include at least one metric in every query. See Available Metrics below. | |
time_breakdown | v | String | How to break down the results: whether by "day", "week", "month", or "all" ("all" - do not break down by date). | |
Filtering Parameters | ||||
app | String | A comma-separated list of app names to filter the query results by. To retrieve a list of app names, use the Reporting API's Filters endpoint. | my_app1,my_app2 | |
source | String | A comma-separated list of ad networks or other media sources to filter by. To retrieve a list of ad network names, use the Reporting API's Filters endpoint. | Example: facebook,adwords | |
filters | JSON | A JSON list of filter objects where each contains a dimension, operator, and value(s). Use this parameter to apply more advanced filtering. Note that if you specify more than one filter they will be applied with an AND relation. To retrieve a full list of dimensions you can filter by and their potential values, use the Reporting API's Filters endpoint. | 'filters': '[{"dimension": "os", "operator": "in","values": [1, 4]}, {"dimension": "source", "operator": "not in", "values": ["adwords"]}]' | |
Formatting Parameters | ||||
format | String | Results format, which can either be "json" (default) or "csv" | csv | |
country_code_format | String | either "iso3" (default) or "iso" | iso3 |
Available Dimensions
- source - Monetization network
- app - Application name
- os - The user's device operating system, such as "iOS" or "Android"
- platform - The user's device platform, such as "iPhone" or "iPad". If the source does not provide breakdowns by iPhone/iPad, this field will be identical to os
- site_publid_id - The identifier of the app site in the app store (the "bundle identifier" in the Apple App Store or the "package name" in the Google Play Store).
- ad_country - The country in which the ad was served to the user
- ad_placement_id - The identifier of the placement of the ad within the app, as reported by the network
- ad_placement_name - The name of the placement of the ad within the app, as reported by the network
- ad_type_id - The ID of the ad type (also known as ad format or ad unit)
- ad_type_name - The name of the ad type (also known as ad format or ad unit). For example, "banner" or "rewarded video"
- instance_id - The ID of the targeting associated with the bid, whether it's a country, a specific app, etc. Some networks refer to this as Line Item or Mediation Group
- instance_name - of the targeting associated with the bid, whether it's a country, a specific app, etc. Some networks refer to this as Line Item or Mediation Group
- custom_dimension_id - Any custom dimensions your team has created, referred by the ID (as names may change). Use the Reporting API's Custom Dimensions endpoint to retrieve all available IDs.
Available Metrics
- ad_requests - The number of ad requests reported by the network.
- filled_ad_requests - The number of ad requests reported by the network. For networks that don't report this metric, it will be equal to ad_impressions.
- ad_fill_rate - The fill rate for the given query, i.e. (Filled Ad Requests ÷ Ad Requests) 100
- ad_impressions - Impressions reported by the Ad Network.
- video_views - Video views reported by the ad Ad Network.
- completed_video_views - Completed video views reported by the ad Ad Network.
- completed_video_view_rate - The completed video view rate for the given query - meaning completed video views divided by video views.
- ad_clicks - Clicks reported by the Ad Network.
- ad_ecpm - Effective Cost per Milli-Impressions, meaning the total ad revenue divided by the total impressions count, times one thousand.
- ad_ecpv - Effective Cost per Video View, meaning the total ad revenue divided by the total video views, times one thousand.
- ad_ecpcv - Effective Cost per Completed Video View, meaning the total ad revenue divided by the total completed video views, times one thousand.
- ad_revenue - Ad revenue reported by the Ad Network, converted to USD.
- bid_requests - Number of bid requests done to the Ad Network. Currently only available for Facebook Audience Network.
- bid_responses - Number of bid responses received from the Ad Network. Currently only available for Facebook Audience Network.
Sample Output
{
"status": 0,
"substatus": 0,
"value": {
"results": [
{
"ad_impressions": 8819347,
"end_date": "2018-07-08",
"app": "Singular",
"ad_requests": 12046598,
"ad_fill_rate": 0.856,
"ad_revenue": 972019.7813,
"source": "Vungle Publisher",
"start_date": "2018-07-01"
},
{
"ad_impressions": 8847496,
"end_date": "2018-07-08",
"app": "Singular",
"ad_requests": 12023162,
"ad_fill_rate": 0.8641,
"ad_revenue": 967907.3438,
"source": "AdColony Publisher",
"start_date": "2018-07-01"
},
{
"ad_impressions": 8794247,
"end_date": "2018-07-08",
"app": "Singular",
"ad_requests": 12041120,
"ad_fill_rate": 0.8646,
"ad_revenue": 956327.5313,
"source": "Facebook Audience Network Publisher",
"start_date": "2018-07-01"
}
]
}
}