Discover v201008: Partial Failure for AdGroupCriterionService

With v201008 of the AdWords API we have introduced a new beta feature for AdGroupCriterionService: Partial Failure. Typically all requests to the AdWords API are atomic, so each of them either fails or succeeds in full. While this can be helpful to maintain consistency, we’ve heard from you that, in some cases, you would prefer that some operations fail while other changes are applied.

AdGroupCriterionService requests often contain many Criteria to add or update. Having an error in just one of them will force you to resend the whole set of objects again. We’ve introduced Partial Failure to enable you to get back a list of failed and successful operations and retry the failed ones only.

To utilize the new feature you’ll need to set this extra SOAP header:

partialFailure = true

Here’s an example from the Java client library:

// usual initialization code
AdWordsUser user = new AdWordsUser();
// Enable partial failure
user.setUsePartialFailure(true);
// Get the AdGroupCriterionService
AdGroupCriterionServiceInterface adGroupCriterionService =
  user.getService(AdWordsService.V201008.ADGROUP_CRITERION_SERVICE);
// Set up operations and operands here
List<AdGroupCriterionOperation> operations = new ArrayList<AdGroupCriterionOperation>();
// [...]

// Execute operations (add ad group criteria)
AdGroupCriterionReturnValue result =
  adGroupCriterionService.mutate(operations.toArray(
      new AdGroupCriterionOperation[] {}));

Now processing succeeded results:

// Display results
if ((result != null) && (result.getValue() != null)) {
  // A result is returned for every operation requested
  for (AdGroupCriterion adGroupCriterionResult : result.getValue()) {
    // Successful operation result will contain a non-null Criterion
    if (adGroupCriterionResult.getCriterion() != null) {
      System.out.printf("Ad group criterion with ad group id '%d', and " +
          "criterion id '%d', and keyword '%s' was added.\n",
          adGroupCriterionResult.getAdGroupId(),
          adGroupCriterionResult.getCriterion().getId(),
          ((Keyword) adGroupCriterionResult.getCriterion()).getText());
    }
  }
} else {
  System.out.println("No ad group criteria were added.");
}

Here is how to handle the failed operations:

// Is there any Partial Failure errors in the results?
if ((result != null) && (result.getPartialFailureErrors() != null)) {
  // Retrieving ApiError object for each of failures
  for (ApiError apiError : result.getPartialFailureErrors()) {
    // The order of the fields might be different to the order of operations in the
    // request, so we are getting the corresponding operation index from the fieldPath.
    Matcher matcher = operationIndexPattern.matcher(apiError.getFieldPath());
    if (matcher.matches()) {
      int operationIndex = Integer.parseInt(matcher.group(1));
      AdGroupCriterion adGroupCriterion =
          operations.get(operationIndex).getOperand();
      System.out.printf("Ad group criterion with ad group id '%d' and " +
          "keyword '%s' triggered a failure for the following reason: '%s'.\n",
          adGroupCriterion.getAdGroupId(),
          ((Keyword) adGroupCriterion.getCriterion()).getText(),
          apiError.getErrorString());
    } else {
      System.out.printf(
          "A failure for the following reason: '%s' has occurred.\n",
          apiError.getErrorString());
    }
  }
}

Partial Failure is fully supported in our client libraries. If you have any questions please post them on the AdWords API forum. This topic is also covered in a video presentation.

-- Danial Klimkin, AdWords API Team.

Discover v201008: Remove incomplete BulkMutateJobs

The v201008 release of the AdWords API added a new feature to the BulkMutateJobService: the ability to remove incomplete jobs. This allows you to clean out your job queue after an application crash or other failure. In this post we’ll demonstrate how to use the feature and discuss some of its limitations.

When a BulkMutateJob is created the field numRequestParts is set, which determines how many BulkMutateRequest objects will be added to the job. Once the final request part has been added, the job enters into the account’s job queue, and when it reaches the front of the queue it begins processing. If the application crashes while the parts are being uploaded, the job will never start and remain stranded in the account.

Jobs that are incomplete and those that are complete but waiting in the queue behind a processing job will both have a PENDING status. An account can only have 10 pending jobs at a time, so stranded jobs can begin to fill up the account, until eventually no new jobs can be added. Prior to v201008 the only way to remove stranded jobs was to add the missing request parts so that the job would start. If the job had been stranded for a while though, the operations that were previously uploaded may make undesired changes to the account.

In v201008 the REMOVE operator can be used to delete incomplete jobs. The following code does this using the PHP client library.

$bulkMutateJobId = (float) 'INSERT_BULK_MUTATE_JOB_ID_HERE';

// Create BulkMutateJob.
$bulkMutateJob = new BulkMutateJob();
$bulkMutateJob->id = $bulkMutateJobId;

// Create operation.
$operation = new JobOperation();
$operation->operand = $bulkMutateJob;
$operation->operator = 'REMOVE';

// Delete bulk mutate job.
$bulkMutateJob = $bulkMutateJobService->mutate($operation);

After being removed, the job will be in the FAILED state and the failureReason field will contain JobError.USER_CANCELED_JOB.

A limitation of the REMOVE operator is that it only works on jobs that are in the PENDING state and that are incomplete (numRequestParts > numRequestPartsReceived). Jobs that are complete and have already entered the job queue, whether they be in the PENDING or PROCESSING state, cannot be deleted.

Code examples that show how to delete jobs are included in all of the client libraries. If you have any questions about this functionality or the BulkMutateJobService, ask us on the forum.

- Eric Koleda, AdWords API Team

Discover 201008: CustomerSyncService - So what’s new?

We recently released the second part of the v201008 version of the AdWords API and with it the CustomerSyncService - the AdWords API’s first service to determine the entities that were changed in your account. In this blog post, I’ll discuss our goals for the new service and provide a few examples illustrating how to integrate it with your system.

At our developer workshops, we received lots of great feedback about what you’d eventually like to see in this service. Please keep sharing your feedback with us on our forum.

Getting started

Central to the service is the CustomerSyncService.get method. You’ll use this method to retrieve all entities that have changed within the account for a given date time range and set of campaign IDs. As an example, to select all changes to campaign with id 12345 yesterday (today being October 27th), you would do something like:

// Create date time range.
DateTimeRange dateTimeRange = new DateTimeRange();
dateTimeRange.setMin(“20101026 000000”);
dateTimeRange.setMax(“20101027 000000”);

// Create selector.
CustomerSyncSelector selector = new CustomerSyncSelector();
selector.setDateTimeRange(dateTimeRange);
selector.setCampaignIds(new long[] {12345L});

// Get all account changes for campaign.
CustomerChangeData accountChanges = customerSyncService.get(selector);

The result will be a CustomerChangeData object with the entities that changed over the last day for the campaign specified; for the date time range you specified and the single campaign ID, you would only get one CampaignChangeData object back from within the accountChanges variable. If you had specified more than one campaign ID, you would get back one CampaignChangeData object per campaign.

Syncing up

The general way you can use the service is to:

1. Get a full list of all current campaigns by performing a CampaignService.get with an empty selector and collect the IDs.
2. Choose a date time range. This could depend on how granular you want your results, or when you last ran the service.
3. Create a CustomerSyncSelector incorporating all of the campaign IDs and the date time range.
4. Run CustomerSyncService.get with the selector.
5. Process the results by traversing the CustomerChangeData object.
6. Fetch the new data of the entties for all of the IDs within the CustomerChangeData hierarchy using their respective services

The goal of the CustomerSyncService is to give you a consolidated overview of what has changed over a time period; changes will be grouped together based on their overall outcome. Because of this, the dateTimeRange property will largely determine how your results are consolidated.

If you added a campaign to your account on the previous day, for example, you would receive a CampaignChangeData object with the campaignChangedStatus field set to NEW. Imagine now that you changed the campaign later that day as well. If the service returned a single CustomerChangeData object for each change, there would be two objects within the CustomerChangeData - one for the “new” event and one for the “modified” event. Instead, the two events will be consolidated into one object with the status set to NEW, not FIELDS_CHANGED. If you, however, split the service call into two date time ranges, one before the modification and one after, the first call would return a CampaignChangeData object with the status of NEW, and the second call would return a CampaignChangeData object with the status of FIELDS_CHANGED.

The same consolidation principle applies to child objects also. As an example, imagine you create a campaign, modify it later that day, then create an ad group, and then also modify that ad group later that day. The resulting CustomerChangeData object would resemble:

<rval>
...
  <changedCampaigns>
    <status>NEW</status>
    ...
  </changedCampaigns>
</rval>

Notice that not only is the status field is set to NEW, not FIELDS_CHANGED, but  also ad groups have been omitted even though they were also modified that day. Since the campaign is new, all of the entities within that object would also be new. Because of this, you would only get 1 CustomerChangeData object with no AdGroupChangeData within in it.

As a final example, imagine that you create an ad group into an existing campaign and modify the budget of the campaign during the same time period. The resulting CustomerChangeData object would be:

<rval>
...
  <changedCampaigns>
    <status>FIELDS_MODIFIED</status>
    ...
    <changedAdGroups>
        <status>NEW</status>
        ...
    </changedAdGroups>
  </changedCampaigns>
</rval>

Notice here that since the campaign already existed and the budget was changed, the status is FIELDS_MODIFIED. If the ad group had just been added, and the campaign budget left alone, the status for the campaign would be FIELDS_UNMODIFIED. Because you see the status is not FIELDS_UNMODIFIED, you know to fetch the campaign from the API, as well as the ad group, while syncing.

We believe the CustomerSyncService provides a great new way to save you time from scouring your account for changes. We’re looking forward to your feedback on our forum and look forward to seeing what you create with it.

-- Adam Rogal, AdWords API Team

Discover v201008: Remarketing

Version v201008 of the AdWords API introduces the UserListService and the CriterionUserList which give you API access to the features available in the ‘Audiences’ tab in the AdWords interface. To learn more about remarketing, visit the AdWords Help Center.

You can set up remarketing using the AdWords API in two steps:

1. Create a remarketing list.
2. Create a CriterionUserList to tie your list to an AdGroup.

We’ve also included short code snippets showing you how to manage LogicalUserLists, also known as custom combination lists, and how to monitor your user list size.

Create a remarketing list

Creating a remarketing list involves the creation of two separate entities: the RemarketingList itself and its associated UserListConversionTypes also known as remarketing tags. The following code shows how to create a remarketing list.

// Get the UserListService.
UserListServiceInterface userListService =
    user.getService(AdWordsService.V201008.USER_LIST_SERVICE);

// Create conversion type (remarketing tag).
UserListConversionType conversionType = new UserListConversionType();
conversionType.setName("Mars cruise customers #" + System.currentTimeMillis());

// Create remarketing user list.
RemarketingUserList userList = new RemarketingUserList();
userList.setName("Mars cruise customers #" + System.currentTimeMillis());
userList.setDescription("A list of mars cruise customers in the last year");
userList.setMembershipLifeSpan(365L);
userList.setConversionTypes(new UserListConversionType[] {conversionType});

// Create operations.
UserListOperation operation = new UserListOperation();
operation.setOperand(userList);
operation.setOperator(Operator.ADD);

UserListOperation[] operations = new UserListOperation[] {operation};

// Add user list.
userList = userListService.mutate(operations).getValue()[0];

Tie a remarketing list to an AdGroup

A new type of criteria object called CriterionUserList is now part of v201008. Through this type of criteria you are able to tie a UserList to an AdGroup. As with other types of criteria, this type is also managed through the AdGroupCriterionService. The following code shows you how to create a CriterionUserList and tie it to an existing AdGroup.

// Create user list criteria.
CriterionUserList userListCriteria = new CriterionUserList();
userListCriteria.setUserListId(userList.getId());

// Create biddable ad group criterion.
BiddableAdGroupCriterion userListBiddableAdGroupCriterion = new BiddableAdGroupCriterion();
userListBiddableAdGroupCriterion.setAdGroupId(adGroupId);
userListBiddableAdGroupCriterion.setCriterion(userListCriteria);

// Create operation.
AdGroupCriterionOperation userListAdGroupCriterionOperation = 
    new AdGroupCriterionOperation();
userListAdGroupCriterionOperation.setOperand(userListBiddableAdGroupCriterion);
userListAdGroupCriterionOperation.setOperator(Operator.ADD);

AdGroupCriterionOperation[] criteriaOperations =
    new AdGroupCriterionOperation[] {userListAdGroupCriterionOperation};

// Add ad group criteria.
adGroupCriterionService.mutate(criteriaOperations);

Custom combination list

It’s also possible through the API to create LogicalUserLists, also known as custom combination lists in the AdWords interface. A LogicalUserList lets you group together other UserLists, which includes RemarketingUserLists and other LogicalUserLists, through a series of UserListLogicalRules. The following code shows you how to create a simple LogicalUserList that combines two other remarketing lists, but it’s possible to create more complex combinations using this type of list.

// Remarketing user lists to be referenced.
UserList list1 = new RemarketingUserList();
list1.setId(remarketingUserListId1);

UserList list2 = new RemarketingUserList();
list2.setId(remarketingUserListId2);

// Create logical user list.
LogicalUserList logicalList = new LogicalUserList();
logicalList.setName("Logical list #" + System.currentTimeMillis());
logicalList.setDescription("A list of two other lists");
logicalList.setMembershipLifeSpan(365L);
logicalList.setRules(new UserListLogicalRule[] {
    new UserListLogicalRule(UserListLogicalRuleOperator.ALL,
       new LogicalUserListOperand[] {
            new LogicalUserListOperand(null, list1),
            new LogicalUserListOperand(null, list2),
    })
});

// Create operation.
UserListOperation operation = new UserListOperation();
operation.setOperand(logicalList);
operation.setOperator(Operator.ADD);

UserListOperation[] operations = new UserListOperation[] {operation};

// Add user list.
UserListReturnValue result = userListService.mutate(operations);

Monitor the size of your list

You also might be interested in monitoring the growth of your list. You can accomplish this by making a simple get() call to the UserListService to retrieve this kind of information. The following code shows you how to retrieve information about all of your user lists.

// Create selector.
UserListSelector selector = new UserListSelector();

// Get all user lists.
UserListPage page = userListService.get(selector);

// Display user lists information.
if (page.getEntries() != null) {
  for (UserList userList : page.getEntries()) {
    System.out.printf("User list with name '%s' has an estimate size of '%d' users.\n",
        userList.getName(), userList.getSize());
  }
}

All code snippets included in this post are based on the AdWords API Java Client Library, other client libraries also include code examples and support for remarketing.

As always, please post your questions about how to use this new service on the forum.

Posted by David Torres, AdWords API Team

Discover v201008 - ServicedAccountService

The ability to retrieve a list of client accounts and their details is useful when you’re managing a large number of accounts using the AdWords API. This was previously possible only with AccountService in the legacy v13 version of the AdWords API. The v201008 version introduces the ServicedAccountService, which brings similar functionality to the new AdWords API. This blog post discusses the differences between the old AccountService and the new ServicedAccountService.

Retrieving client account hierarchy

In v13, you could retrieve the list of client accounts linked to an MCC using the getClientAccounts or getClientAccountInfos methods of AccountService. In the v201008 version of the AdWords API, you can use the get method of ServicedAccountService to get the same results. The following code shows the service in action.

// Get the ServicedAccountService.
ServicedAccountService servicedAccountService =
    (ServicedAccountService) user.GetService(AdWordsService.v201008.
        ServicedAccountService);
 
ServicedAccountSelector selector = new ServicedAccountSelector();
 
try {
  ServicedAccountGraph graph = servicedAccountService.get(selector);
 
  if (graph != null && graph.accounts != null) {
    // Display the accounts.
    Console.WriteLine("There are {0} customers under this account" +
        " hierarchy.", graph.accounts.Length);
    for (int i = 0; i < graph.accounts.Length; i++) {
      Console.WriteLine("{0}) Customer id: {1}\nLogin email: {2}\n" +
          "Company name: {3}\nIsMCC: {4}\n", i + 1,
          graph.accounts[i].customerId, graph.accounts[i].login,
          graph.accounts[i].companyName,
          graph.accounts[i].canManageClients);
    }
  }
} catch (Exception ex) {
  Console.WriteLine("Failed to retrieve accounts. Exception says \"{0}\"",
      ex.Message);
}

ServicedAccountService also allows you to retrieve links that exist between the accounts. To retrieve the links, set the enablePaging field of ServicedAccountSelector to false. The following code shows how to retrieve account links:

selector.enablePaging = false;
selector.serviceTypes = new ServiceType[] { ServiceType.UI_AND_API,
    ServiceType.API_ONLY };
...
...
if (graph != null && graph.accounts != null) {
  // Display the accounts.
  ...
  ...
  // Display the links.
  foreach (Link link in graph.links) {
      Console.WriteLine("There is a {0} link of type {1} from" +
         "{2:###-###-####} to {3:###-###-####}", link.typeOfLink,
         link.serviceType, link.managerId.id, link.clientId.id);
  }
}

An important difference between AccountService.getClientAccounts and ServicedAccountService.get is that getClientAccounts returns only the immediate child accounts, whereas ServicedAccountService.get() returns all of the accounts in the hierarchy. This was harder to do in v13 as you first had to call getClientAccountInfos to find out whether or not a child account is a manager, and then recursively call getClientAccounts to navigate the entire account hierarchy.

To retrieve only the immediate child accounts of your MCC to mimic the behavior of v13’s getClientAccounts method, you can select the relevant accounts as follows:

private Account[] GetClientAccountsForMCC(ServicedAccountGraph graph,
    long mccId) {
  List retval = new List();
  foreach (Link link in graph.links) {
    if (link.managerId.id == mccId) {
      foreach (Account account in graph.accounts) {
        if (account.customerId == link.clientId.id) {
          retval.Add(account);
        }
      }
    }
  }
  return retval.ToArray();
}

Retrieving and updating account information

In v13, you can retrieve and update some fields of a client account using getAccountInfo and updateAccountInfo. This functionality isn’t yet available in v201008, but will be available in a future version of the AdWords API.

Retrieving MCC alerts

In v13, you could retrieve the MCC alerts about your child accounts using getMccAlerts. This functionality is now available through AlertService, another new service introduced in v201008. We will write more about AlertService in a future post.

Please check out this service and share your feedback with us on the forum.

-- Anash P. Oommen, AdWords API Team

Discover v201008: ExperimentService

Access to manage AdWords Campaign Experiments (ACE) has been introduced through the ExperimentService as part of the v201008 version of the AdWords API. Now you are able to configure split test experiments for a campaign through the API. A split test experiment lets you more precisely measure the impact of changes to keywords, bids, ad groups, and placements before you apply them to all auctions. This reduces guesswork and lowers the potential risk. For common usage scenarios and more details, check out this blog post and the AdWords Help Center.

Lets get hands on with the code and see how to use ACE via the AdWords API. The following code snippets are available as part of the Perl client library.

Creating your experiment

You start by defining your experiment, which includes creating the experiment, attaching it to a campaign, setting its start time, end time, and percentage split. You then send an add operation through a service mutate call.

# Create experiment.
my $experiment = Google::Ads::AdWords::v201008::Experiment->new({
  campaignId => $campaign_id,
  name => "Interplanetary Experiment #" . POSIX::strftime("%s", localtime),
  queryPercentage => 10,
  startDateTime => POSIX::strftime("%Y%m%d %H%M%S", localtime)
});

# Create operation.
my $experiment_operation =
    Google::Ads::AdWords::v201008::ExperimentOperation->new({
      operator => "ADD",
      operand => $experiment
    });

# Add experiment.
my $result = $client->ExperimentService()->mutate({
  operations => [$experiment_operation]
});

# Valuable for ValueTrack usage
my $experiment_id = $experiments->get_entries()->[0]->get_id();
my $control_id = $experiments->get_entries()->[0]->get_controlId();

In the last few lines of code, experiment id and control id are extracted from the just-created experiment. These values are important for use with the ValueTrack tag used for campaign tracking and analytics since they uniquely identify which split each click is coming from. For details on using the ValueTrack tag with ACE please consult the AdWords Help Center.

Defining your experimental changes

Now lets apply some bid changes to an existing ad group and assign it to both the experimental and the control splits by using the flag named experimentDeltaStatus. Applying changes to other parts of your campaign are very similar to the following example, refer to the AdGroupExperimentData and the BiddableAdGroupCriterionExperimentData objects in documentation for more information about the experimental changes that can be applied to ad groups and criteria respectively. It is also worth to mention that new ad groups and new criteria can be added to your campaign experiment executing add operations and setting the experimentData to your new objects. You can also check a variety of experiment examples which we included in client libraries.

# Set ad group for the experiment.
my $ad_group = Google::Ads::AdWords::v201008::AdGroup->new({
  id => $ad_group_id
});

# Create experiment bid multiplier rule that will modify ad group bid for the
# experiment.
my $bid_multiplier = 
    Google::Ads::AdWords::v201008::ManualCPCAdGroupExperimentBidMultipliers->
        new({
          maxCpcMultiplier => Google::Ads::AdWords::v201008::BidMultiplier->
              new({
                multiplier => 1.5
              })
        });

# Set experiment data to the ad group.
my $experiment_data =
    Google::Ads::AdWords::v201008::AdGroupExperimentData->new({
      experimentId => $experiment_id,
      experimentDeltaStatus => "MODIFIED",
      experimentBidMultipliers => $bid_multiplier
    });
$ad_group->set_experimentData($experiment_data);

# Create operation.
my $operation = Google::Ads::AdWords::v201008::AdGroupOperation->new({
  operand => $ad_group,
  operator => "SET"
});

# Update ad group.
$experiments = $client->AdGroupService()->mutate({
  operations => [$operation]
});

Deciding to promote or discard your experiment

After you’ve assessed the performance impact of the experimental changes, you can promote or delete the experiment. The following example shows you how to promote your experiment, effectively applying all experimental changes to 100% of your campaign traffic.

# Set experiment's status to PROMOTED.
my $experiment = Google::Ads::AdWords::v201008::Experiment->new({
  id => $experiment_id,
  status => "PROMOTED"
});

# Create operation.
my $experiment_operation =
    Google::Ads::AdWords::v201008::ExperimentOperation->new({
      operator => "SET",
      operand => $experiment
    });

# Update experiment.
my $result = $client->ExperimentService()->mutate({
  operations => [$experiment_operation]
});

Promoting an experiment applies all changes in the experimental split to your campaign. All control only elements become paused. Everything else running in both control and experiment splits continues running as normal.

If you don’t like the performance impact you see with the experiment, you can delete it by sending a mutate operation with the experiment status set as DELETED. Deleting an experiment will effectively discard any changes and additions assigned to the experimental split.

Like other products in beta, ACE has some core features still undergoing active development. Reporting is one area that’s getting special attention. Currently, getting performance data segmented by experiment and control splits is not supported through the AdWords API. Until it’s available, you can pull click and conversion data for each split from a tracking system using ValueTrack tags, as described above. Alternatively, experiments can be implemented so that every ad group is either control only or experiment only. You can then aggregate results for each campaign split using each ad group’s experimentDeltaStatus and check for statistically significant differences. A final interim solution is for users to log into the AdWords UI to check segmented performance stats.

If you have any questions about how to use this service we’ll be happy to address them on the forum. Have fun experimenting.

Best,
- David Torres, AdWords API Team

Discover v201008: TrafficEstimatorService upgrade

The TargetingIdeaService is a powerful tool for generating new keyword ideas and getting statistics about how those keywords perform globally. However, for more personalized estimates of how a keyword may perform in your account, the TrafficEstimatorService can be used. While this service was previously only available in the legacy v13 version of the AdWords API, it’s now available in v201008 with some slight changes.

Estimate Requests

While the v13 service provided separate methods for getting keywords estimates with and without an ad group or campaign context, the v201008 version has been simplified to use just a single get() method. This means that KeywordEstimateRequest objects must always be wrapped in AdGroupEstimateRequest and CampaignEstimateRequest objects, even if you don’t want to use the features those objects offer. Keep in mind though that specifying contextual information in estimate requests, especially the ids of existing ad groups and campaigns, can lead to more accurate estimates and is recommended when possible.

The CampaignEstimateRequest object allows you to set or override the targeting options for the estimation using the targets field. While this field accepts an array of any target type only the following are currently supported: LanguageTarget and GeoTarget, which itself is limited to only CountryTarget, CityTarget, MetroTarget, and ProvinceTarget. More information about the behavior of targeting is available here.

The following PHP example code demonstrates how to build up the estimate requests for three new keywords in a new ad group with a default bid of $1, in a new campaign that targets users in the US who speak English.

  // Create keywords. Up to 2000 keywords can be passed in a request.
  $keywords = array();
  $keywords[] = new Keyword('mars cruise', 'BROAD');
  $keywords[] = new Keyword('cheap cruise', 'PHRASE');
  $keywords[] = new Keyword('cruise', 'EXACT');

  // Create a keyword estimate request for each keyword.
  $keywordEstimateRequests = array();
  foreach ($keywords as $keyword) {
    $keywordEstimateRequest = new KeywordEstimateRequest();
    $keywordEstimateRequest->keyword = $keyword;
    $keywordEstimateRequests[] = $keywordEstimateRequest;
  }

  // Create ad group estimate requests.
  $adGroupEstimateRequest = new AdGroupEstimateRequest();
  $adGroupEstimateRequest->keywordEstimateRequests = $keywordEstimateRequests;
  $adGroupEstimateRequest->maxCpc = new Money(1000000);
  $adGroupEstimateRequests = array($adGroupEstimateRequest);

  // Create campaign estimate requests.
  $campaignEstimateRequest = new CampaignEstimateRequest();
  $campaignEstimateRequest->adGroupEstimateRequests = 
      $adGroupEstimateRequests;
  $campaignEstimateRequest->targets = array(new CountryTarget('US'),
      new LanguageTarget('en'));
  $campaignEstimateRequests = array($campaignEstimateRequest);

  // Create selector.
  $selector = new TrafficEstimatorSelector();
  $selector->campaignEstimateRequests = $campaignEstimateRequests;

Estimated Statistics

While the v13 KeywordEstimate object contained both the minimum and maximum estimated statistics, it has been split into a min and max StatsEstimate object in the v201008 version. This object bundles together the estimated average CPC, average position, clicks and total cost. To get values similar to those returned by the Traffic Estimator web interface you will need to get the mean of the min and max estimates.

The following code shows how to get the estimates for the selector created above and display the results.

  // Get traffic estimates.
  $result = $trafficEstimatorService->get($selector);

  // Display traffic estimates.
  if (isset($result)) {
    $keywordEstimates =
        $result->campaignEstimates[0]->adGroupEstimates[0]->keywordEstimates;
    for ($i = 0; $i < sizeof($keywordEstimates); $i++) {
      $keyword = $keywordEstimateRequests[$i]->keyword;
      $keywordEstimate = $keywordEstimates[$i];

      // Find the mean of the min and max values.
      $meanAverageCpc = ($keywordEstimate->min->averageCpc->microAmount
          + $keywordEstimate->max->averageCpc->microAmount) / 2;
      $meanAveragePosition = ($keywordEstimate->min->averagePosition
          + $keywordEstimate->max->averagePosition) / 2;
      $meanClicks = ($keywordEstimate->min->clicks
          + $keywordEstimate->max->clicks) / 2;
      $meanTotalCost = ($keywordEstimate->min->totalCost->microAmount
          + $keywordEstimate->max->totalCost->microAmount) / 2;

      printf("Results for the keyword with text '%s' and match type '%s':\n",
          $keyword->text, $keyword->matchType);
      printf("  Estimated average CPC: %d\n", $meanAverageCpc);
      printf("  Estimated ad position: %.2f \n", $meanAveragePosition);
      printf("  Estimated daily clicks: %d\n", $meanClicks);
      printf("  Estimated daily cost: %d\n\n", $meanTotalCost);
    }
  } else {
    print "No traffic estimates were returned.\n";
  }

Checking Keyword Traffic

The v13 service included a checkKeywordTraffic() method that could be used to determine if a keyword would get any traffic at all. This method has been removed from the v201008 service, but information about the search volume for a keyword can be obtained by using the TargetingIdeaService and requesting attributes such as AVERAGE_TARGETED_MONTHLY_SEARCHES, GLOBAL_MONTHLY_SEARCHES, or TARGETED_MONTHLY_SEARCHES.

If you have any questions about how to use this service we’ll be happy to address them on the forum.

Best,
- Eric Koleda, AdWords API Team