Bidding

AdWords gives you several ways to bid for your ads, depending on what matters most to you and your business.

In the AdWords API, all bidding parameters are managed via one or both of the following:

With either object, you can use its biddingStrategyType field, its biddingScheme field, or both, to specify a bidding type. The biddingScheme allows you to set additional parameters specific to a bidding type. When both fields are specified, their types must match.

Strategy types

In the table below, the Valid Contexts column indicates whether a given BiddingStrategyType and associated BiddingScheme type can be used in one or both of the contexts mentioned above:

  • A standard strategy with a BiddingStrategyConfiguration object.
  • A portfolio strategy with a SharedBiddingStrategy object.
BiddingStrategyType BiddingScheme Descriptive name Valid Contexts
BUDGET_OPTIMIZER

Deprecated. Use TARGET_SPEND instead.

BudgetOptimizerBiddingScheme Budget optimizer Standard
CONVERSION_OPTIMIZER

Deprecated starting with v201603. Use TARGET_CPA instead.

ConversionOptimizerBiddingScheme Focus on conversions - use CPA bids Standard
ENHANCED_CPC EnhancedCpcBiddingScheme Enhanced CPC Portfolio
MANUAL_CPC ManualCpcBiddingScheme Focus on clicks - use maximum CPC bids Standard
MANUAL_CPM ManualCpmBiddingScheme Focus on impressions Standard
PAGE_ONE_PROMOTED PageOnePromotedBiddingScheme Target search page location Portfolio
TARGET_CPA TargetCpaBiddingScheme Target cost per acquisition (CPA) - must meet eligibility requirements Portfolio (all versions)
Standard (starting with v201603)
TARGET_OUTRANK_SHARE TargetOutrankShareBiddingScheme Target outranking share Portfolio
TARGET_ROAS TargetRoasBiddingScheme Target return on ad spend - must meet eligibility requirements Portfolio
TARGET_SPEND TargetSpendBiddingScheme Maximize clicks Portfolio (all versions)
Standard (starting with v201603)

Errors result if you try to use a BiddingStrategyType or BiddingScheme in the wrong context:

  • Using a portfolio-only type or scheme in the context of a standard strategy generates a BiddingErrors error with reason INVALID_ANONYMOUS_BIDDING_STRATEGY_TYPE.
  • Using a standard-only type or scheme in the context of a portfolio strategy generates a BiddingErrors error with reasonBIDDING_STRATEGY_NOT_SUPPORTED.

Setting bids

Bids can be set at the ad group and ad group criterion levels. A criterion bid will override an ad group bid.

Multiple bids of different types can be set in a single strategy simultaneously (for example, CpcBid and CpmBid) but only the bid that matches the selected biddingStrategyType will be used.

Reporting also returns only the currently active bid. If you transition to a different bidding type the corresponding bid is used.

The following code example uses a mutate call to add a CPC bid at the ad group level.

// Create ad group bid.
BiddingStrategyConfiguration biddingStrategyConfiguration =
    new BiddingStrategyConfiguration();
CpcBid bid = new CpcBid();
bid.setBid(new Money(null, 10000000L));

// You can optionally provide this field.
bid.setContentBid(new Money(null, 20000000L));

biddingStrategyConfiguration.setBids(new Bids[] {bid});
adGroup.setBiddingStrategyConfiguration(biddingStrategyConfiguration);

// Create operation.
AdGroupOperation operation = new AdGroupOperation();
operation.setOperand(adGroup);
operation.setOperator(Operator.SET);
AdGroupOperation[] operations = new AdGroupOperation[] {operation};

// Update ad group.
AdGroupReturnValue result = adGroupService.mutate(operations);

Removing bids

To remove a bid from a BiddingStrategyConfiguration, update its bid field to a Money object with microAmount set to 0.

Bidding strategy transitions

To change a bidding strategy, issue a mutate() call with the updated strategy fields to the corresponding service. The example below illustrates how to change the bidding type for a campaign by setting a different biddingScheme.

// Create a new local Campaign object.
Campaign campaign = new Campaign();
campaign.setId(campaignId);

// Create a new biddingStrategyConfiguration.
BiddingStrategyConfiguration biddingStrategyConfiguration =
    new BiddingStrategyConfiguration();

// You can specify either type or scheme, or both.
biddingStrategyConfiguration.setBiddingScheme(new ManualCpcBiddingScheme());
campaign.setBiddingStrategyConfiguration(biddingStrategyConfiguration);

// Create SET operation.
CampaignOperation operation = new CampaignOperation();
operation.setOperand(campaign);
operation.setOperator(Operator.SET);
CampaignOperation[] operations = new CampaignOperation[] {operation};

// Update the campaign.
CampaignReturnValue result = campaignService.mutate(operations);

Portfolio bid strategies

You can use portfolio bid strategies with your campaigns, ad groups, or keywords.

Use the BiddingStrategyService to create a SharedBiddingStrategy and set its parameters. For example, to use an existing portfolio bid strategy for a campaign, update the campaign's biddingStrategyConfiguration with the strategy's ID:

BiddingStrategyConfiguration biddingStrategyConfiguration = new BiddingStrategyConfiguration();
biddingStrategyConfiguration.setBiddingStrategyId(strategyId);

campaign.setBiddingStrategyConfiguration(biddingStrategyConfiguration);

Content network criteria dimensions

For ads running on the Content Network, there are a number of different dimensions for which an ad group bid can be set. If multiple bids are set in different dimensions, the contentBidCriterionTypeGroup field can be used to specify the dimension that should be used for absolute bids. Ads on the search network will always use keyword bids.

You can also set a bid adjustment which will be used when the criterion is not in an absolute bidding dimension. It can be accessed via the bidModifier field of the BiddableAdGroupCriterion.

Bid modifiers

Campaign and ad group level bid adjustments give you more control over your bids in AdWords campaigns, providing the option to increase or decrease bids for certain criteria.

Within the AdWords API, campaign level adjustments are accessible via CampaignCriterionService, and ad group level adjustments are accessible via AdGroupBidModifierService.

Important changes to platform bid adjustments

In v201603 and earlier, bid adjustments for Platform criteria were only supported for the HighEndMobile criterion (ID=30001). Starting with v201605, you can make bid adjustments for all Platform IDs, but only on test accounts. Support for production accounts will be added in the coming months.

As a result of these changes, you should review your application's bidding functionality, particularly if your application calculates base bids or device (Platform) adjustments.

  • If your code surfaces bid information (max CPC) via a user interface, we recommend also surfacing device bid adjustments (tablet, desktop, and mobile) so users have visibility into the actual bids by device type.

  • Your code should no longer assume that max CPC equates to desktop/tablet bids when calculating bids and/or device bid adjustments. For instance, if you're calculating a recommended mobile bid adjustment, you may need to take into account the desktop bid modifier.

Retrieving bid adjustments

To retrieve existing bid adjustments, use the get() or query() method of CampaignCriterionService or AdGroupBidModifierService. Similar to other services, the get() method accepts a generic selector allowing you to select response fields and filter the results set.

The code below retrieves the first 10 existing campaign-level platform criteria across all your campaigns:

// Get the CampaignCriterionService.
CampaignCriterionServiceInterface campaignCriterionService =
    adWordsServices.get(session, CampaignCriterionServiceInterface.class);

// Create a selector that limits to the first 10 platform criteria found.
Selector selector =
    new SelectorBuilder()
        .fields(
            CampaignCriterionField.CampaignId,
            CampaignCriterionField.Id,
            CampaignCriterionField.CriteriaType,
            CampaignCriterionField.BidModifier)
        .equals(CampaignCriterionField.CriteriaType, "PLATFORM")
        .equals(CampaignCriterionField.IsNegative, "false")
        .limit(10)
        .build();

// Make a 'get' request.
CampaignCriterionPage campaignCriterionPage = campaignCriterionService.get(selector);

// Display the results.
if (campaignCriterionPage.getEntries() != null) {
  for (CampaignCriterion campaignCriterion : campaignCriterionPage.getEntries()) {
    String value =
        campaignCriterion.getBidModifier() == null
            ? "unset"
            : String.format("%.2f", campaignCriterion.getBidModifier());
    System.out.printf(
        "Campaign ID %d, criterion ID %d has campaign level bid modifier %s.%n",
        campaignCriterion.getCampaignId(), campaignCriterion.getCriterion().getId(), value);
  }
} else {
  System.out.println("No campaign criteria found.");
}

Adding, updating and removing bid adjustments

Use the mutate() method of CampaignCriterionService or AdGroupBidModifierService to add or amend a bid adjustment:

  • To add a new bid modifier use the ADD operator.
  • To update an existing bid override to a new value, use the SET operator.
  • To remove a bid modifier override, use the REMOVE operator.

This example demonstrates how to add a new campaign level mobile bid adjustment:

// Get the CampaignCriterionService.
CampaignCriterionServiceInterface campaignCriterionService =
    adWordsServices.get(session, CampaignCriterionServiceInterface.class);

// Create mobile platform. The ID can be found in the documentation.
// https://developers.google.com/adwords/api/docs/appendix/platforms
Platform mobile = new Platform();
mobile.setId(30001L);

// Create criterion with modified bid.
CampaignCriterion campaignCriterion = new CampaignCriterion();
campaignCriterion.setCampaignId(campaignId);
campaignCriterion.setCriterion(mobile);
campaignCriterion.setBidModifier(BID_MODIFIER);

// Create SET operation.
CampaignCriterionOperation operation = new CampaignCriterionOperation();
operation.setOperand(campaignCriterion);
operation.setOperator(Operator.SET);

// Update campaign criterion.
CampaignCriterionReturnValue result =
    campaignCriterionService.mutate(new CampaignCriterionOperation[] {operation});
for (CampaignCriterion campaignCriterionResult : result.getValue()) {
  System.out.printf("Campaign criterion with campaign ID %d, criterion ID %d, "
      + "and type '%s' was modified with bid %.4f.%n",
      campaignCriterionResult.getCampaignId(),
      campaignCriterionResult.getCriterion().getId(),
      campaignCriterionResult.getCriterion().getType(),
      campaignCriterionResult.getBidModifier());
}

Send feedback about...

AdWords API
AdWords API
Need help? Visit our support page.