AdSense Management API: Diving into Reports

The most significant feature in v1 of the AdSense Management API is the ability to run reports on your AdSense account: you've got the full functionality of AdSense reports at your disposal to use directly from your software.

While this is an extremely powerful tool, it brings with it a certain complexity that may make it tricky to figure out how to configure your first report. Fear not! This blog post will help you make sense of the different concepts involved in reporting, as well as how to put them together to get the report you need.


Dates

First things first. You need to indicate both a start and an end date with your report, so that you can tell AdSense what period of data to look at. The date range is inclusive of start and end dates, data outside this range will naturally be excluded.

Simple enough? Great, let's move on to the interesting stuff!


Dimensions and metrics

AdSense Management API reports have two main concepts which you'll find across many reporting systems: dimensions and metrics.

Dimensions are the categories or groups that you're reporting across. They define how you group your data and how you organise your report. For example, you may want to track your account performance over time (with dimensions such as DATE, WEEK, and MONTH), across countries (COUNTRY_CODE, COUNTRY_NAME) or across different AdSense products (PRODUCT_CODE, PRODUCT_NAME).

Metrics, on the other hand, represent the values you're measuring. You can measure your account performance by looking at your earnings (EARNINGS), number of clicks (CLICKS), number of page views (PAGE_VIEWS), and so on.

You can use multiple dimensions and metrics in a single report; multiple dimensions represent different groups and subgroups, whereas multiple metrics simply represent different "columns" or values you're measuring.

You'll find the full list of supported dimensions and metrics in the Reports reference.


Filters

Filters allow you to select a subset of data on which to base your report. They're a separate layer of control that restricts the data being processed before it's grouped by the dimensions or measured by the metrics you choose.

You can filter on any dimension with an exact (==) or substring (=@) match. So if you wanted your report data to be limited to earnings from the US, you could set your filter to COUNTRY_CODE==US, whereas if you wanted to limit the data to any country with "United" as part of its name, you could use COUNTRY_NAME=@United.

You can combine multiple filters by using boolean logic with OR and AND operations. Take a look at the relevant section in the filters documentation for more details on that.


A few examples

One of the most common reports would be your monthly earnings for the current year:

start date:  2011-01-01 end date:  2011-12-31 dimensions:  MONTH metrics:  EARNINGS filters:  (none)

{ "totalMatchedRows": "12", "headers": [ (...) ], "rows": [ ["2011-01", "41"], ["2011-02", "43"], (...) ["2011-12", "42"] ], "totals": ["", "504"], "averages": ["", "42"] }

You can add further metrics to track other areas of account performance, such as page views:

start date:  2011-01-01 end date:  2011-12-31 dimensions:  MONTH metrics:  EARNINGS, PAGE_VIEWS filters:  (none)

{ "totalMatchedRows": "12", "headers": [ (...) ], "rows": [ ["2011-01", "41", "750"], ["2011-02", "43", "760"], (...) ["2011-12", "42", "755"] ], "totals": ["", "504", "9000"], "averages": ["", "42", "750"] }

Of course, you may only be interested in the data for your US audience. Note that country code data only started being collected earlier this year, so we'll move the start date forward a bit:

start date:  2011-05-01 end date:  2011-12-31 dimensions:  MONTH metrics:  EARNINGS, PAGE_VIEWS filters:  COUNTRY_CODE==US

{ "totalMatchedRows": "8", "headers": [ (...) ], "rows": [ ["2011-05", "21", "375"], ["2011-06", "23", "380"], (...) ["2011-12", "22", "370"] ], "totals": ["", "176", "3000"], "averages": ["", "22", "375"] }

Or you may want your data to be broken down by country, instead of restricting it to the US:

start date:  2011-05-01 end date:  2011-12-31 dimensions:  MONTH, COUNTRY_CODE metrics:  EARNINGS, PAGE_VIEWS filters:  (none)

{ "totalMatchedRows": "24", "headers": [ (...) ], "rows": [ ["2011-05", "US", "21", "375"], ["2011-05", "FR", "10", "180"], ["2011-05", "JP", "11", "190"], ["2011-06", "US", "23", "380"], (...) ["2011-12", "US", "22", "370"] ], "totals": ["", "", "350", "6000"], "averages": ["", "", "42", "750"] }

Finally, you may just decide to look at your historical data to see which countries get you the most revenue, so you can choose which audiences to focus on:

start date:  2011-05-01 end date:  2011-12-31 dimensions:  COUNTRY_CODE metrics:  EARNINGS filters:  (none)

{ "totalMatchedRows": "3", "headers": [ (...) ], "rows": [ ["US", "175"], ["FR", "88"], ["JP", "87"] ], "totals": ["", "350"], "averages": ["", "116.67"] }

Your data, your reports

Ultimately, we can't predict which reports will be the most useful to you, or how you will use AdSense performance data in your applications. Instead, we hope to have made our reporting flexible and adaptable enough that you can get the data you need no matter what you're looking for.

And of course, if you can't figure out how to get that report with exactly the data you were hoping for, come talk to us in the forums, and we'll give you a hand!


 - Sérgio Gomes, AdSense API Team