Ad Monetization Reporting Endpoint

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

Ad Monetization API Reference