Share your feedback about the Google Ads API! Take our annual survey.

Recommendation Service

Recommendations help you improve your campaigns by introducing new and relevant features, getting more out of your budget by improving bids, keywords and ads, and increasing the overall performance and efficiency of your campaigns.

Recommendation types

The Google Ads API currently supports the following recommendation types:

Recommendation Type Value
Fixing campaigns limited by budget CAMPAIGN_BUDGET
Bidding with Enhanced CPC ENHANCED_CPC_OPT_IN
Adding new keywords KEYWORD
Bidding with Maximize Clicks MAXIMIZE_CLICKS_OPT_IN
Bidding with Maximize Conversions MAXIMIZE_CONVERSIONS_OPT_IN
Use optimized ad rotation OPTIMIZE_AD_ROTATION
Expand reach with Google search partners SEARCH_PARTNERS_OPT_IN
Adding ad suggestions TEXT_AD
Bidding with Target CPA TARGET_CPA_OPT_IN

Getting recommendations

The following sample code retrieves all available and dismissed recommendations from an account using GoogleAdsService.Search:

Java

private void runExample(GoogleAdsClient googleAdsClient, long customerId) {
  try (GoogleAdsServiceClient googleAdsServiceClient =
      googleAdsClient.getGoogleAdsServiceClient()) {
    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().getValue());
      if (recommendedAd.hasExpandedTextAd()) {
        ExpandedTextAdInfo eta = recommendedAd.getExpandedTextAd();
        System.out.printf(
            "\tHeadline 1 = '%s'%n" + "\tHeadline 2 = '%s'%n" + "\tDescription = '%s'%n",
            eta.getHeadlinePart1().getValue(),
            eta.getHeadlinePart2().getValue(),
            eta.getDescription().getValue());
      }
      if (recommendedAd.getDisplayUrl() != null) {
        System.out.printf("\tDisplay URL = '%s'%n", recommendedAd.getDisplayUrl().getValue());
      }
      for (StringValue url : recommendedAd.getFinalUrlsList()) {
        System.out.printf("\tFinal URL = '%s'%n", url.getValue());
      }
      for (StringValue url : recommendedAd.getFinalMobileUrlsList()) {
        System.out.printf("\tFinal Mobile URL = '%s'%n", url.getValue());
      }
    }
  }
}

C#

public void Run(GoogleAdsClient client, long customerId)

PHP

public static function main()

Python

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

    query = ('SELECT recommendation.type, recommendation.campaign, '
             'recommendation.text_ad_recommendation FROM recommendation '
             'WHERE recommendation.type = TEXT_AD')

    results = ga_service.search(customer_id, query=query, page_size=page_size)

    try:
        for row in results:
            recommendation = row.recommendation
            recommended_ad = recommendation.text_ad_recommendation.ad
            print('Recommendation ("%s") was found for campaign "%s".'
                  % (recommendation.resource_name, recommendation.campaign))

            if recommended_ad.display_url:
                print('\tDisplay URL = "%s"' % recommended_ad.display_url)

            for url in recommended_ad.final_urls:
                print('\tFinal URL = "%s"' % url)

            for url in recommended_ad.final_mobile_urls:
                print('\tFinal Mobile URL = "%s"' % url)
    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 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(:GoogleAds)

  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, query, page_size: PAGE_SIZE)

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

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

Applying a recommendation

You can apply active or dismissed recommendations to your account via the RecommendationService. To override recommended values, use ApplyRecommendationOperation with the additional parameters.

Java

private void runExample(
    GoogleAdsClient googleAdsClient, long customerId, String recommendationId) {
  String recommendationResourceName =
      RecommendationName.format(Long.toString(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/google.ads.googleads.v0.services#google.ads.googleads.v0.services.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(Int64Value.of(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.getRecommendationServiceClient()) {
    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)

PHP

public static function main()

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))

    try:
        recommendation_response = recommendation_service.apply_recommendation(
            customer_id, [apply_recommendation_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)

    print('Applied recommendation with resource name: "%s".'
          % 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(:ApplyRecommendation)
  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.v0.services#google.ads.google_ads.v0.services.ApplyRecommendationOperation
  #
  # overriding_ad = client.resource(:Ad)
  # overriding_ad.id = client.wrapper.int64('INSERT_AD_ID_AS_INTEGER_HERE')
  # text_ad_parameters = client.resource(:TextAdParameters)
  # text_ad_parameters.ad = overriding_ad
  # 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,
      [apply_recommendation_operation])
  applied_recommendation = response.results.first

  puts sprintf('Applied recommendation with resource name: "%s".',
      applied_recommendation.resource_name)
end

Send feedback about...

Google Ads API Beta
Google Ads API Beta
Need help? Visit our support page.