Monday, January 9, 2012

AdSense Management API and Chart Tools week: Monday

It’s Monday morning, and you’re sitting in front of your computer, ready for a relaxed start of the week. But wait!

You’ve received an email from your CEO. He wants you to add AdSense reporting to his dashboard, and he wants to see the following:
  • a line chart showing the number of ad requests for the current year, broken down by month
  • a column chart showing the number of page views, ad requests, matched ad requests and individual ad impressions for the current year, broken down by month
  • a table showing the number of ad requests, matched ad requests and individual ad impressions for the current year, broken down by ad client id
  • a geo chart showing the number of page views for the current year broken down by country
He also requires the ability to interact with data: he wants to refine the visualization of the line and column charts filtering by lowest and highest number of ad requests shown in the charts.

It might look like a week of hard work is coming, but don’t worry! It’s Chart Tools week here on the AdSense Management API blog, and we’re going to show you how to easily and rapidly create the dashboard using the Google AdSense Management API and the Google Chart Tools. In the first part of this series, we’ll examine how to generate a line chart.

Background


You can access the AdSense Management API from different programming languages using the appropriate Google APIs Client. Check our documentation for AdSense Management API specific information.

The Google Chart Tools API are accessible using Javascript, check this ‘Hello Charts’ example for a quick start lesson on the API.

Line chart


The CEO wants a line chart showing the number of ad requests for the current year, broken down by month.

We will send a request to the AdSense Management API with the following parameters:
start date:2011-01-01
end date:2011-12-31
dimensions:MONTH
metrics:AD_REQUESTS

 And the result will be a json array similar to the following: 
result = {
  "kind": "adsense#report",
  "totalMatchedRows": "9",
  "headers": [ {...} ],
  "rows": [
    ["2011-01", "46"],
    ...
    ["2011-11", "3"]
  ],
  "totals": ["", "278"],
  "averages": ["", "30"]
}
To use the Chart API we first need to create a DataTable object representing the result of our request: 
// Create the data table.
var data = new google.visualization.arrayToDataTable(
    [['Month', 'AD_REQUESTS']].concat(result.rows));
The AdSense Management API is returning the value for AD_REQUESTS as a string, but we need a numeric value for our charts. To achieve this, we are going to build a Data View on top of our Data Table and convert the string column to a number column: 
var view = new google.visualization.DataView(data);
view.setColumns([
  0,
  {calc:function(dataTable, rowNum) {return parseInt(dataTable.getValue(
      rowNum, 1))}, type:'number', label:'Ad requests'}
]);
Our DataView will use the first column of the DataTable as it is, but will generate on the fly a second column composed of numeric values by calling a function of our choice that implements the conversion.

Finally we can draw the chart using a chart wrapper and passing our DataView to the wrapper. Make sure to define an element with id equal to the containerId parameter, as this is where the chart will be drawn. 
var lineChartWrapper = new google.visualization.ChartWrapper({
  chartType: 'LineChart',
  dataTable: view,
  options: {'title': 'Ad requests trend - Year 2011'},
  containerId: 'vis_div'
});
lineChartWrapper.draw();
The line chart for the CEO is ready, and it’s also displaying tips when hovering over points. Check the live example and the source code for today!

Time to play!

Eager to try to see what you can do combining these two powerful Google APIs?

You can start immediately by using our Google API Explorer and our Google Visualization PlayGround. You can use the Explorer to query our Management API, and then use the results inside the code on the Visualization PlayGround to generate a chart.

In the next post of this series, we’ll look at how to generate a column chart.

Have questions in the meantime?
 - , AdSense API Team