Google Ads Developer Blog

Retiring support for v201103, v201104, and v201107 of the DFP API

2012-02-10T12:30:00.000-08:00

Today, we are announcing the deprecation of versions v201103, v201104, and v201107 of the DFP API. In 3 months, on May 11th, these versions will be turned off. We are turning off older versions to make sure that everyone can benefit from the improvements in more recent releases and so that we can focus on releasing new features.

As mentioned in previous deprecation announcements, we will always give at least 3 months notice before turning off a version. Our release notes page also contains changelogs for each version, which will help you migrate to a newer version. If you aren’t using one of our client libraries, now would be a great time to start as well. If you have any feedback or comments about this deprecation, or the API in general, please feel free to leave them on our forum or join us in a future hangout on Feb 28th.

- Adam Rogal, DFP API Team

isocket and Shiny Ads deliver new innovations using the DFP API

2012-02-07T10:00:00.000-08:00

Editor’s note: We’d like to share with you this post from John Park about the growing DFP API ecosystem and a few success stories from our partner directory. -- Adam Rogal, Ads Developer Relations Team

With thousands of publishers using the DFP and DFP Small Business ad serving platforms, we know first-hand that no two publishers are identical. Publishers may use in-house billing systems, have unique approval workflows, or use third-party tools to handle their ad operations.

To give publishers the flexibility to easily integrate their unique processes and systems with their ad server, DFP offers publishers an open API to easily create tools that complement their ad operations.

We’ve seen hundreds of developers build new ad serving innovations using the API, including applications to manage inventory, create orders, pull reports, and more. The API has created a new ecosystem of partner innovations, giving publishers access to new ad serving tools and applications. Two such applications come from isocket and Shiny Ads who have used the DFP API to build applications that help publishers manage and sell their ad space.

isocket uses the API to create tools that streamlines sales

Seeing the need to streamline the manual steps involved with buying and selling inventory, isocket engineered a direct and self-service ad sales tool to simplify sales workflows. By leveraging the DFP API, isocket was able to build an application to automate sales processes and save money. “We were interested in using the API because it allowed us to eliminate the hassle of manually coordinating campaigns, while still keeping the important parts like publisher control and approval. Integrating with the DFP API has allowed us to make things a lot simpler for publishers,” said Ben Trenda, VP of Sales at isocket.

Read more about how isocket integrated with the DFP API.

Shiny Ads builds application to help publishers save time

To help facilitate publishers’ direct ad campaign management, Shiny Ads began using
the DFP API to integrate its self-serve advertising platform with DFP in order to help publishers streamline their sales processes. This integration has helped save publishers time since they no longer need to manually book sales orders. “Our solution needs to support DFP - our customers demand it” said CEO and founder Roy Pereira. “The API made integrating with DFP easy for us, and most importantly, easy for our clients. Without the DFP API, Shiny Ads would not have the fully functional solution we have today.”

Read more about how Shiny Ads integrated with the DFP API.

Over the coming months, we’ll share more stories on how our partners are using the DFP API to deliver exciting ad serving innovations. For a complete list of partners who have built applications using the DFP API, please visit our partner directory.

Posted by John Park, Partner Programs Manager, and Adam Rogal, Developer Relations

Announcing v201201 of the DFP API

2012-02-06T15:00:00.000-08:00

The newest version of the API, v201201, brings some frequently requested features including using date time strings in PQL statements, filtering objects based on last modified date and times, including a PQL statement to limit a report (such as just running a report for one order), and more. A full list of features can be found on our release notes page.

Filtering

In v201201, we’ve focused on improving filtering with PQL statements across the entire API. We’ve introduced a better way to do date time filtering, a new lastModifiedDateTime field to search on, and the ability to filter from within a report.

With the ability to filter by date and time fields directly in the PQL statement, you’ll now be able to limit the objects on the server, rather than fetch all line items and checking their startDateTime property one at a time. For example, if you want to retrieve all line items that started so far in January, include

startDateTime

as a predicate of your filter with a date and time string, e.g.

WHERE startDateTime >= ‘2012-01-01T00:00:00’

. Note here that the date and time are in ISO 8061 format, i.e.

YYYY-MM-DDThh:mm:ss

, and the time zone is assumed to be that of the network’s. You can also bind a DateTime object instead of using a string, i.e.

WHERE startDateTime > :dateTime

, where

:dateTime

is bound to a DateTimeValue.

We’ve also added the new lastModifiedDateTime field to companies, creatives, ad units, line item creative associations, line items, orders, and placements. Using this field, you can now query for objects that have changed recently. Combined with the new date and time filtering feature mentioned above, you will be able to pull all objects changed so far this year, e.g.

WHERE lastModifiedDateTime >= ‘2012-01-01T00:00:00’

. If you are a developing an application that has to keep in sync with changes made through the UI, only pulling down objects that have changed since your last fetch time will speed up your calls and decrease processing time.

Finally, one of the largest requests from our developers was to limit what data is returned from within a report. We’ve add the ability to define a PQL statement in a report definition to do just that. Now when you create a report, you’ll be able to supply statements to limit it to just one order, e.g.

WHERE orderId = :orderId

, or with only one salesperson as well, e.g.

WHERE orderId = :orderId AND salespersonId = :salespersonId

.

Creatives

In v201102, we’ve added three new creative types that are only available to small business networks:

FlashExpandableCreative - an expandable creative where the collapsed size is a Flash SWF file and the expanded size is another Flash SWF file.
FlashPushdownCreative - a creative that pushes page content down when the creative expands.
TextAdCreative - a text-based creative.

Teams

We’ve introduced a new service with this version, TeamService, which lets you group users into teams. Although currently not editable via the API, teams will be used to limit access to entities such as companies, inventory, and orders.

Coming soon

Over the next few weeks, you’ll learn about all of the features a bit more in the Discover v201201 series starting first with a discussion of filtering and syncing best practices. Let us know if you want to see anything else on our forum.

- Adam Rogal, DFP API Team

AdWords API: Retrieving large result sets

2012-02-01T06:31:00.000-08:00

When you need to retrieve a large set of objects, such as a list of criteria for an account, it’s tempting to use one simple query with a paging parameter to pull the data from the server page-by-page.

While this approach is acceptable for most queries, it has some limitations:

The AdWords API does not allow you to retrieve data whose start index is past 50000
Unit cost for the request will depend on the number of pages and will be relatively expensive
A parallel update request may interfere with the process
Error handling and retry logic could be complex

We recommend using one of the following approaches instead:

Use AdHoc reporting to obtain data. With reports, you can still retrieve most fields available through SOAP requests, with the added bonus of AdHoc reporting being faster and free of unit costs.
Try to narrow the query as much as possible with predicates. Group queries by Campaign and AdGroup to retrieve only required data and to fit all results into one response.

Also, you can save bandwidth and retrieve large results faster by enabling transparent gzip compression. Check out our best practices page for more details on this feature and other recommendations.

As always, please feel free to ask any questions regarding the AdWords API on our forum or during scheduled office hours.

- Danial Klimkin, AdWords API Team

30 days left to migrate to AdWords API v201109

2012-01-30T09:43:00.000-08:00

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:

Review the resources in the AdWords API client libraries.

Review the “Discover v201109” blog series.

Subscribe to the AdWords API Twitter account, which will share daily migration tips for the next month

Make sure you’ve completed everything on this migration checklist.

Give yourself ample time to migrate from v13 to AdHoc reporting. Resources to help with this migration are available here.

Attend office hours.

Make sure your contact information is up to date in your My Client Center account.

Post questions on the forum.

Posted by Katie Miller, AdWords API Team

Announcing AdCatalog v1 for iOS

2012-01-27T16:36:00.000-08:00

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.

- Wes Goodman, AdMob Team

Prepare for the sunset with the AdWords API v201109 migration checklist

2012-01-27T09:49:00.000-08:00

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:

You can now use the v201109 CreateAccountService to create AdWords optional-login accounts

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

- Mandy Waite, AdWords API Team

Getting Started With the PHP Client Library

2012-01-26T11:00:00.000-08:00

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.

- Jeffrey Sham, DFP API Team

AdWords SOAP Header validation is being enabled

2012-01-25T11:30:00.000-08:00

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.

- Kevin Winter, AdWords API Team

Upcoming changes to AdWords Impression Share metrics

2012-01-24T02:19:00.000-08:00

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.

- Anash P. Oommen, AdWords API Team.

UPDATED: DeveloperToken in reports rollback

2012-01-20T13:27:00.000-08:00

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:

DotNet - 13.1.0
Java - 8.4.1
Perl - 2.5.1
PHP - 2.7.1
Python - 15.0.4
Ruby - 0.5.0

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.

- Kevin Winter, AdWords API Team

ReportDefinition XML Schema Definition is now available

2012-01-19T11:33:00.000-08:00

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.

- Kevin Winter, AdWords API Team

Upcoming Changes to the DFA API

2012-01-18T07:48:00.000-08:00

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.

- Joseph DiLallo, DFA API Team

Latest AdWords API developer docs available in 9 languages

2012-01-12T12:28:00.000-08:00

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.

- Stan Grinberg, AdWords API Team

AdWords, DFA and DFP Client Library Updates

2012-01-12T10:41:00.000-08:00

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.

- Kevin Winter, AdWords API Team

AdSense Management API and Chart Tools week: Thursday

2012-01-12T03:26:00.000-08:00

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!

- Silvano Luciani, AdSense API Team

Get Started with Ad Catalog for Android

2012-01-11T14:11:00.000-08:00

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.

- Eric Leichtenschlag, AdMob Team

AdSense Management API and Chart Tools week: Wednesday

2012-01-11T03:24:00.000-08:00

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.

- Silvano Luciani, AdSense API Team

Developer token required in reports starting January 17th

2012-01-10T10:41:00.000-08:00

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.

- Kevin Winter, AdWords API Team

AdSense Management API and Chart Tools week: Tuesday

2012-01-10T03:31:00.000-08:00

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.

- Silvano Luciani, AdSense API Team

AdSense Management API and Chart Tools week: Monday

2012-01-09T02:51:00.000-08:00

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?

If they’re related to the AdSense Management API, come to our forum and ask!
If they’re related to the Google Chart Tools, visit the Google Visualization API forum and ask!

- Silvano Luciani, AdSense API Team

55 days until AdWords API deprecation deadline

2012-01-05T13:56:00.000-08:00

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:

An overview of the new ConstantDataService, which can be used with CampaignCriterion to get more fine-grained control of the targeting of your campaigns

Information on changes to account identification criteria (it’s now only client customer ID)

Details on how to target campaigns with CampaignCriterionService

The introduction of XML validation so you can be alerted to structural issues with your requests

The introduction of CreateAccountService which creates AdWords accounts without login emails

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.

Katie Miller, AdWords API Team

More Office Hours in 2012

2012-01-05T11:56:00.000-08:00

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:

A Google+ account (sign up here)
The Google voice and video plugin installed on your computer
A quiet place to hangout so we can hear you

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.

- Eric Koleda, Google Ads Developer Team

Updates to AdWords API on Python Google App Engine

2012-01-05T11:46:00.000-08:00

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.

- Kevin Winter, AdWords API Team

Meet an AdSense API Engineer: Nick Johnson

2011-12-28T09:00:00.000-08:00

A few weeks ago, we caught up with Ben Birt from our AdSense API Engineering team in London. Today, we'd like to introduce you to another member of the team -- Nick Johnson, a Software Engineer who joined Google in May 2011.

What’s your main contribution to API development?
I could tell you... but then I would have to use one of those flashy things from Men in Black on you. (We have those at Google). Then I’d probably have to use it on me. I’m essentially a general purpose code monkey at this point in time, but I have some very cool stuff coming into the pipeline soon.

Describe your average day at work
My average day starts with me grabbing a coffee and some cereal from the kitchen. Aside from our (seated) stand up team meeting, everything else changes on a daily basis. So long as I get to do some coding, I’m generally happy.

What do you like most about the AdSense Management API?
I think the Ad Clients list call is my favourite. It’s less typing, so that makes it pretty ideal for making test calls. In all seriousness though, I think the thing I like best is the potential. The ways in which you can use and combine your data are entirely in your hands now.

We have some pretty cool surprises coming from inside Google (but when is that not true?), but we also can’t wait to see what third party developers create.

Tell us one best practice about the API
Think about what you have, and what you need. Be smart with your calls and make the most of them. Try to multiplex and retrieve as much of the data you need in the least number of calls. You need to balance this with the responsiveness of your app though. Quite obviously more data will take more time.

Another important thing is that if you have any problems or feature suggestions, then by all means, please...
...tell Silvano and Sérgio :) (members of the AdSense API Developer Relations team)

Enough work stuff, let’s go personal. We’ve heard that you lived in Scotland for some years. Is it true that they deep fry everything up there?
I think we both know that science has proven any foodstuff can be improved by submerging it in a large quantity of hot fat. It’s like adding “in space” to the end of a plot description. I did live in the beautiful city of Edinburgh (s’up to my homies on the Morningsi-ide) for ten extremely pleasant years, before I moved down to the big smoke for a job with the big G.

No, it’s not true that the Scottish deep fry everything. It would be far more accurate to say they will deep fry anything. Don’t knock it until you’ve tried it though. Deep fried Mars bars are very real, but I’m afraid I never tried them. I was worried I might like them.

Ok, let me ask you some geeky questions now. I’ve heard that you like functional programming...
Truly, your wit is sharp as a pillow.

Functional programming is something I’m slowly getting my head around, but the biggest barrier (for me, at least) is the attitude of the functional programming evangelists. It’s like talking to someone who thinks Emacs is better than Vim.

I mean, come on.

Since it’s obligatory in these sorts of interviews, why don’t you throw some film and book recommendations our way?
I’m at least as big a film nerd as I am a computer nerd (and I do the latter for a living!), so I could literally talk to you all day about that. If I’m completely honest, the film I saw in 2011 which I enjoyed the most was almost certainly Fast [and Furious] 5, but I’m not sure I’d go so far as to say it’s the best film I saw this year. I will always love The Matrix, Fight Club, Pitch Black and Amélie, and right now I’m really quite excited about Joss Whedon(!)’s The Avengers.

If I had to recommend one book it would probably be either The Hitchhiker’s Guide to the Galaxy, or Neal Stephenson’s Cryptonomicon (though that is really not a light read, in any sense of the word). Recently I read, and loved, “The Alloy of Law”, Brandon Sanderson’s follow up to his brilliant Mistborn trilogy, so I think I’ll also have to recommend those books.

Will you fix my computer?
No.

Fine. Will you code my favorite API?
I’m on it.

- Silvano Luciani, AdSense API Team
- Nick Johnson, AdSense API Team