Discover v2009: Do more with mutate

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