Ad Monetization API Reference

Follow
Avatar
Vaibhav Gupta
Updated

Learn how to run ad monetization reports through the Singular API. This reporting API only reports the data Singular pulls from networks for ad monetization analytics. If you have Singular's SDK collecting ad revenue, please reference the Reporting API. 

To learn about configuring your account for ad monetization, see Setting Up Ad Monetization Reporting.

 

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