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