Google Ads API is returning to beta status. Please read our blog post for more details.

Manage Bid Modifiers

Campaign and ad group-level bid adjustments give you more control over your bids in Google Ads campaigns, providing the option to increase or decrease bids for different types of criteria.

Within the Google Ads API, campaign-level adjustments are accessible via CampaignBidModifierService and ad group-level adjustments are accessible via AdGroupBidModifierService.

Adding, updating, and removing bid adjustments

Use the create, update or remove fields of CampaignBidModifierOperation or AdGroupBidModifierOperation operations to add, amend or remove bid adjustments.

This example demonstrates how to add a new ad group-level mobile bid adjustment:

Java

private void runExample(
    GoogleAdsClient googleAdsClient, long customerId, long adGroupId, double bidModifier) {

  // Creates an ad group bid modifier for mobile devices with the specified ad group ID and
  // bid modifier value.
  AdGroupBidModifier adGroupBidModifier =
      AdGroupBidModifier.newBuilder()
          .setAdGroup(
              StringValue.of(
                  AdGroupName.format(Long.toString(customerId), Long.toString(adGroupId))))
          .setBidModifier(DoubleValue.of(bidModifier))
          .setDevice(DeviceInfo.newBuilder().setType(Device.MOBILE))
          .build();

  // Creates an ad group bid modifier operation for creating an ad group bid modifier.
  AdGroupBidModifierOperation adGroupBidModifierOperation =
      AdGroupBidModifierOperation.newBuilder().setCreate(adGroupBidModifier).build();

  // Issues a mutate request to add the ad group bid modifier.
  try (AdGroupBidModifierServiceClient adGroupBidModifierServiceClient =
      googleAdsClient.getLatestVersion().createAdGroupBidModifierServiceClient()) {
    MutateAdGroupBidModifiersResponse response =
        adGroupBidModifierServiceClient.mutateAdGroupBidModifiers(
            Long.toString(customerId), ImmutableList.of(adGroupBidModifierOperation));

    System.out.printf("Added %d ad group bid modifiers:%n", response.getResultsCount());
    for (MutateAdGroupBidModifierResult mutateAdGroupBidModifierResult :
        response.getResultsList()) {
      System.out.printf("\t%s%n", mutateAdGroupBidModifierResult.getResourceName());
    }
  }
}

C#

public void Run(GoogleAdsClient client, long customerId, long adGroupId,
    double bidModifier)
{
    // Get the AdGroupBidModifierService.
    AdGroupBidModifierServiceClient adGroupBidModifierService =
        client.GetService(Services.V3.AdGroupBidModifierService);

    // Creates an ad group bid modifier for mobile devices with the specified ad group
    // ID and bid modifier value.
    AdGroupBidModifier adGroupBidModifier = new AdGroupBidModifier()
    {
        AdGroup = ResourceNames.AdGroup(customerId, adGroupId),
        BidModifier = bidModifier,
        Device = new DeviceInfo()
        {
            Type = Device.Mobile
        }
    };

    // Creates an ad group bid modifier operation for creating an ad group bid modifier.
    AdGroupBidModifierOperation adGroupBidModifierOperation =
        new AdGroupBidModifierOperation()
        {
            Create = adGroupBidModifier
        };

    // Send the operation in a mutate request.
    try
    {
        MutateAdGroupBidModifiersResponse response =
            adGroupBidModifierService.MutateAdGroupBidModifiers(customerId.ToString(),
                new AdGroupBidModifierOperation[] { adGroupBidModifierOperation });
        Console.WriteLine("Added {0} ad group bid modifiers:", response.Results.Count);
        foreach (MutateAdGroupBidModifierResult result in response.Results)
        {
            Console.WriteLine($"\t{result.ResourceName}");
        }
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}

PHP

public static function runExample(
    GoogleAdsClient $googleAdsClient,
    int $customerId,
    int $adGroupId,
    float $bidModifierValue
) {
    // Creates an ad group bid modifier for mobile devices with the specified ad group ID and
    // bid modifier value.
    $adGroupBidModifier = new AdGroupBidModifier([
        'ad_group' => new StringValue(
            ['value' => ResourceNames::forAdGroup($customerId, $adGroupId)]
        ),
        'bid_modifier' => new DoubleValue(['value' => $bidModifierValue]),
        'device' => new DeviceInfo(['type' => Device::MOBILE])
    ]);

    // Creates an ad group bid modifier operation for creating an ad group bid modifier.
    $adGroupBidModifierOperation = new AdGroupBidModifierOperation();
    $adGroupBidModifierOperation->setCreate($adGroupBidModifier);

    // Issues a mutate request to add the ad group bid modifier.
    $adGroupBidModifierServiceClient = $googleAdsClient->getAdGroupBidModifierServiceClient();
    $response = $adGroupBidModifierServiceClient->mutateAdGroupBidModifiers(
        $customerId,
        [$adGroupBidModifierOperation]
    );

    printf("Added %d ad group bid modifier:%s", $response->getResults()->count(), PHP_EOL);

    foreach ($response->getResults() as $addedAdGroupBidModifier) {
        /** @var AdGroupBidModifier $addedAdGroupBidModifier */
        print $addedAdGroupBidModifier->getResourceName() . PHP_EOL;
    }
}

Python

def main(client, customer_id, ad_group_id, bid_modifier_value):
    ad_group_service = client.get_service('AdGroupService', version='v3')
    ad_group_bm_service = client.get_service('AdGroupBidModifierService',
                                             version='v3')

    # Create ad group bid modifier for mobile devices with the specified ad
    # group ID and bid modifier value.
    ad_group_bid_modifier_operation = client.get_type(
        'AdGroupBidModifierOperation')
    ad_group_bid_modifier = ad_group_bid_modifier_operation.create

    # Set the ad group.
    ad_group_bid_modifier.ad_group.value = ad_group_service.ad_group_path(
        customer_id, ad_group_id)

    # Set the bid modifier.
    ad_group_bid_modifier.bid_modifier.value = bid_modifier_value

    # Sets the device.
    ad_group_bid_modifier.device.type = client.get_type('DeviceEnum',
                                                        version='v3').MOBILE

    # Add the ad group bid modifier.
    try:
        ad_group_bm_response = (
            ad_group_bm_service.mutate_ad_group_bid_modifiers(
                customer_id, [ad_group_bid_modifier_operation]))
    except google.ads.google_ads.errors.GoogleAdsException as ex:
        print('Request with ID "%s" failed with status "%s" and includes the '
              'following errors:' % (ex.request_id, ex.error.code().name))
        for error in ex.failure.errors:
            print('\tError with message "%s".' % error.message)
            if error.location:
                for field_path_element in error.location.field_path_elements:
                    print('\t\tOn field: %s' % field_path_element.field_name)
        sys.exit(1)

Ruby

def add_ad_group_bid_modifier(customer_id, ad_group_id, bid_modifier_value)
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new

  # Creates an ad group bid modifier for mobile devices with the specified
  # ad group ID and bid modifier value.
  ad_group_bid_modifier = client.resource.ad_group_bid_modifier do |mod|
    # Sets the ad group.
    mod.ad_group = client.path.ad_group(customer_id, ad_group_id)

    # Sets the Bid Modifier.
    mod.bid_modifier = bid_modifier_value

    # Sets the Device.
    mod.device = client.resource.device_info do |device|
      device.type = :MOBILE
    end
  end

  # Create the operation.
  operation = client.operation.create_resource.ad_group_bid_modifier(ad_group_bid_modifier)

  # Add the ad group ad.
  response = client.service.ad_group_bid_modifier.mutate_ad_group_bid_modifiers(
      customer_id, [operation])

  puts "Added #{response.results.size} ad group bid modifiers:"
  response.results.each do |added_ad_group_bid_modifier|
    puts "\t#{added_ad_group_bid_modifier.resource_name}"
  end
end

Perl

sub add_ad_group_bid_modifier {
  my ($api_client, $customer_id, $ad_group_id, $bid_modifier_value) = @_;

  # Create an ad group bid modifier for mobile devices with the specified ad group ID and
  # bid modifier value.
  my $ad_group_bid_modifier =
    Google::Ads::GoogleAds::V3::Resources::AdGroupBidModifier->new({
      adGroup => Google::Ads::GoogleAds::V3::Utils::ResourceNames::ad_group(
        $customer_id, $ad_group_id
      ),
      bidModifier => $bid_modifier_value,
      device      => Google::Ads::GoogleAds::V3::Common::DeviceInfo->new({
          type => MOBILE
        })});

  # Create an ad group bid modifier operation.
  my $ad_group_bid_modifier_operation =
    Google::Ads::GoogleAds::V3::Services::AdGroupBidModifierService::AdGroupBidModifierOperation
    ->new({
      create => $ad_group_bid_modifier
    });

  # Add the ad group bid modifier.
  my $ad_group_bid_modifier_response =
    $api_client->AdGroupBidModifierService()->mutate({
      customerId => $customer_id,
      operations => [$ad_group_bid_modifier_operation]});

  printf "Created ad group bid modifier '%s'.\n",
    $ad_group_bid_modifier_response->{results}[0]{resourceName};

  return 1;
}

Retrieving bid adjustments

You can retrieve existing campaign-level bid adjustments by looking for all the campaign_bid_modifier values. At the ad group level, search for ad_group_bid_modifier. Here is a GAQL query that retrieves all bid modifiers of the account that are related to a given ad group:

SELECT
    campaign.id,
    ad_group.id,
    ad_group_bid_modifier.bid_modifier,
    ad_group_bid_modifier.criterion_id
FROM
    ad_group_bid_modifier
WHERE
    ad_group.id = ad_group_id