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