Posted:
On February 29, 2012, we will be sunsetting the following versions and services:
  • AdWords API versions v13, v200909, v201003, v201008, v201101
  • AdWords API version v13 AccountService will only be available on a whitelist basis.
Calls made using these versions will return errors after February 29th. It is therefore critical that you migrate to AdWords API v201109 if you would like your applications to run without interruption.

We encourage you to use the following resources for a successful migration:
Posted by Katie Miller, AdWords API Team

Posted:

We’re very pleased to announce the release of AdCatalog v1 for the iOS platform. AdCatalog is a sample project that demonstrates how to incorporate banner and interstitial ad units into your application. In particular, AdCatalog showcases implementations for two standard banner ad sizes—320x50 and 300x250—and several use cases for interstitial ad units: basic, app launch splash screen, in-between game levels, and before playing a stored video.

AdCatalog can be downloaded as a zip from our google-mobile-dev project. Additionally, feel free to clone the repository or examine the source from the checkout page. In version 2, we’ll be looking to add even more advanced layout options to our banner scenario, so be sure to stay tuned. As usual, if you have any questions, comments, concerns, or feature requests, we appreciate hearing the feedback on our developer forum.


Posted:
As announced in October, we will sunsetting all versions of the AdWords API prior to v201109 on February 29, 2012. To help you prepare to migrate to v201109, we've created a checklist that covers all of the required changes:

Required Changes:
  • Migrate all API calls to use v201109 services
  • Migrate all API calls to use clientCustomerId (instead of clientEmail) to identify an account as the target of an operation (Blog post)
  • Migrate campaign geo target creation and identification to use the new location criterion object (available through the CampaignCriterionService and the LocationCriterionService)
  • Migrate all other campaign targets (except ad scheduling) from the CampaignTargetService to CampaignCriterionService using the appropriate criterion objects defined within that service*
  • Migrate cross client reporting to v201109 AdHoc (single account) reports (Blog post)
  • Provide developerToken as HTTP header in AdHoc report requests
  • The last few API releases have seen various services migrate to generic selectors, as you update to v201109 you’ll need to migrate from service specific selectors to generic selectors as required. See the Selector Migration Reference for details
  • Update to the very latest version of the AdWords API client library specific to the programming language(s) that you use for API tool/platform development**
  • If you generate your own client side stubs from the API Service WSDLs, make sure that your requests strictly adhere to the WSDL definition as we have implemented stricter validation for the SOAP header and envelope (Blog post)

Optional Changes:

Note: If you do not make the required changes, calls made using versions of the AdWords API prior to v201109 will return errors after February 29th 2012

Additional Notes:
*In v201109, most targets become criteria, with each having it’s own ‘type’ of criterion object (see this Blog post for more details)
**This is an important requirement, so do make sure to check the version of the library or libraries that you are using against those available here



Posted:
Recently, we released our first client library walkthrough video for the DoubleClick for Publishers API. This five-minute video guide shows you how to get up and running with the PHP client library from downloading the code to running one of the examples. All you need to get started is a DFP account (production or sandbox) and a machine with PHP 5.2.x and the SoapClient, OpenSSL, and cURL extensions. For new users to the API, it’s a great way to get acquainted with the documentation pages, project site, and client library features.



The video takes you through an explanation of how the getCreativesByStatement example makes an API call and highlights common usage patterns and best practices for the client library. We also show you what happens when a call returns an error and how you can configure logging to get more information and troubleshoot an issue.

Please let us know about any topics you would like us to cover in a video guide or blog by leaving a comment on our forum. You can also chat with us live at one of our DFP API Office Hours Hangouts.

Posted:
Starting with v201109, we enabled stricter validation of the SOAP Body, meaning that XML that did not closely follow the XML Schema defined in the WSDL would be rejected with a SOAP fault. This stricter validation enables developers to detect flaws in their applications, such as sending an unsupported field, at development time rather than later discovering that field was ignored.

In the coming weeks, we will also be enabling stricter validation of the SOAP Headers. Currently, SOAP Headers that don’t validate against the XML Schema are ignored. This includes headers such as clientEmail/applicationToken (both of which do not apply to v201109) or partialFailure, which is case sensitive (will not accept “TRUE” or “True”, only “true”). When clientEmail is ignored, the request will target the authenticating account (often an MCC), which will, for example, return an error message if you attempt to add a Campaign or no results if you make a GET request.

The stricter validation will trigger a SOAP fault for any SOAP Headers that do not match the XML Schema defined in the WSDL. This may cause your application to see more errors such as those referenced in our previous blog post. This validation will enable developers to better detect bugs in their application that were previously silently ignored.

If you have any questions, please post on the forum or attend one of the AdWords API Office Hours Hangouts.

Posted:

We recently announced upcoming changes to AdWords Impression Share metrics. If you are using the AdWords API to download BudgetLostImpressionShare, ImpressionShare, QualityLostImpressionShare and ExactMatchImpressionShare metrics in account and campaign performance reports, then the upcoming change will affect you in the following ways:

  • We will revise campaign-level Impression Share metrics from May 1, 2011 to present. You may notice some adjustments in past campaign-level Impression Share data once this change goes live.
  • We will remove campaign-level Impression Share metrics prior to May 1, 2011. If you depend on historic impression share data prior to May 1, 2011, then you need to download them before January 30th.
  • All Impression Share metrics will only be updated once every day, by afternoon PST. In addition, the data will no longer be available for segmentation by hour. If you have a saved report definition that requests hourly aggregation of IS data, then those definitions will stop working once the new changes go live.

If you wish to backup old Impression Share data or make changes to the way you use Impression Share to control your AdWords campaigns, please do so before January 30th. If you have any questions about the AdWords API, check out our developer forum.


Posted:
Update: developer token will be required in report downloads starting February 7th, 2012.

Based on recent AdWords API forum posts, many of you are unaware that on January 17th we began requiring a developer token in all post v13 report downloads. As a result, we are temporarily rolling back this change to give you additional time to update your applications and upgrade to the latest version of the client libraries. If you have already made this change, no action is required on your part. We will enforce this requirement starting February 7th, 2012.

Minimum client library versions with support for providing the developerToken header in reports are as follows:

As always, we encourage you to subscribe to the AdWords API blog posts and Twitter account and to follow us on the forum to ensure that you are aware of all critical updates and requirements.

If you have any questions, please post on the forum or attend one of the AdWords API Office Hours Hangouts.

Posted:
Unlike reports in previous AdWords API versions, v201109 AdHoc reports are downloaded by POSTing XML to a URL rather than defining them using a SOAP service; therefore they have no WSDL document to describe the XML payload. To ensure that your ReportDefinition XML is valid when sending it to the API, we are now publishing an XML Schema Definition (XSD).

This XSD is tied to the versioned Report Download endpoint, allowing us to make incremental changes to reporting as needed. Here’s an example URL used to obtain the XSD for v201109 ReportDefinitions:

https://adwords.google.com/api/adwords/reportdownload/v201109/reportDefinition.xsd


How to use this XSD

There are many tools to use to validate XML against an XSD. Here we will show how to use the common command-line tool xmllint to validate against the XSD. First, download the reportDefinition.xsd to a working directory. Next, save some ReportDefinition XML to a file, such as reportDefinition.xml:

<reportDefinition xmlns="https://adwords.google.com/api/adwords/cm/v201109">
 <selector>
   <fields>CampaignId</fields>
   <fields>Id</fields>
   <fields>Impressions</fields>
   <fields>Clicks</fields>
   <fields>Cost</fields>
   <predicates>
     <field>Status</field>
     <operator>IN</operator>
     <values>ENABLED</values>
     <values>PAUSED</values>
   </predicates>
 </selector>
 <reportName>Custom Adgroup Performance Report</reportName>
 <reportType>ADGROUP_PERFORMANCE_REPORT</reportType>
 <dateRangeType>LAST_7_DAYS</dateRangeType>
 <downloadFormat>CSV</downloadFormat>
</reportDefinition>


Now run the following command from the directory you placed these two files in:

$ xmllint --schema reportDefinition.xsd reportDefinition.xml
[xml omitted]
reportDefinition.xml validates

This step verifies that your ReportDefinition XML is well-formed for use with the AdWords API report downloads.

If you have any questions, please post on the forum or attend one of the AdWords API Office Hours Hangouts.

Posted:

As we continue to improve the DFA API, two upcoming security enhancements are particularly noteworthy. We want you to be aware of adjustments to HTTP support and token lifespan and to take them into consideration when planning the development and upkeep of your applications.

Moving Towards Secure Connections

Last year Google began an effort to improve the security of our APIs with SSL encryption. Most of Google’s Ads APIs already require requests to be made over HTTPS connections. The DFA API will be following suit this year. We’ll consider the use of HTTP connections deprecated with the release of v1.17 in mid-February, 2012. Support for making requests over HTTP will be completely retired in v1.18, expected to launch in May, 2012. Our client libraries will transition to using HTTPS connections during the launch of v1.17.

On the Horizon: Expiring Tokens

Currently, tokens generated from the login service’s authenticate operation do not expire unless the user profile’s password is changed. In the not-too-distant future, API tokens will have a timed lifespan. We will be adding a new error code to represent a failure due to an expired token so that your applications will be able to catch and handle this situation.

We do not have a concrete release date for token expirations yet. It will not be part of the v1.17 release. Please keep an eye on our blog for further updates about this topic. Questions and comments are always welcome on our forum.

Posted:
We are happy to announce availability of the AdWords API documentation for v201109 release in 9 languages in addition to English. In time for your upcoming migration with deadline on February 29, 2012, we have released the latest documentation in Chinese, French, Japanese, German, Korean, Portuguese, Russian, and Spanish. The drop-down menu at the top right corner of the documentation can be used to change the language.

If you have any questions, suggestions or requests for improving docs please post on the forum.

Posted:
We’re constantly making improvements to our AdWords, DoubleClick for Advertisers (DFA) and DoubleClick for Publishers (DFP) client libraries across all supported languages. Recently, we added the following features. Read the ChangeLogs and READMEs for details on these changes:
  • GZIP compression used when sending and receiving API calls and reports. (Perl and Java do not have this for AdWords API Report Downloads).
  • SSL certificate verification.
  • AdWords only - Examples and support for the new CreateAccountService.
Please see below for a summary of other changes for each library.

DotNet
  • No other updates.

Java
  • A preview version of the rewritten Java client library is now available for AdWords, DFA and DFP APIs. Please consider this alpha-quality code; please file any bugs or feature requests on the issue tracker. The new library currently supports Maven2, SLF4J, OAuth and we have plans to support other environments and platforms.


Ruby
  • Improved parameters validation and error reporting on missing / mistyped fields.
  • HTTP headers are now logged on DEBUG level.

Perl
  • Fixes to OAuth logic to better handle misconfigurations.
  • Several bug fixes.

PHP
  • AdWords only - Added example to get the clientCustomerId for a clientEmail.
  • AdWords only - Fixed issue with GetAccountHeirarchy example when used in the sandbox.
  • Fixed issue with lingering "id" attribute after reference replacement. Added tests for SoapXmlFixer.

Python
  • Validation and error handling has been improved to make it easier to use OAuth and Google AppEngine.


You can download updated versions of our client libraries from their respective sites, or see a list of all client libraries: AdWords, DFA and DFP.

If you have any questions or would like to discuss these changes, please post on our forums: AdWords, DFA, DFP.


Posted:

Thanks for joining us for Chart Tools week on the blog, where we're sharing ways to use Google Chart Tools. In the fourth and last part of this series, we’ll examine how to organize and manage multiple charts that share the same underlying data using dashboards and controls.

Interaction with data

The last request of the CEO is to be able to interact with the data: he wants to filter the line chart and the column chart by expressing a range of page views.

What we need to do now is compose the 2 charts into a Dashboard object, following these steps:

  • combine the data retrieved from the AdSense Management API into one single table
  • create the charts
  • add 1 control, a Number Range Filter for ad requests
  • create a view on top of the data table
  • create a Dashboard object and feed it with the view

Create the DataTable

To create a Dashboard, we need the charts to share the same underlying data. For this reason, we will combine the requests for the line and the column chart into a single request:

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

The result will be similar to:

result = {
  "kind": "adsense#report",
  "totalMatchedRows": "9",
  "headers": [ {...} ],
  "rows": [
    ["2011-01", "28", "46", "41", "165"],
    ...
    ["2011-11", "2", "3", "3", "3"]
  ],
  "totals": ["", "241", "278", "264", "825"],
  "averages": ["", "26", "30", "29", "91"]
}

Now we can create our DataTable, adding columns for all the metrics:

var data = new google.visualization.arrayToDataTable(
    [['Month', 'PAGE_VIEWS', 'AD_REQUESTS', 'MATCHED_AD_REQUESTS',
        'INDIVIDUAL_AD_IMPRESSIONS']].concat(resp.rows));

Create the charts

The next step is to create the wrappers:

var lineChartWrapper = new google.visualization.ChartWrapper({
  chartType: 'LineChart',
  options: {'title': 'Ad requests trend - Year 2011'},
  containerId: 'line_chart_div',
  view: {'columns': [0, 2]}
});

var columnChartWrapper = new google.visualization.ChartWrapper({
  chartType: 'ColumnChart',
  options: {'title': 'Performances per month - Year 2011'},
  containerId: 'column_chart_div',
  view: {'columns': [0, 1, 3, 4]}
});

There are two important differences between creating wrappers for a dashboard and wrappers for standalone charts:

  • For each chart in a dashboard, we use the view option to select which columns are relevant for the chart (remember, all the data for the two charts is in the same table now)
  • We don’t draw the charts now, we’ll draw the entire dashboard later

Time to create the control!

Create the control

Let’s create the control wrapper for our number range filter for the ad requests:

var adRequestsSlider = new google.visualization.ControlWrapper({
  'controlType': 'NumberRangeFilter',
  'containerId': 'ad_requests_filter_div',
  'options': {
    'filterColumnLabel': 'Ad requests',
  }
});

The option container_id specifies the element of the page where the filter will be drawn into, while filterColumnLabel tells the filter which column to target.

Create the DataView

Remember that we need a DataView to convert our string field to numeric fields:

var view = new google.visualization.DataView(data);
view.setColumns([
  0,
  {calc:function(dataTable, rowNum) {return parseInt(dataTable.getValue(
      rowNum, 1))}, type:'number', label:'Page views'},
  {calc:function(dataTable, rowNum) {return parseInt(dataTable.getValue(
      rowNum, 2))}, type:'number', label:'Ad requests'},
  {calc:function(dataTable, rowNum) {return parseInt(dataTable.getValue(
      rowNum, 3))}, type:'number', label:'Matched ad requests'},
  {calc:function(dataTable, rowNum) {return parseInt(dataTable.getValue(
      rowNum, 4))}, type:'number', label:'Individual ad impressions'},
]);

Create the dashboard

Creating the Dashboard, binding the control to the charts and drawing the dashboard is as easy as the following:

var dashboard = new google.visualization.Dashboard(
    document.getElementById('dashboard_div'))
    .bind(adRequestsSlider, [lineChartWrapper, columnChartWrapper])
    .draw(view);

dashboard_div is the element of the page that acts as container for the Dashboard:

<div id="dashboard_div">
  <!--Divs that will hold each control-->
  <div id="ad_requests_filter_div"></div>
  <!--Divs that will hold each chart-->
  <div id="line_chart_div"></div>
  <div id="column_chart_div"></div>
</div>

And it’s done! Our Dashboard is ready. Check the live example and the source code for today!

Mission Accomplished!

Well done -- our dashboard is ready and the CEO is happy with his new tool! Now you can relax and play foosball!

If you want to know more about our APIs, check the documentation pages:

And if you have any additional questions, don’t hesitate to engage with us in our forums:

You can also join us in one of our AdSense API Office Hours on Google+ Hangouts. Check the schedule for the upcoming Office Hours in our Google Ads Developer Blog.

Lastly, a public service announcement: thanks Riccardo for your help!

Posted:

Last quarter we announced the release of Ad Catalog for Android, a sample project that demonstrates how to incorporate ads into your application using the Google AdMob SDK. Today, we are excited to announce the release of a walkthrough video to help you get started with Ad Catalog in five minutes! This video will guide you through the entire setup process, from downloading the source code to running it on an emulator. The only preconditions are that you have Eclipse installed as well as an Android SDK version 3.2 or higher.



Ad Catalog shows you two implementations for standard banner ads. You can select the size of the ad that is displayed on the Banners screen by selecting either the 320x50 standard banner ad or the 300x250 medium rectangle ad.

In addition to display ads, Ad Catalog demonstrates various use cases for interstitial ads. Ad Catalog provides examples on how to include interstitial ads in between game levels, before loading a YouTube video, and in between a screen swipe. There is also an option to receive a splash screen interstitial ad. If enabled, the app will load and display an interstitial ad the next time it starts up.

The first version of the Android Ad Catalog source code can be downloaded from the google-mobile-dev project. In the next version, we plan to add examples of banner ads in various advanced layouts. The iOS implementation of Ad Catalog is almost complete, so stay tuned for another release announcement. We appreciate your feedback, so please post any questions or feature requests you may have to our forum.

Posted:

Welcome back to Chart Tools week here on the blog, where we're continuing our overview of generating charts for your AdSense reporting with Google Chart Tools. Today we’ll examine how to generate two other types of charts: a table chart and a geo chart.

Table chart

The third chart requested by our CEO is a table chart. The table chart will contain the number of ad requests, the number of matched ad requests, and the number of individual ad impressions broken down by ad client ID.

Our request will have these parameters:

start date:2011-01-01
end date:2011-12-31
dimensions:AD_CLIENT_ID
metrics:AD_REQUESTS, MATCHED_AD_REQUESTS, INDIVIDUAL_AD_IMPRESSIONS
filters:(none)

And the result will be similar to:

result = {
  "kind": "adsense#report",
  "totalMatchedRows": "4",
  "headers": [ {...} ],
  "rows": [
    ["ca-afdo-pub-1234567890123456", "59", "55", "232"],
    ...
    ["partner-mb-pub-1234567890123456", "1", "0", "0"]
  ],
  "totals": ["", "278", "264", "825"],
  "averages": ["", "69", "66", "206"]
}

As usual, let’s create a DataTable and a DataView to perform transformations on columns:

var data = new google.visualization.arrayToDataTable([['Ad client id',
    'AD_REQUESTS', 'MATCHED_AD_REQUESTS', 'INDIVIDUAL_AD_IMPRESSIONS']]
    .concat(resp.rows));
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'},
  {calc:function(dataTable, rowNum) {return parseInt(dataTable.getValue(
      rowNum, 2))}, type:'number', label:'Matched ad requests'},
  {calc:function(dataTable, rowNum) {return parseInt(dataTable.getValue(
      rowNum, 3))}, type:'number', label:'Individual ad impressions'}
]);

Finally, let’s draw the table chart. Note that there is no title for a table chart: if you need one, you’ll have to add it in a different element.

var tableWrapper = new google.visualization.ChartWrapper({
  chartType: 'Table',
  dataTable: view,
  containerId: 'vis_div'
});
tableWrapper.draw();

The table chart for our CEO is ready, and it can be sorted and paged.

Check the live example and the source code for today!

Geo chart

Finally, the last chart requested from our CEO: a geo chart. The geo chart will show the number of page views for the year broken down by country name.

Our request will have these parameters:

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

And the result will be similar to:

result = {
  "kind": "adsense#report",
  "totalMatchedRows": "9",
  "headers": [ {...} ],
  "rows": [
    ["Canada", "1"],
    ...
    ["United States", "52"]
  ],
  "totals": ["", "241"],
  "averages": ["", "26"],
}

DataTable and DataView creation step:

var data = new google.visualization.arrayToDataTable(
          [['Country', 'Page Views']].concat(resp.rows));

var view = new google.visualization.DataView(data);
view.setColumns([
  0,
  {calc:function(dataTable, rowNum) {return parseInt(dataTable.getValue(
      rowNum, 1))}, type:'number', label:'Page views'}
]);

Now we can draw the geo chart. For the geo chart there is no title:

var geoChartWrapper = new google.visualization.ChartWrapper({
  chartType: 'GeoChart',
  dataTable: view,
  containerId: 'vis_div'
});
geoChartWrapper.draw();

Et voilĂ ! We have a map of the world with colors and values assigned to specific countries representing the page views from the countries for the current year.

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 using our Google API Explorer and our Google Visualization PlayGround. You can use the Explorer to query our AdSense Management API, and then use the results inside the code on the Visualization PlayGround to generate a chart.

In the next and final part of this series, we will see how to assemble multiple charts into dashboards and enrich them with interactive controls to manipulate the data they display.

Meanwhile, feel free to post any questions related to Google Chart Tools in Google Visualization API forum, or visit our AdSense Management API forum to ask general questions.

Posted:
As previously mentioned, the production environment will start requiring developer tokens with report downloads starting on Tuesday, January 17th. Please see the original blog post for details regarding how to provide the token and what errors you will see when it is not provided.

The sandbox environment has required the developer token as an HTTP header since November 16th. We strongly encourage you to test your production report download code against the sandbox environment to confirm that you will not experience any disruptions in report downloads. The AdWords API client libraries have also been updated to reflect this change; upgrade to the newest version of your client library to ensure continued reporting.

If you have any questions or would like to discuss these changes, please post on the forum or attend one of the AdWords API Office Hours Hangouts.


Posted:

It's Chart Tools week here on the blog, and so we'll be showing you in a 4-part series how to easily generate charts for your AdSense reporting using Google Chart Tools. In today’s second post we’ll examine how to generate another type of chart: a column chart.

Column chart

The second item required by our CEO is a column chart. The column chart will show the number of page views, ad requests, matched ad requests and individual ad impressions for each month of the current year.

Our request becomes:

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

Now the result will be similar to:

result = {
 "kind": "adsense#report",
 "totalMatchedRows": "9",
 "headers": [ {...{ ],
 "rows": [
   ["2011-01", "28", "46", "41", "165"],
   ...
   ["2011-11", "2", "3", "3", "3"]
 ],
 "totals": ["", "241", "278", "264", "825"],
 "averages": ["", "26", "30", "29", "91"]
}

We create the DataTable object, adding the columns for our dimensions:

// Create the data table.
var data = new google.visualization.arrayToDataTable(
    [['Month', 'PAGE_VIEWS', 'AD_REQUESTS', 'MATCHED_AD_REQUESTS',
    'INDIVIDUAL_AD_IMPRESSIONS']].concat(result.rows));

Once again we use a DataView to convert the string values to numbers:

var view = new google.visualization.DataView(data);
view.setColumns([
  0,
  {calc:function(dataTable, rowNum) {return parseInt(dataTable.getValue(
      rowNum, 1))}, type:'number', label:'Page views'},
  ...
  {calc:function(dataTable, rowNum) {return parseInt(dataTable.getValue(
      rowNum, 4))}, type:'number', label:'Individual ad impressions'}
]);

And finally, let’s create a wrapper for the column chart and draw it:

var columnChartWrapper = new google.visualization.ChartWrapper({
  chartType: 'ColumnChart',
  dataTable: view,
  options: {'title': 'Performances - Year 2011'},
  containerId: 'vis_div'
});
columnChartWrapper.draw();

Another piece is done: a column chart of our performances that is also displaying tips when hovering over bars. 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.

Stay tuned for our next post this week, where we’ll show you how to generate other two charts, a table chart and a geo chart.

If you have any questions related to the AdSense Management API, come to our forum; alternatively, visit the Google Visualization API forum if you're looking for support on Chart Tools.


Posted:
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?

Posted:
As announced in October 2011, with the release of AdWords API v201109, we will be deprecating the following versions and services:
  • AdWords API versions v13, v200909, v201003, v201008, v201101
  • AdWords API version v13 AccountService will only be available on a whitelist basis.
We will be sunsetting these versions and services in 55 days on February 29, 2012. If you have not started migrating to AdWords API v201109, we strongly encourage you to do so, as calls made using previous versions will return errors after February 29th. In particular, we anticipate that migrating from v13 to AdHoc reporting may take some time. Resources to help with this migration are available here. AdHoc documentation is available here and best practices have been outlined on the blog.

We’ve been running the “Discover v201109” blog series to introduce new services, as well as make the migration process easier for you. Posts include:
To keep up to date with future “Discover v201109” posts, click on the adwords_v201109 label on the Google Ads Developer Blog.

As with every new version of the AdWords API, we encourage you to review the resources in the AdWords API client libraries. If you have any questions please post them on the AdWords API forum. We will also continue to host Google+ Hangouts with members of the AdWords API Developer Relations Team.

Finally, we may send out periodic service announcements via email on the deprecation timeline and resources to migrate to v201109. Please be sure that your contact information is up to date in your My Client Center account. Review this blog post for more details.
 

Posted:
Last year we hosted our first office hours for the Google Ads Developer products using Google+ hangouts, and the feedback was overwhelmingly positive. We plan to host more of them in 2012, and sessions for January and February have already been scheduled. Our upcoming hangouts are listed on the Google Developers events page, and we encourage you to click the "I'll be there" button if you plan on attending. You can also follow our schedule by subscribing to the Google Ads Developer Office Hours calendar or by glancing at the sidebar to the right of this blog entry.
In case you haven’t joined us before, you will need 3 things to join the hangout:
These hangouts are informal and conversational, which make them a great place to ask questions or give us feedback. If you have questions about our office hours program, reach out to us on the forums.

Update: DFP January Office hours have been moved to January 31st.

Posted:

The AdWords API Python Google App Engine demo has been updated to use v201109 (and clientCustomerId) and now has its source control hosted at the new project site.

In addition, we are happy to announce the release of a new Python Google App Engine demo - this one demonstrating AdHoc reports running on Google App Engine using OAuth 1.0a for the authentication. This demo allows you to select as many or as few child accounts as you wish to run a report against and will download the reports asynchronously using a Task Queue one by one. Reports are stored in the Google App Engine Blobstore and can be downloaded by the user once they have been processed.

The new demo also shows how to perform the OAuth flow in a web application context and how to store the oauth_token and oauth_token_secret in the Google App Engine datastore. OAuth is used both to query the API for a list of accounts as well as to download the reports.

You can download the Google App Engine demo and use the Python Development Google App Engine Server to play around with the code without the need for an existing Google App Engine account. If you have any questions or would like to discuss this new demo, please post on the forum.