Ads Activity Report Alpha API

Caution: Thank you for your participation in the Ads Activity Report alpha. The Ads Activity report has no plans to exit alpha and is no longer supported. Please use the Mediation Report API instead. Learn more about the stability constraints of an alpha channel.

Important: New user roles and permissions will affect data returned by the AdMob API. Learn more

The Ads Activity report is a centralized view of your ads performance. It combines the data, metrics, and dimensions from the network report API and mediation report API as well as bidding data into a single unified report.

The Ads Activity Report API provides additional improvements from the Mediation Report API and Network Report API as seen in the table below:

	Network Report API	Mediation Report API	Ads Activity Report API
Network performance	✅	✅	✅
Waterfall performance		✅	✅
Bidding performance			✅
Mediation A/B Experiment performance			✅
Hourly reporting			✅
Report size	100k	100k	500k

Metrics, dimensions, and dimension filters

The following metrics have been added in the Ads Activity Report API in addition to many of the metrics available in the Network Report API and the Mediation Report API.

Metric	Description
BID_REQUEST	The number of requests made to the bidding ad source.
BIDS_IN_AUCTION	The number of bids submitted by the ad source that participated in bidding auctions.
WINNING_BIDS	The number of bids that won a bidding auction.

The following new dimensions are included in the Ads Activity Report API.

Dimension	Description
WEEK	The date of the first day of a week (in accordance with the language code mentioned in the localization settings) in the YYYYMMDD format (for example, "20210701"). Requests can specify only one of the DATE, WEEK, or MONTH time dimension.
HOUR	The hour in HH format in PST time. For example, "05" for 5am PST, "13" for 1pm PST. The DATE dimension must also be specified in the request. A maximum of 28 days of data is returned when the HOUR dimension is specified. Date range start dates that are greater than 28 days prior to the current date return an error.
MEDIATION_AB_TEST (experiment name)	View performance by mediation A/B test. It is mandatory to specify this if the VARIANT dimension is specified.
MEDIATION_AB_TEST_VARIANT (Variant A, Variant B)	View performance by mediation A/B test variant.

Note: All dimensions in the Ads Activity report are supported as dimension filters. For values with _NAME and _ID suffixes, the _ID suffix is the supported filter value. For example to filter on ad units, use the AD_UNIT_ID dimension as a dimension filter.

Dimension name in Mediation Report API	Dimension name in Ads Activity Report API	Description
AD_UNIT^1	AD_UNIT_ID	The unique ID of the ad unit (for example, "123456789").
	AD_UNIT_NAME	The name of the ad unit.
APP^1	APP_ID	The unique ID of the mobile application (for example, "1234567890").
	APP_NAME	The name of the app.
AD_SOURCE^1	AD_SOURCE_ID	The unique ID of the ad source (for example, "1234567890123456789".
	AD_SOURCE_NAME	The name of the ad source (for example, "AdMob Network").
AD_SOURCE_INSTANCE^1	AD_SOURCE_INSTANCE_ID	The unique ID of the ad source instance (for example, "123456789012").
	AD_SOURCE_INSTANCE_NAME	The name of the ad source instance (for example, "AdMob (default)").
MEDIATION_GROUP^1	MEDIATION_GROUP_ID	The unique ID of the mediation group (for example, "1234567890").
	MEDIATION_GROUP_NAME	The unique ID of the mediation group (for example, "AdMob (default)").

¹: See Scalars for additional information.

The following dimensions have an updated format.

Dimension name in Mediation Report API	Description in Mediation Report API	Description in Ads Activity Report API
ESTIMATED_EARNINGS	The estimated earnings of the AdMob publisher. The currency unit (USD, EUR, or other) of the earning metrics are determined by the localization setting for currency. The amount is in micros. For example, $6.50 would be represented as 6500000. Estimated earnings per mediation group and per ad source instance level is supported dating back to October 20, 2019. Third-party estimated earnings will show 0 for dates prior to October 20, 2019.	The estimated earnings of the AdMob publisher. The currency unit (USD, EUR, or other) of the earning metrics are determined by the localization setting for currency.
OBSERVED_ECPM	The third-party ad network's estimated average eCPM. The currency unit (USD, EUR, or other) of the earning metrics are determined by the localization setting for currency. The amount is in micros. For example, $2.30 would be represented as 2300000. The estimated average eCPM per mediation group and per ad source instance level is supported dating back to October 20, 2019. Third-party estimated average eCPM will show 0 for dates prior to October 20, 2019.	The average eCPM for all ads. The currency unit (USD, EUR, or other) of the earning metrics are determined by the localization setting for currency. The average eCPM per mediation group and per ad source instance level is supported dating back to October 20, 2019. OBSERVED_ECPM will show 0 for dates prior to October 20, 2019.

Scalars

The dimensions below have been updated in the Ads Activity Report API to be scalar values instead of objects. This will simplify the response and reduce complexity.

Dimensions affected in the Mediation Report API and the Network Report API:

• AD_UNIT
• APP
• AD_SOURCE
• AD_SOURCE_INSTANCE
• MEDIATION_GROUP

Sample report response data
Mediation / Network API dimension format	"AD_UNIT": { "value":"ca-app-pub-XXXXXXXXXXXXXXXXX/YYYYYYYYYY", "displayLabel": "Test ad unit name" }
AAR API dimension format	"AD_UNIT_NAME": "Test ad unit name", "AD_UNIT_ID": "ca-app-pub-XXXXXXXXXXXXXXXXX/YYYYYYYYYY"

Hourly reporting

You can now view performance by hour in the AdMob API. Hourly reporting is available for up to 28 days.

The DATE dimension must also be specified in the request to retrieve hourly data. A maximum of 28 days of data is returned when the HOUR dimension is specified. Date range start dates that are greater than 28 days prior to the current date return an error.

Key Point: Data for the most recent two hours could be incomplete.

Larger report size

The Ads Activity Report API lets you retrieve a total of 500,000 rows. For additional information, see the quotas guide.

Make a request

Follow these steps to make a request.

curl (command line)

Requests using curl

1. Load the client secrets file and generate authorization credentials.

   The first time you perform this step you'll be asked to accept an authorization prompt in your browser. Before accepting, make sure you're signed in with a Google Account that has access to the AdMob API. Your application will be authorized to access data on behalf of whichever account is currently logged in.

   For authentication and authorization, we recommend using oauth2l, a simple command-line tool for working with Google OAuth 2.0. Install oauth2l and run the command below, replacing path_to_credentials_json with a path to a credentials.json file that you download when registering your cloud application. For the first run, the command walks you through the OAuth 2.0 authorization flow. Subsequent runs refresh the token automatically.

   ~/go/bin/oauth2l header --json path_to_credentials_json \
           https://www.googleapis.com/auth/admob.readonly
   

2. Generate an ads activity report.

   curl -X POST https://admob.googleapis.com/v1alpha/accounts/pub-XXXXXXXXXXXXXXXX/adsActivityReport:generate \
        -H "Content-Type: application/json" \
        -H "$(~/go/bin/oauth2l header --json path_to_credentials_json https://www.googleapis.com/auth/admob.readonly)"  --data @- << EOF
         {
           "report_spec": {
           "date_range": {
             "start_date": {"year": 2023, "month": 1, "day": 1},
             "end_date": {"year": 2023, "month": 1, "day": 2}
           },
           "dimensions": ["DATE", "HOUR", "MEDIATION_AB_TEST", "VARIANT", "AD_SOURCE_ID", "AD_SOURCE_NAME"],
           "metrics": ["CLICKS", "BID_REQUEST","WINNING_BIDS", "IMPRESSIONS", "ESTIMATED_EARNINGS" ],
           "dimension_filters": [{"dimension": "COUNTRY", "matches_any": {"values": ["US"]}}],
           "sort_conditions": [{"metric":"CLICKS", "order": "DESCENDING"}],
           "localization_settings": {"currency_code": "USD", "language_code": "en-US"}
           }
         }
   EOF
   

   Sample response:

   {
   "rows": [
     {
       "dimensionValues": {
         "DATE": {
           "value": "20221102"
         },
         "HOUR": {
           "value": "23"
         },
         "MEDIATION_AB_TEST": {
           "value": "Mediation AB Test"
         },
         "VARIANT": {
           "value": "Variant A"
         },
         "AD_SOURCE_ID": {
           "value": "5450213213286189855"
         },
         "AD_SOURCE_NAME": {
           "value": "AdMob Network"
         }
       },
       "metricValues": {
         "CLICKS": {
           "doubleValue": 0
         },
         "BID_REQUEST": {
           "integerValue": "27"
         },
         "WINNING_BIDS": {
           "doubleValue": 0.1111111111111111
         },
         "IMPRESSIONS": {
           "integerValue": "2"
         },
         "ESTIMATED_EARNINGS": {
           "doubleValue": 0
         }
       }
     },
   {
       "dimensionValues": {
         "DATE": {
           "value": "20221102"
         },
         "HOUR": {
           "value": "23"
         },
         "MEDIATION_AB_TEST": {
           "value": "Mediation AB Test"
         },
         "VARIANT": {
           "value": "Variant B"
         },
         "AD_SOURCE_ID": {
           "value": "5450213213286189855"
         },
         "AD_SOURCE_NAME": {
           "value": "AdMob Network"
         }
       },
       "metricValues": {
         "CLICKS": {
           "doubleValue": 1
         },
         "BID_REQUEST": {
           "integerValue": "6"
         },
         "WINNING_BIDS": {
           "doubleValue": 1
         },
         "IMPRESSIONS": {
           "integerValue": "3"
         },
         "ESTIMATED_EARNINGS": {
           "doubleValue": 0.000427519
         }
       }
     }
   ]}