Optimization score and recommendations

Video: Deep dive

Recommendations can improve your campaigns in a few ways:

  • Introduce new and relevant features
  • Get more out of your budget with improved bids, keywords, and ads
  • Increase the overall performance and efficiency of your campaigns

To increase optimization scores, you can use the RecommendationService to retrieve recommendations, and then apply or dismiss them accordingly. Starting in v15 of the Google Ads API, you can also subscribe to automatically apply recommendations by using the RecommendationSubscriptionService.

Optimization score

Video: Optimization score

Optimization score is an estimate of how well your Google Ads account is set to perform and is available at the Customer and Campaign levels.

The Customer.optimization_score_weight is only available for non-manager accounts and is used to compute the overall optimization score of multiple accounts. Retrieve the optimization score and optimization score weight of the accounts and multiply them together (Customer.optimization_score * Customer.optimization_score_weight) to compute the overall optimization score.

There are optimization-related metrics available for customer and campaign reports:

  1. The metrics.optimization_score_url provides a deep link into the account to view information on the related recommendations in the Google Ads UI.
  2. The metrics.optimization_score_uplift tells how much the optimization score would increase if all related recommendations are applied. It's an estimate based on all available recommendations as a whole, not just the sum of the uplift scores for each recommendation.

To group and order the returned recommendations, you can segment both of these metrics by recommendation type using segments.recommendation_type in your query.

Recommendation types

Fully-supported recommendation types

RecommendationType Description
CAMPAIGN_BUDGET Fix campaigns limited by budget
KEYWORD Add new keywords
TEXT_AD Add ad suggestions
TARGET_CPA_OPT_IN Bid with Target CPA
MAXIMIZE_CONVERSIONS_OPT_IN Bid with Maximize Conversions
MAXIMIZE_CONVERSION_VALUE_OPT_IN Bid with Maximize Conversion Value
ENHANCED_CPC_OPT_IN Bid with Enhanced CPC
MAXIMIZE_CLICKS_OPT_IN Bid with Maximize Clicks
OPTIMIZE_AD_ROTATION Use optimized ad rotations
MOVE_UNUSED_BUDGET Move unused to constrained budgets
TARGET_ROAS_OPT_IN Bid with Target ROAS
FORECASTING_CAMPAIGN_BUDGET Fix campaigns that are expected to become limited by budget in the future
RESPONSIVE_SEARCH_AD Add new responsive search ad
MARGINAL_ROI_CAMPAIGN_BUDGET Adjust campaign budget to increase ROI
USE_BROAD_MATCH_KEYWORD Use broad match for conversion-based campaigns with automated bidding
RESPONSIVE_SEARCH_AD_ASSET Add responsive search ad assets to an ad
RESPONSIVE_SEARCH_AD_IMPROVE_AD_STRENGTH Improve the strength of a responsive search ad
DISPLAY_EXPANSION_OPT_IN Update a campaign to use Display Expansion
SEARCH_PARTNERS_OPT_IN Expand reach with Google search partners
CUSTOM_AUDIENCE_OPT_IN Create a custom audience
IMPROVE_DISCOVERY_AD_STRENGTH Improve the strength of ads in Demand Gen campaigns
UPGRADE_SMART_SHOPPING_CAMPAIGN_TO_PERFORMANCE_MAX Upgrade a Smart Shopping campaign to a Performance Max campaign
UPGRADE_LOCAL_CAMPAIGN_TO_PERFORMANCE_MAX Upgrade a legacy local campaign to a Performance Max campaign
SHOPPING_MIGRATE_REGULAR_SHOPPING_CAMPAIGN_OFFERS_TO_PERFORMANCE_MAX Migrate offers targeted by Regular Shopping Campaigns to existing Performance Max campaigns
MIGRATE_DYNAMIC_SEARCH_ADS_CAMPAIGN_TO_PERFORMANCE_MAX Migrate Dynamic Search Ads to Performance Max campaigns
PERFORMANCE_MAX_OPT_IN Create Performance Max campaigns in your account
IMPROVE_PERFORMANCE_MAX_AD_STRENGTH Improve the asset group strength of a Performance Max campaign to an "Excellent" rating
PERFORMANCE_MAX_FINAL_URL_OPT_IN Turn on Final URL expansion for your Performance Max campaigns
RAISE_TARGET_CPA_BID_TOO_LOW Raise target CPA when it is too low and there are very few or no conversions
FORECASTING_SET_TARGET_ROAS Raise the budget in advance of a seasonal event that is forecasted to increase traffic, and change bidding strategy from maximize conversion value to target ROAS
LEAD_FORM Add lead form assets to a campaign
CALLOUT_ASSET Add callout assets to campaign or customer level
SITELINK_ASSET Add sitelink assets to campaign or customer level
CALL_ASSET Add call assets to campaign or customer level
SHOPPING_ADD_AGE_GROUP Add the age group attribute to offers that are demoted because of a missing age group
SHOPPING_ADD_COLOR Add a color to offers that are demoted because of a missing color
SHOPPING_ADD_GENDER Add a gender to offers that are demoted because of a missing gender
SHOPPING_ADD_GTIN Add a GTIN (Global Trade Item Number) to offers that are demoted because of a missing GTIN
SHOPPING_ADD_MORE_IDENTIFIERS Add more identifiers to offers that are demoted because of missing identifiers
SHOPPING_ADD_SIZE Add the size to offers that are demoted because of a missing size
SHOPPING_ADD_PRODUCTS_TO_CAMPAIGN Add products for a campaign to serve
SHOPPING_FIX_DISAPPROVED_PRODUCTS Fix disapproved products
SHOPPING_TARGET_ALL_OFFERS Create a catch-all campaign that targets all offers
SHOPPING_FIX_SUSPENDED_MERCHANT_CENTER_ACCOUNT Fix Merchant Center account suspension issues
SHOPPING_FIX_MERCHANT_CENTER_ACCOUNT_SUSPENSION_WARNING Fix Merchant Center account suspension warning issues
DYNAMIC_IMAGE_EXTENSION_OPT_IN Enable dynamic image extensions on the account
RAISE_TARGET_CPA Raise Target CPA
LOWER_TARGET_ROAS Lower Target ROAS
FORECASTING_SET_TARGET_CPA Set a target CPA for campaigns that don't have one specified, in advance of a seasonal event that is forecasted to increase traffic
SET_TARGET_CPA Set a target CPA for campaigns that don't have one specified
SET_TARGET_ROAS Set a target ROAS for campaigns that don't have one specified
REFRESH_CUSTOMER_MATCH_LIST Update a customer list that hasn't been updated in the last 90 days
IMPROVE_GOOGLE_TAG_COVERAGE Deploy the Google Tag on more pages
CALLOUT_EXTENSION (deprecated) Deprecated, use CALLOUT_ASSET instead
SITELINK_EXTENSION (deprecated) Deprecated, use SITELINK_ASSET instead
CALL_EXTENSION (deprecated) Deprecated, use CALL_ASSET instead
KEYWORD_MATCH_TYPE (deprecated) Deprecated, use USE_BROAD_MATCH_KEYWORD instead

Watch this video to learn more

Handle unsupported types

Retrieve recommendations

Video: Live coding

Like most other entities in the Google Ads API, Recommendation objects are fetched by using the GoogleAdsService.SearchStream with a Google Ads Query Language query.

For each type of recommendation, details are provided in a recommendation-specific field. For example, CAMPAIGN_BUDGET recommendation details are in the campaign_budget_recommendation field, and are wrapped in a CampaignBudgetRecommendation object.

Find all recommendation-specific fields in the recommendation union field.

Recommendation impact

Some recommendation types populate the impact field of the recommendation. RecommendationImpact contains an estimate of the impact on account performance as a result of applying the recommendation. The following recommendation metrics are available in the impact.base_metrics and impact.potential_metrics fields:

  • impressions

  • clicks

  • cost_micros

  • conversions

  • all_conversions (available starting in v16 of the Google Ads API)

  • video_views

Code example

The following sample code retrieves all available and dismissed recommendations of type TEXT_AD from an account and prints some of their details:

Java

private void runExample(GoogleAdsClient googleAdsClient, long customerId) {
  try (GoogleAdsServiceClient googleAdsServiceClient =
      googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
    String query =
        "SELECT recommendation.type, "
            + "recommendation.campaign, "
            + "recommendation.text_ad_recommendation "
            + "FROM recommendation "
            + "WHERE recommendation.type = TEXT_AD";

    // Creates a request that will retrieve all recommendations using pages of the
    // specified page size.
    SearchGoogleAdsRequest request =
        SearchGoogleAdsRequest.newBuilder()
            .setCustomerId(Long.toString(customerId))
            .setPageSize(PAGE_SIZE)
            .setQuery(query)
            .build();
    // Issues the search request.
    SearchPagedResponse searchPagedResponse = googleAdsServiceClient.search(request);

    // Iterates over all rows in all pages and prints the requested field values for the
    // recommendation in each row.
    for (GoogleAdsRow googleAdsRow : searchPagedResponse.iterateAll()) {
      Recommendation recommendation = googleAdsRow.getRecommendation();
      Ad recommendedAd = recommendation.getTextAdRecommendation().getAd();

      System.out.printf(
          "Recommendation ('%s') was found for campaign '%s':%n",
          recommendation.getResourceName(), recommendation.getCampaign());
      if (recommendedAd.hasExpandedTextAd()) {
        ExpandedTextAdInfo eta = recommendedAd.getExpandedTextAd();
        System.out.printf(
            "\tHeadline 1 = '%s'%n" + "\tHeadline 2 = '%s'%n" + "\tDescription = '%s'%n",
            eta.getHeadlinePart1(), eta.getHeadlinePart2(), eta.getDescription());
      }
      if (recommendedAd.getDisplayUrl() != null) {
        System.out.printf("\tDisplay URL = '%s'%n", recommendedAd.getDisplayUrl());
      }
      for (String url : recommendedAd.getFinalUrlsList()) {
        System.out.printf("\tFinal URL = '%s'%n", url);
      }
      for (String url : recommendedAd.getFinalMobileUrlsList()) {
        System.out.printf("\tFinal Mobile URL = '%s'%n", url);
      }
    }
  }
}
      

C#

public void Run(GoogleAdsClient client, long customerId)
{
    // Get the GoogleAdsServiceClient .
    GoogleAdsServiceClient service = client.GetService(Services.V15.GoogleAdsService);

    string query =
        @"SELECT
        recommendation.type,
        recommendation.campaign,
        recommendation.text_ad_recommendation
    FROM
        recommendation
    WHERE
        recommendation.type = TEXT_AD";

    // Create a request that will retrieve all recommendations using pages of the
    // specified page size.
    SearchGoogleAdsRequest request = new SearchGoogleAdsRequest()
    {
        CustomerId = customerId.ToString(),
        PageSize = PAGE_SIZE,
        Query = query
    };

    try
    {
        // Issue the search request.
        PagedEnumerable<SearchGoogleAdsResponse, GoogleAdsRow> searchPagedResponse =
            service.Search(customerId.ToString(), query);

        // Iterates over all rows in all pages and prints the requested field values
        // for the recommendation in each row.
        foreach (GoogleAdsRow googleAdsRow in searchPagedResponse)
        {
            Recommendation recommendation = googleAdsRow.Recommendation;
            // ...
        }
    }
    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)
{
    $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
    // Creates a query that retrieves recommendations for text ads.
    $query = 'SELECT recommendation.type, recommendation.campaign, '
        . 'recommendation.text_ad_recommendation '
        . 'FROM recommendation '
        . 'WHERE recommendation.type = TEXT_AD';

    // Issues a search request by specifying page size.
    $response = $googleAdsServiceClient->search(
        SearchGoogleAdsRequest::build($customerId, $query)->setPageSize(self::PAGE_SIZE)
    );

    // Iterates over all rows in all pages and prints the requested field values for
    // the recommendation in each row.
    foreach ($response->iterateAllElements() as $googleAdsRow) {
        /** @var GoogleAdsRow $googleAdsRow */
        $recommendation = $googleAdsRow->getRecommendation();
        printf(
            "Recommendation with resource name '%s' was found for campaign "
            . "with resource name '%s':%s",
            $recommendation->getResourceName(),
            $recommendation->getCampaign(),
            PHP_EOL
        );
        $recommendedAd = $recommendation->getTextAdRecommendation()->getAd();
        if (!is_null($recommendedAd->getExpandedTextAd())) {
            $recommendedExpandedTextAd = $recommendedAd->getExpandedTextAd();
            printf(
                "\tHeadline part 1 is '%s'.%s",
                $recommendedExpandedTextAd->getHeadlinePart1(),
                PHP_EOL
            );
            printf(
                "\tHeadline part 2 is '%s'.%s",
                $recommendedExpandedTextAd->getHeadlinePart2(),
                PHP_EOL
            );
            printf(
                "\tDescription is '%s'%s",
                $recommendedExpandedTextAd->getDescription(),
                PHP_EOL
            );
        }
        if (!is_null($recommendedAd->getDisplayUrl())) {
            printf("\tDisplay URL is '%s'.%s", $recommendedAd->getDisplayUrl(), PHP_EOL);
        }
        foreach ($recommendedAd->getFinalUrls() as $finalUrl) {
            /** @var string $finalUrl */
            printf("\tFinal URL is '%s'.%s", $finalUrl, PHP_EOL);
        }
        foreach ($recommendedAd->getFinalMobileUrls() as $finalMobileUrl) {
            /** @var string $finalMobileUrl */
            printf("\tFinal Mobile URL is '%s'.%s", $finalMobileUrl, PHP_EOL);
        }
    }
}
      

Python

def main(client, customer_id):
    ga_service = client.get_service("GoogleAdsService")

    query = """
        SELECT
          recommendation.type,
          recommendation.campaign,
          recommendation.text_ad_recommendation
        FROM recommendation
        WHERE recommendation.type = TEXT_AD"""

    search_request = client.get_type("SearchGoogleAdsStreamRequest")
    search_request.customer_id = customer_id
    search_request.query = query
    stream = ga_service.search_stream(request=search_request)

    for batch in stream:
        for row in batch.results:
            recommendation = row.recommendation
            recommended_ad = recommendation.text_ad_recommendation.ad
            print(
                f'Recommendation ("{recommendation.resource_name}") '
                f'was found for campaign "{recommendation.campaign}".'
            )

            if recommended_ad.display_url:
                print(f'\tDisplay URL = "{recommended_ad.display_url}"')

            for url in recommended_ad.final_urls:
                print(f'\tFinal URL = "{url}"')

            for url in recommended_ad.final_mobile_urls:
                print(f'\tFinal Mobile URL = "{url}"')
      

Ruby

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

  ga_service = client.service.google_ads

  query = <<~QUERY
    SELECT recommendation.type, recommendation.campaign,
        recommendation.text_ad_recommendation
    FROM recommendation
    WHERE recommendation.type = TEXT_AD
  QUERY

  response = ga_service.search(
    customer_id: customer_id,
    query: query,
    page_size: PAGE_SIZE,
  )

  response.each do |row|
    recommendation = row.recommendation
    recommended_ad = recommendation.text_ad_recommendation.ad

    puts "Recommendation ('#{recommendation.resource_name}') was found for "\
        "campaign '#{recommendation.campaign}'."
    if recommended_ad.expanded_text_ad
      eta = recommended_ad.expanded_text_ad
      puts "\tHeadline 1 = '#{eta.headline_part1}'\n\tHeadline2 = '#{eta.headline_part2}'\n" +
          "\tDescription = '#{eta.description}'"
    end
    if recommended_ad.display_url
      puts "\tDisplay URL = '#{recommended_ad.display_url}'"
    end
    recommended_ad.final_urls.each do |url|
      puts "\tFinal Url = '#{url}'"
    end
    recommended_ad.final_mobile_urls.each do |url|
      puts "\tFinal Mobile Url = '#{url}'"
    end
  end
end
      

Perl

sub get_text_ad_recommendations {
  my ($api_client, $customer_id) = @_;

  # Creates the search query.
  my $search_query =
    "SELECT recommendation.type, recommendation.campaign, " .
    "recommendation.text_ad_recommendation " .
    "FROM recommendation WHERE recommendation.type = TEXT_AD";

  # Create a search Google Ads request that will retrieve all recommendations for
  # text ads using pages of the specified page size.
  my $search_request =
    Google::Ads::GoogleAds::V15::Services::GoogleAdsService::SearchGoogleAdsRequest
    ->new({
      customerId => $customer_id,
      query      => $search_query,
      pageSize   => PAGE_SIZE
    });

  # Get the GoogleAdsService.
  my $google_ads_service = $api_client->GoogleAdsService();

  my $iterator = Google::Ads::GoogleAds::Utils::SearchGoogleAdsIterator->new({
    service => $google_ads_service,
    request => $search_request
  });

  # Iterate over all rows in all pages and print the requested field values for
  # the recommendation in each row.
  while ($iterator->has_next) {
    my $google_ads_row = $iterator->next;
    my $recommendation = $google_ads_row->{recommendation};
    printf
      "Recommendation '%s' was found for campaign '%s':\n",
      $recommendation->{resourceName},
      $recommendation->{campaign};

    my $recommended_ad = $recommendation->{textAdRecommendation}{ad};
    if ($recommended_ad->{expandedTextAd}) {
      my $recommended_expanded_text_ad = $recommended_ad->{expandedTextAd};

      printf "\tHeadline part 1 is '%s'.\n" .
        "\tHeadline part 2 is '%s'.\n" . "\tDescription is '%s'.\n",
        $recommended_expanded_text_ad->{headlinePart1},
        $recommended_expanded_text_ad->{headlinePart2},
        $recommended_expanded_text_ad->{description};
    }

    if ($recommended_ad->{displayUrl}) {
      printf "\tDisplay URL is '%s'.\n", $recommended_ad->{displayUrl};
    }

    foreach my $final_url (@{$recommended_ad->{finalUrls}}) {
      printf "\tFinal URL is '%s'.\n", $final_url;
    }

    foreach my $final_mobile_url (@{$recommended_ad->{finalMobileUrls}}) {
      printf "\tFinal Mobile URL is '%s'.\n", $final_mobile_url;
    }
  }

  return 1;
}
      

Take action

Any retrieved recommendation can be applied or dismissed.

Depending on the recommendation type, recommendations can change on a daily basis or even multiple times a day. When that happens, a recommendation object's resource_name can become obsolete after the recommendation is retrieved.

It is good practice to take action on recommendations shortly after retrieval.

Apply recommendations

Video: Apply recommendations

You can apply active or dismissed recommendations with the ApplyRecommendation method of the RecommendationService.

Recommendation types can have mandatory or optional parameters. Most recommendations come with recommended values that are used by default.

Setting accounts for auto-applying recommendations is not supported for all recommendation types. However, you can implement similar behavior for the recommendation types that are fully supported by the Google Ads API. Refer to the DetectAndApplyRecommendations code example to learn more.

Use the apply_parameters union field of ApplyRecommendationOperation to apply recommendations with specific parameter values. Each suitable recommendation type has its own field. Any recommendation type not listed in the apply_parameters field does not use these parameter values.

Code example

The following code example illustrates how to apply a recommendation with the recommended apply parameters:

Java

private void runExample(
    GoogleAdsClient googleAdsClient, long customerId, String recommendationId) {
  String recommendationResourceName = ResourceNames.recommendation(customerId, recommendationId);

  ApplyRecommendationOperation.Builder operationBuilder =
      ApplyRecommendationOperation.newBuilder().setResourceName(recommendationResourceName);
  // Each recommendation types has optional parameters to override the recommended values.
  // This is an example to override a recommended ad when a TextAdRecommendation is applied.
  // Please read
  // https://developers.google.com/google-ads/api/reference/rpc/latest/ApplyRecommendationOperation
  // for details.
  // Note that additional import statements are needed for this example to work. And also, please
  // replace INSERT_AD_ID_HERE with a valid ad ID below.
  //
  // Ad overrideAd = Ad.newBuilder().setId(Long.parseLong("INSERT_AD_ID_HERE")).build();
  // operationBuilder.setTextAd(TextAdParameters.newBuilder().
  //     setAd(overrideAd).build()).build();
  List<ApplyRecommendationOperation> operations = new ArrayList<>();
  operations.add(operationBuilder.build());

  try (RecommendationServiceClient recommendationServiceClient =
      googleAdsClient.getLatestVersion().createRecommendationServiceClient()) {
    ApplyRecommendationResponse response =
        recommendationServiceClient.applyRecommendation(Long.toString(customerId), operations);
    System.out.printf("Applied %d recommendation:%n", response.getResultsCount());
    for (ApplyRecommendationResult result : response.getResultsList()) {
      System.out.println(result.getResourceName());
    }
  }
}
      

C#

public void Run(GoogleAdsClient client, long customerId, long recommendationId)
{
    // Get the RecommendationServiceClient.
    RecommendationServiceClient service = client.GetService(
        Services.V15.RecommendationService);

    ApplyRecommendationOperation operation = new ApplyRecommendationOperation()
    {
        ResourceName = ResourceNames.Recommendation(customerId, recommendationId),

        // Each recommendation types has optional parameters to override the recommended
        // values. For example, you can override a recommended ad when a
        // TextAdRecommendation is applied, as shown below.
        // Please read https://developers.google.com/google-ads/api/reference/rpc/latest/ApplyRecommendationOperation
        // for details.
        // TextAd = new TextAdParameters() {
        //   Ad = new Ad() {
        //     Id = long.Parse("INSERT_AD_ID_HERE")
        //   }
        // }
    };

    try
    {
        ApplyRecommendationResponse response = service.ApplyRecommendation(
            customerId.ToString(), new ApplyRecommendationOperation[] {
                operation
            });
        Console.WriteLine($"Applied {0} recommendation(s):", response.Results.Count);
        foreach (ApplyRecommendationResult result in response.Results)
        {
            Console.WriteLine($"- {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,
    string $recommendationId
) {
    $recommendationResourceName =
        ResourceNames::forRecommendation($customerId, $recommendationId);

    $applyRecommendationOperation = new ApplyRecommendationOperation();
    $applyRecommendationOperation->setResourceName($recommendationResourceName);

    // Each recommendation type has optional parameters to override the recommended values.
    // This is an example to override a recommended ad when a TextAdRecommendation is applied.
    // For details, please read
    // https://developers.google.com/google-ads/api/reference/rpc/latest/ApplyRecommendationOperation.
    /*
    $overridingAd = new Ad([
        'id' => 'INSERT_AD_ID_AS_INTEGER_HERE'
    ]);
    $applyRecommendationOperation->setTextAd(new TextAdParameters(['ad' => $overridingAd]));
    */
    // Issues a mutate request to apply the recommendation.
    $recommendationServiceClient = $googleAdsClient->getRecommendationServiceClient();
    $response = $recommendationServiceClient->applyRecommendation(
        ApplyRecommendationRequest::build($customerId, [$applyRecommendationOperation])
    );
    /** @var Recommendation $appliedRecommendation */
    $appliedRecommendation = $response->getResults()[0];

    printf(
        "Applied recommendation with resource name: '%s'.%s",
        $appliedRecommendation->getResourceName(),
        PHP_EOL
    );
}
      

Python

def main(client, customer_id, recommendation_id):
    recommendation_service = client.get_service("RecommendationService")

    apply_recommendation_operation = client.get_type(
        "ApplyRecommendationOperation"
    )

    apply_recommendation_operation.resource_name = (
        recommendation_service.recommendation_path(
            customer_id, recommendation_id
        )
    )

    # This is where we override the recommended ad when a TextAdRecommendation is applied.
    # override_ad = client.get_type("Ad")
    # override_ad.resource_name = "INSERT_AD_ID_HERE"
    # apply_recommendation_operation.text_ad.ad = override_ad

    recommendation_response = recommendation_service.apply_recommendation(
        customer_id=customer_id, operations=[apply_recommendation_operation]
    )

    print(
        "Applied recommendation with resource name: "
        f"'{recommendation_response.results[0].resource_name}'"
    )
      

Ruby

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

  recommendation_resource =
      client.path.recommendation(customer_id, recommendation_id)
  apply_recommendation_operation = client.operation.apply_recommendation
  apply_recommendation_operation.resource_name = recommendation_resource

  # Each recommendation type has optional parameters to override the recommended
  # values. This is an example to override a recommended ad when a
  # TextAdRecommendation is applied.
  # For details, please read
  # https://developers.google.com/google-ads/api/reference/rpc/google.ads.google_ads.v1.services#google.ads.google_ads.v1.services.ApplyRecommendationOperation
  #
  # text_ad_parameters = client.resource.text_ad_parameters do |tap|
  #   tap.ad = client.resource.ad do |ad|
  #     ad.id = "INSERT_AD_ID_AS_INTEGER_HERE"
  #   end
  # end
  # apply_recommendation_operation.text_ad = text_ad_parameters

  # Issues a mutate request to apply the recommendation.
  recommendation_service = client.service.recommendation
  response = recommendation_service.apply_recommendation(
    customer_id: customer_id,
    operations: [apply_recommendation_operation],
  )
  applied_recommendation = response.results.first

  puts "Applied recommendation with resource name: '#{applied_recommendation.resource_name}'."
end
      

Perl

sub apply_recommendation {
  my ($api_client, $customer_id, $recommendation_id) = @_;

  my $recommendation_resource_name =
    Google::Ads::GoogleAds::V15::Utils::ResourceNames::recommendation(
    $customer_id, $recommendation_id);

  # Create an apply recommendation operation.
  my $apply_recommendation_operation =
    Google::Ads::GoogleAds::V15::Services::RecommendationService::ApplyRecommendationOperation
    ->new({
      resourceName => $recommendation_resource_name
    });

  # Each recommendation type has optional parameters to override the recommended values.
  # This is an example to override a recommended ad when a TextAdRecommendation is applied.
  # For details, please read
  # https://developers.google.com/google-ads/api/reference/rpc/latest/ApplyRecommendationOperation.
  #
  # my $overriding_ad = Google::Ads::GoogleAds::V15::Resources::Ad->new({
  #   id => "INSERT_AD_ID_AS_INTEGER_HERE"
  # });
  # my $text_ad_parameters =
  #   Google::Ads::GoogleAds::V15::Services::RecommendationService::TextAdParameters
  #   ->new({ad => $overriding_ad});
  # $apply_recommendation_operation->{textAd} = $text_ad_parameters;

  # Apply the recommendation.
  my $apply_recommendation_response =
    $api_client->RecommendationService()->apply({
      customerId => $customer_id,
      operations => [$apply_recommendation_operation]});

  printf "Applied recommendation with resource name: '%s'.\n",
    $apply_recommendation_response->{results}[0]{resourceName};

  return 1;
}
      

Watch these videos to learn more

Apply parameters

Bulk

Errors

Tests

Dismiss recommendations

Video: Dismiss recommendations

You can dismiss recommendations with the RecommendationService. The code structure is similar to applying recommendations, but instead you use DismissRecommendationOperation and RecommendationService.DismissRecommendation.

Watch these videos to learn more

Bulk

Errors

Tests

Automatically apply recommendations

Starting with v15 of the Google Ads API, you can use the RecommendationSubscriptionService to automatically apply recommendations of a specific type.

To subscribe to a particular recommendation type, create a RecommendationSubscription object, set the type field to one of the supported recommendation types, and set the status field to ENABLED.

Subscription-supported recommendation types

  • ENHANCED_CPC_OPT_IN
  • KEYWORD
  • KEYWORD_MATCH_TYPE
  • LOWER_TARGET_ROAS
  • MAXIMIZE_CLICKS_OPT_IN
  • OPTIMIZE_AD_ROTATION
  • RAISE_TARGET_CPA
  • RESPONSIVE_SEARCH_AD
  • RESPONSIVE_SEARCH_AD_IMPROVE_AD_STRENGTH
  • SEARCH_PARTNERS_OPT_IN
  • SEARCH_PLUS_OPT_IN
  • SET_TARGET_CPA
  • SET_TARGET_ROAS
  • TARGET_CPA_OPT_IN
  • TARGET_ROAS_OPT_IN
  • USE_BROAD_MATCH_KEYWORD

Retrieve subscriptions

To get information about an account's recommendation subscriptions, query the recommendation_subscription resource.

To view changes that were automatically applied, query the change_event resource, filtering the change_client_type to GOOGLE_ADS_RECOMMENDATIONS_SUBSCRIPTION.

Recommendations in campaign construction

Starting with v16 of the Google Ads API, you can use RecommendationService.GenerateRecommendationsRequest to generate recommendations during campaign construction, for a given set of recommendation types.

GenerateRecommendations accepts as input a customer ID, an advertising channel type which must be either SEARCH or PERFORMANCE_MAX, a list of recommendation types to generate, and various data points dependent on the specified types. It outputs a list of Recommendation objects based on the data you provide. If there isn't sufficient data to generate a recommendation for the requested recommendation_types, or if the campaign is already in the recommended state, the result set won't contain a recommendation for that type. Make sure your application handles the case where no recommendations are returned for the requested recommendation types.

The following table describes the recommendation types that GenerateRecommendations supports, and the fields you must provide to receive recommendations for that type. As a best practice, send the GenerateRecommendations request after all information has been collected related to the requested recommendation types. For additional details on required and optional fields, including nested fields, consult the reference documentation.

RecommendationType Required fields Optional fields
KEYWORD
  • seed_info
  • ad_group_info
MAXIMIZE_CLICKS_OPT_IN
  • conversion_tracking_status
  • bidding_info
MAXIMIZE_CONVERSIONS_OPT_IN
  • conversion_tracking_status
  • bidding_info
MAXIMIZE_CONVERSION_VALUE_OPT_IN
  • conversion_tracking_status
  • bidding_info
SET_TARGET_CPA
  • conversion_tracking_status
  • bidding_info
SET_TARGET_ROAS
  • conversion_tracking_status
  • bidding_info
SITELINK_ASSET
Note: The returned SitelinkAssetRecommendation object will contain empty lists. If the GenerateRecommendations response contains a SitelinkAssetRecommendation, it can be treated as a signal to add at least one sitelink asset to the campaign.
  • campaign_sitelink_count
TARGET_CPA_OPT_IN
  • conversion_tracking_status
  • bidding_info
TARGET_ROAS_OPT_IN
  • conversion_tracking_status
  • bidding_info

Example usage flow

Suppose your company is an advertising agency which provides a campaign construction workflow to users, and you want to offer suggestions to users during that flow. You can use GenerateRecommendationsRequest to generate recommendations on-demand, and incorporate those recommendations into your campaign construction user interface.

The usage flow might look like the following:

  1. A user comes to your application to create a Performance Max campaign.

  2. The user provides some initial information as part of the campaign construction flow. For example, they provide details to build a single SitelinkAsset, and they select TARGET_SPEND as their Smart Bidding strategy.

  3. You send a GenerateRecommendationsRequest which sets the following fields:

    • campaign_sitelink_count: set to 1, which is the number of sitelink assets on the work-in-progress campaign.

    • bidding_info: set the nested bidding_strategy_type field to TARGET_SPEND.

    • conversion_tracking_status: set to the ConversionTrackingStatus of this customer. For guidance on how to retrieve this field, visit the Getting started guide for conversion management.

    • recommendation_types: set to [SITELINK_ASSET, MAXIMIZE_CLICKS_OPT_IN].

    • advertising_channel_type: set to PERFORMANCE_MAX.

    • customer_id: set to the ID of the customer creating the campaign.

  4. You can take the recommendations in the GenerateRecommendationsResponse — in this case, a SitelinkAssetRecommendation and a MaximizeClicksOptInRecommendation —and suggest them to the user by displaying them within your campaign construction interface. If the user accepts a suggestion, you can then incorporate it into the campaign creation request once the user completes the campaign construction flow.