Discover v2009: Do more with mutate

Thursday, March 25, 2010

In previous versions of the API, services had separate methods for adding, updating, and removing items in an AdWords account. The v2009 version changed this paradigm and combined the functionality into a single method called mutate. The mutate method works on operations, where each operation defines the action to perform (operator) and the item to perform it against (operand).

While it may not be immediately obvious, the mutate method is designed to process many operations in one call. For example, the following method uses the PHP client library to add multiple keywords in one request.

function addKeywords($keywords, $adGroupId, $adGroupCriterionService) {
$operations = array();

foreach ($keywords as $keyword) {
// Create biddable ad group criterion.
$adGroupCriterion = new BiddableAdGroupCriterion();
$adGroupCriterion->adGroupId = $adGroupId;
$adGroupCriterion->criterion = $keyword;

// Create operation.
$operation = new AdGroupCriterionOperation();
$operation->operand = $adGroupCriterion;
$operation->operator = 'ADD';

// Add operation to array.
$operations[] = $operation;

// Make mutate request.
$results = $adGroupCriterionService->mutate($operations);

return $results;

It’s important to note that performing multiple operations in one request can be substantially faster then performing them one at a time. Making any request to the AdWords API comes with a certain amount of overhead, so performing more work per request can dramatically improve the performance of your application. For example, in a simple test I ran adding 500 keywords in a single request was over 100x faster than performing 500 separate requests.

Also of note is that the operations in a mutate request can contain any mixture of operators and span any number of campaigns, ad groups, etc. That means you can add a keyword to one ad group and update a keyword in a different ad group in the same request.

More information on the mutate method of a service and the operations it supports can be found in the developer documentation, and any questions you have can be posted to the forum.

- Eric Koleda, AdWords API Team

Alert: 30 days before major v13 sunset

Tuesday, March 23, 2010

Attention AdWords API developers: you now have just 30 days to migrate your application to the new AdWords API. On April 22, most v13 services will be sunset. We announced version v200909 on October 22, 2009 and told you that in six months we would sunset most v13 services. If you have not begun migrating your application to v200909, it’s very important that you start right away.

Be sure to follow us on Twitter for the latest news, tips, and tricks about the AdWords API and please post your migration questions to the Developer Forum.

– Jason Shafton, Product Marketing Manager

AdWords Downtime: March 20th, 10am-2pm PDT

Wednesday, March 17, 2010

We'll be performing routine system maintenance on Saturday, March 20th from approximately 10:00am to 2:00pm PDT. You won't be able to access AdWords or the API during this time frame, but your ads will continue to run as normal.

- Eric Koleda, AdWords API Team