Reporting in the Ad Exchange Seller REST API

The Ad Exchange Seller REST API reporting system exposes the flexibility and customization capabilities of the Ad Exchange Seller website. This guide covers the parameters used in the reports.generate method and provides some tips to produce efficient and useful reports.


A report is generated by making a request to the reports.generate method with a date range, one or more metrics and one or more dimensions.


Each time Ad Exchange displays an ad, every event associated with that ad is logged with a set of attributes: date, country, channel, ad unit, etc. These attributes are called dimensions.


When a report is requested, the logged events are added together: How many impressions were there for this attribute? How many clicks? How much did the publisher make? It also does some math: What was the cost per click? What was the revenue per thousand impressions? These measurements are retrieved using metrics.

Some common examples

Get earnings per dayDATEEARNINGS
Get earnings and page views per weekWEEKEARNINGS, PAGE_VIEWS
Get earnings and page views for each custom channel per dayDATE, CUSTOM_CHANNEL_NAMEEARNINGS, PAGE_VIEWS
Compare the average Cost Per Click of each ad formatAD_FORMAT_NAMECOST_PER_CLICK

Choose dimensions wisely

The generated report consists of a series of rows, each having one or more fields. Adding a new metric to a report produces a new column but adding a dimension multiplies the number of rows.

For example, a report with DATE as a dimension will generate a set of rows, one row for each day with activity. Adding a new dimension, like CUSTOM_CHANNEL_NAME, will generate a row per day and per existing channel. As a guideline it's fine to use as many metrics as you like, but try not to use more than two dimensions per report.

Choose dimensions wisely


Dimensions can be filtered to match exact or partial queries. Also, they can be combined using ANDs and ORs. Take a look at the guide on filters to find out more.


Results can be sorted by metrics and dimensions. The name of the metrics and dimensions are passed as strings and they can be preceded by a “-” to indicate descending sort (default is ascending).

Date, week and month as dimensions

The required parameters startDate and endDate define the bounds of the report, the temporal dimensions (DATE, WEEK and MONTH) define the granularity. Some reports may not use a temporal dimension. For example:

Compare earnings per custom channelCUSTOM_CHANNEL_NAMEEARNINGS
Get earnings and page views per week, current week firstWEEKEARNINGS, PAGE_VIEWS-WEEK
Compare channel performance, per week, current week firstWEEK, CUSTOM_CHANNEL_NAMEEARNINGS-WEEK

Example report
Figure 1: Example report (Compare channel performance, per week, current week first)

Special date keywords

For convenience, date parameters (startDate and endDate) allow special keywords in place of the standard YYYY-MM-DD format:

  • today
  • startOfMonth
  • startOfYear

These allow generation of reports relative to the current date. Also, they can be modified:

ReportsStart dateEnd date
Last 7 days’ performancetoday-6dtoday
Last month’s performancestartOfMonth-1mstartOfMonth-1d
Previous six monthsstartOfMonth-6mstartOfMonth-1d

The available operations are addition (+) and subtraction (-) and the ranges are (y)ears, (m)onths, (w)eeks and (d)ays.

Example report: Monthly earnings and clicks, last six months, show last month first.

Example report: Monthly earnings and clicks, last six months, show last month first
Start date:startOfMonth-6m
End date:startOfMonth-1d


     "kind": "adsense#report",
     "totalMatchedRows": "6",
     "headers": [
       {"name": "MONTH", "type": "DIMENSION" }
       {"name": "EARNINGS", "type": "METRIC_CURRENCY", "currency": "USD"}
       {"name": "PAGE_VIEWS", "type": "METRIC_TALLY"}
     "rows": [
       ["2013-03", "285", "46320"],
       ["2012-10", "298", "49201"]
     "totals": ["", "1841", "300278"],
     "averages": ["", "288", "47501", ]

Example report
Figure 3: Example report

Incompatible dimensions and metrics

There are some metrics and dimensions that cannot be combined in a single report. For example, a conflict will arise when trying to fetch URL and custom channels at the same time. This limitation is the same as in the Ad Exchange Seller website (Performance reports tab).

You can use the metadata calls for dimensions and metrics to retrieve an up-to-date list of all compatible dimensions and metrics.

APIs explorer

In order to experiment and before starting to code the requests to the APIs, it’s recommended to use the APIs explorer, which is a secure and reliable tool to test the combination of filters, metrics and dimensions and to check that the result is expected.

Send feedback about...