Downloading reports for lots of client accounts

Reporting has changed significantly with v201109. We’d like to take this opportunity to discuss how to download reports for lots of clients simultaneously. To download reports for a large number of client accounts, we recommend requesting the download of these reports simultaneously.

We recommend requesting no more than 10 reports concurrently and to use one thread for each concurrent download. If for some reason the report download fails, we recommend you retry after a short wait. The length of the wait should increase with the number of times the request has been tried (known as Exponential Backoff). This backoff algorithm helps prevent making too many requests to the server in a short period of time.

You should check the specific reason the download failed and only retry if it was a transient error (such as exceeding the rate limit) instead of retrying if the report definition XML was invalid. The HTTP Status of the response provides useful information:

• HTTP Status 500 indicates there is a transient server side issue and the request can be retried after a delay. We retrying no more than 5 times for any given report.
• HTTP Status 400 indicates there was a problem with the request (or the report itself) and retrying will not help.
• HTTP Status 200 means the report download was successful.

With v201109 you should use Ad Hoc reports to download new reports. With this new feature, there is no need for stored ReportDefinitions. The XML describing a Report Definition is sent directly with report download. A developer token is required, but the API call accrues no costs (report downloads are now free!).

Another benefit of downloading reports in this fashion is you get data more quickly than with legacy cross-client reports. As soon as a report download succeeds, you can start processing the data by putting it into a database or performing further logic on the results.

We hope this discussion of best practices will help you with writing report download code in the future. We’ve published a reference implementation showing how to do this in java here. If you have any questions about downloading reports, you can ask us on the forum.

Kevin Winter, AdWords API Team

Enjoy more API units this holiday season

Last year, we provided you with a bonus of 20% more AdWords API units at no additional cost. We’re pleased to announce that we’re bringing back our holiday bonus this year. Starting now and extending through January 15, 2012, you’ll receive 20% more API units at no additional cost.

Here are the details:

• Developers can purchase AdWords API units at the rate of 1250 for 0.25 USD, up from 1000 for 0.25 USD. Don’t forget that you can apply for preferred AdWords API pricing to receive free units.
• Advertisers who are eligible for free units will receive credit at the rate of 300 units for every 1 USD of AdWords spend, up from 250 for every 1 USD of AdWords spend. They will be credited the holiday bonus based on their spend in previous months

You can view your AdWords API usage in your MCC account, by clicking the AdWords API Center link under the My Account tab.

You can use this as an opportunity to try out and take advantage of the many new features just released in version v201109. As always, we encourage you to use the AdWords API as efficiently as possible.

Happy Holidays,
Posted by the AdWords API Team

AdWords API now fully supports OAuth 1.0a

With the release of v201109 we are happy to announce that we now fully support OAuth 1.0a in the AdWords API.

OAuth is an open standard for authorization. Google uses this standard to allow applications to access a user’s data (in this case AdWords) without requiring the user to give the application their Google username and password.

In OAuth, an application starts by contacting Google with an OAuth request. Next, the application redirects the user to Google to authorize the request. Once authorized, the user is directed back to the application, which can then upgrade their request token to an access token which the application can use to make requests to Google in lieu of a username and password.

The client libraries have code to handle much of the OAuth process for you. We have provided code examples in many languages to demonstrate how to use OAuth with the client libraries: DotNet, Python, Ruby, Perl, PHP.

Please note that making your first request against the sandbox using OAuth will not create accounts for you as described here. Please make your first request to the sandbox using email/password authentication to provision the sandbox accounts and make subsequent requests with OAuth.

For more information about using OAuth with Google APIs, please see this documentation.

If you have any questions about using OAuth with the client libraries, you can ask us on the forum.

Edit: the link describing how accounts are provisioned for you in the AdWords API sandbox was omitted in the original blog post.  This link has been updated and is located here.

Kevin Winter, AdWords API Team

AdWords API v201109 launch -- providing better targeting and reporting

We’re pleased to announce the launch of AdWords API v201109, which includes upgrades to targeting and reporting. We’ve highlighted some of the new features below. A complete list of changes is available in the release notes.  

v201109 highlights:

• Reporting: We have made several changes aimed at making reporting easier to use.
• Downloading reports is now free and does not require a stored ReportDefinition.
• We have added the ability to exclude zero impression rows, with an explicit flag.
• New “criteria” report lets you download all criteria data at once.
• We have added new data on call metrics.
• Geo targeting: We have been making several improvements to our location targeting services and are launching these in the API. We have created a new LocationCriterionService to look up geo criteria. And we have moved all geo targeting to the CampaignCriterionService. 
• Device targeting: In May we launched the ability for advertisers to target users on tablets in our web interface. We have now added this tablet device targeting option to the API. We have also updated the available list of O/S and carrier targets. 
• Asynch and Other: We have enhanced or updated several other existing features.
• The new MutateJobService allows for the scheduling of large batch updates as asynchronous jobs. This service simplifies mutate jobs submissions and will eventually replace BulkMutateJobService.
• We have added support for negative keywords feature in TrafficEstimatorService.
• We have enabled PartialFailure for AdGroupAdService.
• We no longer support email addresses as identifiers, please use Customer IDs instead.

Deprecation timeline for previous versions With the release of v201109, the following versions and services will be deprecated:

• API versions v13, v200909, v201003, v201008, v201101
• Please note: We are not supporting cross-client reports in this release, but we have released some sample code for those of you who need to run reports across many clients.
• API version v13 AccountService will only be available on a whitelist basis.

We will be sunsetting these versions and services at the end of February 2012. 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.

Posted by the AdWords API Team

Using AWCLI (AdWords Command Line Interface)

Earlier this year we released a demo that allows you to run AdWords API queries from the command line. Today, a new version is available and I’d like to point out some of its features.


Accessing production environment

We’ve made a change to reduce a risk of accidentally running the demo tool against a production environment. Since version 1.2.0, an explicit ‘--prod’ flag is required in order to query billable services. Check out ‘awcli --help’ for all available command-line options.


Automatic batch mode

AWCLI can now run in interactive or batch mode and detects the required mode automatically. In interactive mode, you will get a prompt to type your commands:

awcli:/>

In batch mode, any extra input is suppressed and the application exits after a command completes. This makes it easier to use the tool in shell scripts:

bash $ echo ls | ./awcli.sh
    #1 Campaign Name [69266990]
    [...]
bash $

You can also specify a command and its parameters as extra arguments to the tool itself:

bash $ ./awcli.sh --prod ls 69266990
    #1 AdGroup name [2390064350]
    [...]
bash $

Browsing Ad Parameters

A new CriterionLocation was added which allows you to browse Criteria. This enables you to list and view AdParams associated with your criteria:

bash $ ./awcli.sh [options] ls <campaign_id>/<adgroup_id>/<criterion_id>
    #1 $100 [1]
    #2 50 [2]
bash $

...and even edit them: 'edit #1' will spawn your configured editor. The changes will be automatically applied when you save and exit.


Querying stats

You can combine AWCLI output with other command-line tools to retrieve parts of the information you need. For example, you can use Unix filters to obtain ad group stats:

bash $ ./awcli.sh --prod cat <campaign_id>/<adgroup_id> | grep -E "clicks|impressions"
        clicks = 12,
        impressions = 160,
bash $

Getting AWCLI

AWCLI is available from the Google Code page and is part of the AdWords Java API client libraries project. You can find installation and running instructions as well as usage examples on the wiki page. Please join us to discuss the tool and report any issues on the project page or forum.


Danial Klimkin, AdWords API Team.