- HTTP request
- Path parameters
- Request body
- Response body
- Authorization scopes
- MediationReportSpec
- Dimension
- Metric
- DimensionFilter
- SortCondition
- Examples
- Try it!
Generates an AdMob Mediation report based on the provided report specification. Returns result of a server-side streaming RPC. The result is returned in a sequence of responses.
HTTP request
POST https://admob.googleapis.com/v1/{parent=accounts/*}/mediationReport:generate
The URL uses gRPC Transcoding syntax.
Path parameters
Parameters | |
---|---|
parent |
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 ( |
Fields | |
---|---|
reportSpec |
Network report specification. |
Response body
The streaming response for the AdMob Mediation report where the first response contains the report header, then a stream of row responses, and finally a footer as the last response message.
For example:
[{
"header": {
"dateRange": {
"startDate": {"year": 2018, "month": 9, "day": 1},
"endDate": {"year": 2018, "month": 9, "day": 1}
},
"localizationSettings": {
"currencyCode": "USD",
"languageCode": "en-US"
}
}
},
{
"row": {
"dimensionValues": {
"DATE": {"value": "20180918"},
"APP": {
"value": "ca-app-pub-8123415297019784~1001342552",
"displayLabel": "My app name!"
}
},
"metricValues": {
"ESTIMATED_EARNINGS": {"decimal_value": "1324746"}
}
}
},
{
"footer": {"matchingRowCount": 1}
}]
If successful, the response body contains data with the following structure:
JSON representation |
---|
{ // Union field |
Fields | |
---|---|
Union field payload . Each stream response message contains one type of payload. payload can be only one of the following: |
|
header |
Report generation settings that describes the report contents, such as the report date range and localization settings. |
row |
Actual report data. |
footer |
Additional information about the generated report, such as warnings about the data. |
Authorization scopes
Requires one of the following OAuth scopes:
https://www.googleapis.com/auth/admob.readonly
https://www.googleapis.com/auth/admob.report
For more information, see the OAuth 2.0 Overview.
MediationReportSpec
The specification for generating an AdMob Mediation 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": 9, "day": 1},
"endDate": {"year": 2021, "month": 9, "day": 30}
},
"dimensions": ["AD_SOURCE", "APP", "COUNTRY"],
"metrics": ["OBSERVED_ECPM"],
"dimensionFilters": [
{
"dimension": "COUNTRY",
"matchesAny": {"values": [{"value": "US", "value": "CN"}]}
}
],
"sortConditions": [
{"dimension":"APP", 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, APP, COUNTRY, OBSERVED_ECPM
FROM MEDIATION_REPORT
WHERE DATE >= '2021-09-01' AND DATE <= '2021-09-30'
AND COUNTRY IN ('US', 'CN')
GROUP BY AD_SOURCE, APP, COUNTRY
ORDER BY APP ASC;
JSON representation |
---|
{ "dateRange": { object ( |
Fields | |
---|---|
dateRange |
The date range for which the report is generated. |
dimensions[] |
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[] |
List of metrics of the report. A report must specify at least one metric. |
dimensionFilters[] |
Describes which report rows to match based on their dimension values. |
sortConditions[] |
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 |
Localization settings of the report. |
maxReportRows |
Maximum number of report data rows to return. If the value is not set, the API returns as many rows as possible, up to 100000. Acceptable values are 1-100000, inclusive. Values larger than 100000 return an error. |
timeZone |
A report time zone. Accepts an IANA TZ name values, such as "America/Los_Angeles." If no time zone is defined, the account default takes effect. Check default value by the get account action. Warning: The "America/Los_Angeles" is the only supported value at the moment. |
Dimension
The dimensions of the mediation 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 for an unset field. Do not use. |
DATE |
A date in the YYYYMMDD format (for example, "20210701"). Requests can specify at most one time dimension. |
MONTH |
A month in the YYYYMM format (for example, "202107"). Requests can specify at most one time dimension. |
WEEK |
The date of the first day of a week in the YYYYMMDD format (for example, "20210701"). Requests can specify at most one time dimension. |
AD_SOURCE |
The unique ID of the ad source (for example, "5450213213286189855" and "AdMob Network" as label value). |
AD_SOURCE_INSTANCE |
The unique ID of the ad source instance (for example, "ca-app-pub-1234:asi:5678" and "AdMob (default)" as label value). |
AD_UNIT |
The unique ID of the ad unit (for example, "ca-app-pub-1234/8790"). If AD_UNIT dimension is specified, then APP is included automatically. |
APP |
The unique ID of the mobile application (for example, "ca-app-pub-1234~1234"). |
MEDIATION_GROUP |
The unique ID of the mediation group (for example, "ca-app-pub-1234:mg:1234" and "AdMob (default)" as label value). |
COUNTRY |
CLDR country code of the place where the ad views/clicks occur (for example, "US" or "FR"). This is a geography dimension. |
FORMAT |
Format of the ad unit (for example, "banner", "native"), an ad delivery dimension. |
PLATFORM |
Mobile OS platform of the app (for example, "Android" or "iOS"). |
MOBILE_OS_VERSION |
Mobile operating system version, e.g. "iOS 13.5.1". |
GMA_SDK_VERSION |
GMA SDK version, e.g. "iOS 7.62.0". |
APP_VERSION_NAME |
For Android, the app version name can be found in versionName in PackageInfo. For iOS, the app version name can be found in CFBundleShortVersionString. |
SERVING_RESTRICTION |
Restriction mode for ads serving (e.g. "Non-personalized ads"). |
Metric
The metrics of the mediation report. Metrics are quantitative measurements indicating how the publisher business is performing. They are aggregated from the individual ad events and grouped by the report dimensions. The metric value is either integer, or decimal (without rounding).
Enums | |
---|---|
METRIC_UNSPECIFIED |
Default value for an unset field. Do not use. |
AD_REQUESTS |
The number of requests. 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. 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. |
IMPRESSIONS |
The total number of ads shown to users. The value is an integer. |
IMPRESSION_CTR |
The ratio of clicks over impressions. The value is a double precision (approximate) decimal value. |
MATCHED_REQUESTS |
The number of times ads are returned in response to a request. 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. |
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. |
DimensionFilter
Describes which report rows to match based on their dimension values.
JSON representation |
---|
{ "dimension": enum ( |
Fields | |
---|---|
dimension |
Applies the filter criterion to the specified dimension. |
Union field operator . Filter operator to be applied. operator can be only one of the following: |
|
matchesAny |
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 ( |
Fields | |
---|---|
order |
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 |
Sort by the specified dimension. |
metric |
Sort by the specified metric. |