Bid Landscapes

Bid landscapes allow you to estimate performance for your ad groups, criteria, and campaigns under different bidding scenarios. You can use this information to adjust and optimize your bidding strategy.

The bid landscape services of the API predict how changing your bid in various ways impacts cost, impressions, and clicks. This is analogous to bid simulators in the AdWords user interface.

Use case

Imagine you have an ad that's been running for a few weeks, that's costing a lot more than you expected or wanted to spend.

You want to test what might happen if you lower your bids a little. How many fewer views and clicks would your ad get? How much less would it cost? Conversely, what if your ad isn't getting the amount of impressions and clicks you expect, and you want to know where you should set your bids to fix that problem?

Bid landscapes help you research these scenarios. When you fetch a bid landscape, it shows projected views, clicks, and cost during the same time period your ad was showing.

With bid landscapes you can examine performance statistics for the past week at the current level of bidding, alongside simulated performance over the same time period using different bid amounts.

By analyzing how your ads might have performed differently in the past, you can make more informed decisions about how to adjust your bids and campaign-level bid modifiers for the future.


To use bid landscapes, the campaign must meet the following requirements:

  • You must have an established criterion, ad group, or campaign to provide the system with baseline information from which to generate predictions.
  • Conversion tracking must be enabled.
  • The account must not be a test account. Bid landscapes are based on past performance; since test accounts don't serve ads, they have no performance history.

Additionally, only information pertaining to the Search Network portion of a campaign is returned; bid landscapes don't work with Display Network data.

Making a request

When retrieving bid landscape data, the API service returns a BidLandscape object, with information about the time range, campaign, ad group, or criterion on which the data is focused. The time range is always in the past, as bid landscapes predict how your ads would have performed at those times and under the same conditions, but with different bid or campaign-level bid modifiers.

The BidLandscape also includes a sequence of landscape points which taken together, provide a histogram of the predicted performance with different bids or campaign-level mobile bid modifiers during that timeframe.

There are three kinds of bid and mobile bid modifier landscapes you can request through the DataService. The landscape you choose depends on the level at which you want to adjust bidding: criterion, ad group, or campaign. The get() or query() methods are named accordingly:

Fetching bid landscapes for criteria and ad groups

In the example below, assume that bids are set at a criterion level; the process for fetching bid landscapes for ad groups is similar.

Fetching bid landscapes works similarly to making any other query: select the fields you want, set up the predicates to restrict the query to only the ad groups or criteria you're interested in, and then make a get() or query() call to fetch the data.

The BidLandscape and LandscapePoint reference documentation lists all valid filterable and selectable fields.

Whether the field you're interested in is in the BidLandscape or LandscapePoint, you include it in the same selector or predicate. Note that the BidModifier, TotalLocalClicks, TotalLocalCost, TotalLocalImpressions, and RequiredBudget fields are only supported for campaign mobile bid modifier landscape requests. When the data is returned, the fields are automatically put in the appropriate place in the SOAP and client library implementations. Fields on the LandscapePoints will be populated for each LandscapePoint returned within the BidLandscape.


// Get the DataService.
DataServiceInterface dataService = adWordsServices.get(session, DataServiceInterface.class);

// Create selector.
Selector selector =
    new SelectorBuilder()
        .equals(DataField.AdGroupId, adGroupId.toString())
        .equals(DataField.CriterionId, criterionId.toString())

CriterionBidLandscapePage page = dataService.getCriterionBidLandscape(selector);

Fetching mobile bid modifier landscapes for campaigns

You fetch campaign-level mobile bid modifier landscapes much like you fetch bids at the ad group / criterion level. Fields on the LandscapePoints will be populated for each LandscapePoint returned within the BidLandscape. Refer to the reference documentation for BidLandscape and LandscapePoint to see which fields are selectable and filterable. Whether a field is in BidLandscape or LandscapePoint, you should include it in the same selector or predicate.

This example shows how to fetch campaign-level mobile bid modifier landscapes:


// Get the DataService.
DataServiceInterface dataService = adWordsServices.get(session, DataServiceInterface.class);

// Create selector.
Selector selector =
    new SelectorBuilder()
        .equals(DataField.CampaignId, campaignId.toString())

CriterionBidLandscapePage page = dataService.getCampaignCriterionBidLandscape(selector);

Paging through results

The behavior of CriterionBidLandscapePage (returned by [get|query]CriterionBidLandscape and [get|query]CampaignCriterionBidLandscape) and AdGroupBidLandscapePage (returned by [get|query]AdGroupBidLandscape) differs from other page types. Instead of incrementing paging.startIndex and making requests until paging.startIndex >= page.totalNumEntries, for a bid landscape request you should:

  • Increment paging.startIndex by the number of inner landscape points found in each response.
  • Continue making requests until the number of inner landscape points found in the last response is less than the paging.numberResults (page size) you specified on your selector.

The example below demonstrates how you could implement this logic.


// Display bid landscapes.
int landscapePointsInPreviousPage = 0;
int startIndex = 0;
do {
  // Offset the start index by the number of landscape points in the last retrieved page,
  // NOT the number of entries (bid landscapes) in the page.
  startIndex += landscapePointsInPreviousPage;

  // Reset the count of landscape points in preparation for processing the next page.
  landscapePointsInPreviousPage = 0;

  // Request the next page of bid landscapes.
  CriterionBidLandscapePage page = dataService.getCriterionBidLandscape(selector);

  if (page.getEntries() != null) {
    for (CriterionBidLandscape criterionBidLandscape : page.getEntries()) {
          "Criterion bid landscape with ad group ID %d, criterion ID %d, "
              + "start date %s, end date %s, with landscape points:%n",

      for (BidLandscapeLandscapePoint bidLanscapePoint :
          criterionBidLandscape.getLandscapePoints()) {
            "\t{bid: %d clicks: %d cost: %d impressions: %d}%n",
      System.out.println(" was found.");
} while (landscapePointsInPreviousPage >= PAGE_SIZE);

Understanding the results

The results return various bids and the expected performance at those levels. Here's an example of an XML response you might get when making one of these requests.


All the possible elements you can get back from the LandscapePoints are represented above. The promotedImpressions value signifies the number of times the impression was in a "promoted" position (at the top) of the search page.

The XML snippet above shows one LandscapePoint, but each BidLandscape will have a sequence of these points, with a different bid or mobile bid modifier amount, and with corresponding stats adjusted to account for the changed bid or bid modifier. It's up to you to interpret the results, but the data provided should offer useful information to determine how tweaking your bids and mobile bid modifiers might impact performance.


Code examples

Each client library contains complete code examples for retrieving keyword and campaign bid modifier simulations in its Optimization folder:

Wyślij opinię na temat...

Potrzebujesz pomocy? Odwiedź naszą stronę wsparcia.