Bid simulator results have moved to the DataService

We introduced the BidLandscapeService in v201003 as a read-only service that allowed developers to retrieve the bid simulator results available for keywords, then extended it to include ad group results in v201008. Looking ahead we foresaw that additional forms of metadata would need to be exposed via the API, so we decided to consolidate these types of features into a single service: the DataService. Today the DataService provides the ability to retrieve bid simulator results and we plan to expand it to include other functionality in future versions of the API.

In addition to relocating the bid simulator feature to a new service, we updated it to support generic selectors. The returned objects haven't changed however, so much of your application logic can remain the same. It's also worth noting that while the BidLandscapeService had a single getBidLandscape() method which would return both criteria and ad group bid simulation results, the DataService has now broken this functionality out into two methods: getAdGroupBidLandscape() and getCriterionBidLandscape().

As a reminder, to get criteria bid simulation results using the v201008 BidLandscapeService you can use the following PHP code:

// Old v201008 code.
$selector = new CriterionBidLandscapeSelector();

$idFilter = new BidLandscapeIdFilter();
$idFilter->adGroupId = $adGroupId;
$idFilter->criterionId= $keywordId;
$selector->idFilters = array($idFilter);

$bidLandscapes = $bidLandscapeService->getBidLandscape($selector);

To accomplish the same task with the v201101 DataService use the following code:

// New v201101 code.
$selector = new Selector();

$selector->fields = array('AdGroupId', 'CriterionId', 'StartDate',
    'EndDate', 'Bid', 'LocalClicks', 'LocalCost', 'MarginalCpc',
    'LocalImpressions');

$adGroupIdPredicate = 
    new Predicate('AdGroupId', 'IN', array($adGroupId));
$criterionIdPredicate =
    new Predicate('CriterionId', 'IN', array($criterionId));
$selector->predicates =
    array($adGroupIdPredicate, $criterionIdPredicate);

$page = $dataService->getCriterionBidLandscape($selector);

Like with all generic selectors you must explicitly list all of the fields you wish to have returned, the names of which can be found in the documentation for CriterionBidLandscape (or AdGroupBidLandscape) and its sub-objects. Also notice that the functionality of the BidLandscapeIdFilter can be replicated by using a combination of predicates, which are always ANDed together.

If you have any questions about the DataService, or how to migrate your bid simulator code, reach out to us on the forum.

 - Eric Koleda, AdWords API Team

Discover v201003: Learn from the past with the Bid Simulator

Have you ever wondered how your keywords could have performed with a different bid? The bid simulator feature released last year allows you to do just that. Using data from the last seven days, it calculates the impressions, clicks, and cost your keywords could have received if different maximum CPC bids were used. This information was previously only exposed in the AdWords web interface, but is now available in the v201003 version of the API with the BidLandscapeService.

The getBidLandscape() method is used to retrieve the bid simulation results, also known as bid landscapes. You can use the selector to filter the results by campaign, ad group, or keyword ID. For example, to retrieve the results for a single keyword using the PHP client library you would use the following code:

  // Create selector.
  $selector = new CriterionBidLandscapeSelector();

  // Create id filter.
  $idFilter = new BidLandscapeIdFilter();
  $idFilter->adGroupId = $adGroupId;
  $idFilter->criterionId= $keywordId;
  $selector->idFilters = array($idFilter);

  // Get bid landscape for keyword.
  $bidLandscapes = $bidLandscapeService->getBidLandscape($selector);

The returned BidLandscape contains a series of LandscapePoints, each of which represents a single simulation for that keyword. It isn’t possible to configure which bids are used in the simulations, but the points are chosen automatically by the system to give an interesting range of data. Each landscape point contains the impressions, clicks, and cost that the keyword could have received at that bid. In addition, it contains the field marginalCpc, which contains the incremental cost-per-click (ICC) at the simulated bid. More information on ICC values and how you can use them is outlined in a video by Google's Chief Economist, Hal Varian. Please note that depending on the recent performance of the keyword, only some of this information may be populated in the landscape point.

Bid simulations are currently only available for campaigns that use ManualCPC bidding and target the GOOGLE_SEARCH or SEARCH_NETWORK networks. Additional restrictions are listed in the AdWords Help Center. The bid simulations are performed automatically in regular intervals, and new keywords or those with no impressions in the last seven days won’t have any associated results. No errors will be thrown when this happens, but the response will not contain a BidLandscape for that keyword.

Example code using the BidLandscapeService is available in the client libraries. Please post any questions about this service to the forum. Additional information about the bid simulator can be found in the Help Center.

- Eric Koleda, AdWords API Team