Method: accounts.adsActivityReport.generate

Generates Ads Activity Report based on provided specifications.

HTTP request

POST https://admob.googleapis.com/v1alpha/{parent=accounts/*}/adsActivityReport:generate

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
parent

string

Resource name of the account to generate the report for. Example: accounts/pub-9876543210987654

Request body

The request body contains data with the following structure:

JSON representation 
{
  "reportSpec": {
    object (AdsActivityReportSpec)
  }
}
Fields
reportSpec

object (AdsActivityReportSpec)

Ads activity report specification.

Response body

If successful, the response body contains data with the following structure:

Ads Activity Report API response.

JSON representation 
{
  "rows": [
    {
      object (ReportRow)
    }
  ],
  "warnings": [
    {
      object (ReportWarning)
    }
  ]
}
Fields
rows[]

object (ReportRow)

The ads activity report data from the specified publisher. At most 100000 rows will be returned from the API.
warnings[]

object (ReportWarning)

Warnings associated with generation of the report.

Authorization Scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/admob.report
  • https://www.googleapis.com/auth/admob.readonly

For more information, see the OAuth 2.0 Overview.

AdsActivityReportSpec

The specification for generating an Ads Activity report. For example, the specification to get OBSERVED_ECPM sliced by ad source and app for the 'US' and 'CN' countries can look like the following example:

{
  "dateRange": {
    "startDate": {"year": 2021, "month": 12, "day": 1},
    "endDate": {"year": 2021, "month": 12, "day": 30}
  },
  "dimensions": ["AD_SOURCE_ID", "APP_ID", "COUNTRY"],
  "metrics": ["OBSERVED_ECPM"],
  "dimensionFilters": [
    {
      "dimension": "COUNTRY",
      "matchesAny": {"values": ["US", "CN"]}
    }
  ],
  "sortConditions": [
    {"dimension":"APP_ID", order: "ASCENDING"}
  ],
  "localizationSettings": {
    "currencyCode": "USD",
    "languageCode": "en-US"
  }
}

For a better understanding, you can treat the preceding specification like the following pseudo SQL:

SELECT AD_SOURCE_ID, APP_ID, COUNTRY, OBSERVED_ECPM FROM
ADS_ACTIVITY_REPORT WHERE DATE >= '2021-09-01' AND DATE <= '2021-09-30'
AND COUNTRY IN ('US', 'CN') GROUP BY AD_SOURCE_ID, APP_ID, COUNTRY ORDER
BY APP_ID ASC;
JSON representation 
{
  "dateRange": {
    object (DateRange)
  },
  "dimensions": [
    enum (Dimension)
  ],
  "metrics": [
    enum (Metric)
  ],
  "dimensionFilters": [
    {
      object (DimensionFilter)
    }
  ],
  "sortConditions": [
    {
      object (SortCondition)
    }
  ],
  "localizationSettings": {
    object (LocalizationSettings)
  },
  "reportingTimeZone": enum (Timezone)
}
Fields
dateRange

object (DateRange)

The date range for which the report is generated.
dimensions[]

enum (Dimension)

List of dimensions of the report. The value combination of these dimensions determines the row of the report. If no dimensions are specified, the report returns a single row of requested metrics for the entire account.
metrics[]

enum (Metric)

List of metrics of the report. A report must specify at least one metric.
dimensionFilters[]

object (DimensionFilter)

List of dimension filters for the report to match rows on their dimension values. The result is an intersection of all the filters, i.e. the rows matching all the filters will be returned.
sortConditions[]

object (SortCondition)

Describes the sorting of report rows. The order of the condition in the list defines its precedence; the earlier the condition, the higher its precedence. If no sort conditions are specified, the row ordering is undefined.
localizationSettings

object (LocalizationSettings)

Localization settings of the report.
reportingTimeZone

enum (Timezone)

The timezone to use for aggregation of the statistics.

Dimension

The dimensions of the ads activity report. Dimensions are data attributes to break down or refine the quantitative measurements (metrics) by certain attributes, such as the ad format or the platform an ad was viewed on.

Enums
DIMENSION_UNSPECIFIED Default value of an unspecified dimension. Do not use.
AD_UNIT_ID The unique ID of the ad unit (for example, "123456789").
AD_UNIT_NAME The name of the ad unit.
APP_ID The unique ID of the mobile application (for example, "1234567890").
APP_NAME The name of the app.
PLATFORM Mobile OS platform of the app (for example, "Android" or "iOS") specified while creating the app on AdMob platform.
COUNTRY CLDR country code, in ISO 3166-1 alpha-2 format, of the place where the request comes from (for example, "US" or "FR"). This is a geography dimension.
DATE A date in the YYYYMMDD format (for example, "20210701"). Requests can specify only one of the DATE, WEEK or MONTH time dimensions.
MONTH A month in the YYYYMM format (for example, "202107"). Requests can specify only one of the DATE, WEEK or MONTH time dimension.
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. Need to specify DATE with it.
AD_SOURCE_ID The unique ID of the ad source /admob/api/v1/adSources (for example, "1234567890123456789".
AD_SOURCE_NAME The name of the ad source. For example, "AdMob Network".
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)").
AD_TYPE

Type of the ad (for example, "text" or "image").

Warning: The dimension is incompatible with AD_REQUESTS, MATCH_RATE because the bifurcation of these metrics isn't available by ad type.
FORMAT Format of the ad unit (for example, "banner", "native"), an ad delivery dimension.
GMA_SDK_VERSION GMA SDK version, e.g. "iOS 7.62.0". Currently, only the GMA SDK for iOS is supported.
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)").
OS_VERSION Operating system version, e.g. "iOS 13.5.1".
SERVING_RESTRICTION Restriction mode for ads serving (e.g. "Non-personalized ads").
APP_VERSION For Android, the app version name can be found in versionName in PackageInfo. For iOS, the app version name can be found in CFBundleShortVersionString.
MEDIATION_AB_TEST View performance by mediation A/B test. It is mandatory to specify this if the VARIANT dimension is specified.
VARIANT View performance by mediation A/B test variant.

Metric

The metrics of the ads activity report. Metrics are quantitative measurements indicating how the publisher's business is performing. They are aggregated from the individual ad events and grouped by the report dimensions.

Enums
METRIC_UNSPECIFIED Default value for an unset field. Do not use.
IMPRESSIONS The number of times an ad is shown to the user. The value is an integer.
CLICKS The number of times a user clicks an ad. The value is an integer.
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.
OBSERVED_ECPM

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.
AD_REQUESTS The number of requests. The value is an integer. It is determined based on the granularity dimensions/filters asked in the AdsActivityReportSpec. For example, if ad source instance is asked in the dimensions, ad source level ad requests will be returned, if mediation group or A/B testing is asked, mediation group level ad requests will be retured, otherwise, ad unit level ad requests will be returned.
MATCHED_REQUESTS The number of times an ad request is fulfilled with an ad. The value is an integer.
MATCH_RATE The ratio of matched ad requests over the total ad requests. The value is a double precision (approximate) decimal value.
SHOW_RATE The ratio of ads that are displayed over ads that are returned, defined as impressions / matched requests. The value is a double precision (approximate) decimal value.
IMPRESSION_CTR The ratio of clicks over impressions, a.k.a. click-through rate (CTR). The value is a double precision (approximate) decimal value.
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.

DimensionFilter

Describes which report rows to match based on their dimension values.

JSON representation 
{
  "dimension": enum (Dimension),

  // Union field operator can be only one of the following:
  "matchesAny": {
    object (StringList)
  }
  // End of list of possible types for union field operator.
}
Fields
dimension

enum (Dimension)

Applies the filter criterion to the specified dimension.

The following values are accepted as dimension filters: APP_ID, PLATFORM, AD_UNIT_ID, COUNTRY, DATE, WEEK, MONTH, FORMAT, AD_SOURCE_ID, AD_SOURCE_INSTANCE_ID, AD_TYPE, APP_VERSION, GMA_SDK_VERSION, MEDIATION_GROUP_ID, OS_VERSION, SERVING_RESTRICTION
Union field operator. Filter operator to be applied. operator can be only one of the following:
matchesAny

object (StringList)

Matches a row if its value for the specified dimension is in one of the values specified in this condition.

SortCondition

Sorting direction to be applied on a dimension or a metric.

JSON representation 
{
  "order": enum (SortOrder),

  // Union field sort_on can be only one of the following:
  "dimension": enum (Dimension),
  "metric": enum (Metric)
  // End of list of possible types for union field sort_on.
}
Fields
order

enum (SortOrder)

Sorting order of the dimension or metric.
Union field sort_on. Identifies which values to sort on. sort_on can be only one of the following:
dimension

enum (Dimension)

Sort by the specified dimension.
metric

enum (Metric)

Sort by the specified metric.

LocalizationSettings

Localization settings for reports, such as currency and language.

JSON representation 
{
  "currencyCode": string,
  "languageCode": string
}
Fields
currencyCode

string

Currency code of the earning related metrics, which is the 3-letter code defined in ISO 4217. The daily average rate is used for the currency conversion. Defaults to the account currency code if unspecified. It affects how monetary metrics are calculated.
languageCode

string

Language used for any localized text, such as certain applicable dimension values. The language tag defined in the IETF BCP47. Defaults to 'en-US' if unspecified.

Timezone

Describes the timezones available to use for aggregation for the statistics.

Enums
TIMEZONE_UNSPECIFIED Default value for an unset field. Do not use.
GOOGLE_TIMEZONE The Google Timezone which is America/Los Angeles.
PUBLISHER_TIMEZONE The publisher's local timezone.