AdsApp.​RecommendationSelector

  • Fetches Google Ads recommendations, allowing for filtering and ordering.

  • Enables retrieval of recommendations by type, resource name, or other criteria using conditions.

  • Supports ordering results by specific recommendation attributes like type or resource name, in ascending or descending order.

  • Provides methods for limiting the number of recommendations returned and filtering by specific resource names.

  • Uses an iterator (RecommendationIterator) to access individual recommendations (Recommendation) after fetching.

 Fetches recommendations. Supports filtering and ordering.

Typical usage: 

var recommendationSelector = AdsApp
    .recommendations()
    .withCondition("recommendation.type = 'KEYWORD'")
    .orderBy("recommendation.resource_name DESC");

var recommendationIterator = recommendationSelector.get();
while (recommendationIterator.hasNext()) {
  var recommendation = recommendationIterator.next();
}
 Related:

Methods:

MemberTypeDescription
get() AdsApp.RecommendationIterator Fetches the requested recommendations and returns an iterator.
orderBy(orderBy) AdsApp.RecommendationSelector Specifies the ordering of the resulting entities.
withCondition(condition) AdsApp.RecommendationSelector Adds the specified condition to the selector in order to narrow down the results.
withLimit(limit) AdsApp.RecommendationSelector Specifies limit for the selector to use.
withResourceNames(resourceNames) AdsApp.RecommendationSelector Restricts this selector to return only recommendations with the given Google Ads API resource names.

get()

Fetches the requested recommendations and returns an iterator.

Return values:

TypeDescription
AdsApp.RecommendationIterator Iterator of the requested recommendations.

orderBy(orderBy)

Specifies the ordering of the resulting entities. orderBy parameter can have one of the following forms:
  • orderBy("recommendation.resource_name") - orders results by recommendation.resource_name, in ascending order.
  • orderBy("recommendation.type ASC") - orders results by recommendation.type, in ascending order.
  • orderBy("recommendation.type DESC") - orders results by recommendation.type, in descending order.

See RecommendationSelector.withCondition(String) for enumeration of columns that can be used.

orderBy() may be called multiple times. Consider the following example: 

selector = selector
    .orderBy("recommendation.type DESC")
    .orderBy("recommendation.resource_name ASC");

The results will be ordered by recommendation.type in descending order. Results with equal recommendation.type value will be ordered by recommendation.resource_name in ascending order.

Arguments:

NameTypeDescription
orderBy String Ordering to apply.

Return values:

TypeDescription
AdsApp.RecommendationSelector The selector with ordering applied.

withCondition(condition)

Adds the specified condition to the selector in order to narrow down the results.

Multiple conditions may be added to the same selector: 

selector = selector
    .withCondition("recommendation.type = 'KEYWORD'")
    .withCondition("recommendation.campaign like '%campaigns/123'");
 All specified conditions are AND-ed together. The above example will retrieve recommendations of type KEYWORD for the campaign with id 123.

The parameter to be passed into this method must be of the following form: 

"COLUMN_NAME OPERATOR VALUE"

Operators

The operator that can be used in a condition depends on the type of column.
  • For Integer and Long columns (e.g. metrics.clicks and metrics.impressions): 
    <  <=  >  >=  =  !=
  • For Double columns (e.g. metrics.ctr): 
    <  >
  • For String columns (e.g. campaign.name): 
    =  !=  (NOT) (LIKE | CONTAINS | REGEXP_MATCH)
  • For Enumeration columns (ones that can only take one value from a predefined list, such as Status): 
    =  !=  IN ()  NOT IN ()
  • For StringSet columns (e.g. campaign.labels): 
    CONTAINS ALL ()  CONTAINS ANY ()  CONTAINS NONE ()
Conditions using IN, NOT IN, CONTAINS ALL, CONTAINS ANY and CONTAINS NONE operators look as follows: 
withCondition("resource.column_name IN (Value1, Value2)")

Columns

To see the list of fields which may be filtered on, please refer to the Google Ads API reference documentation.

All column names are case-sensitive, and so are all values of enumerated columns (such as Status).

Arguments:

NameTypeDescription
condition String Condition to add to the selector.

Return values:

TypeDescription
AdsApp.RecommendationSelector The selector with the condition applied.

withLimit(limit)

Specifies limit for the selector to use. For instance, withLimit(50) returns only the first 50 entities.

Arguments:

NameTypeDescription
limit int How many entities to return.

Return values:

TypeDescription
AdsApp.RecommendationSelector The selector with limit applied.

withResourceNames(resourceNames)

Restricts this selector to return only recommendations with the given Google Ads API resource names. 
const recommendationResourceNames = [
  'customers/1234567890/recommendations/111',
  'customers/1234567890/recommendations/222',
  'customers/1234567890/recommendations/333',
];
selector = selector.withResourceNames(recommendationResourceNames);

The resulting selector can be further refined by applying additional conditions to it. The resource name condition will then be AND-ed together with all the other conditions.

The selector can only support up to 10,000 resource names. If more than 10,000 resource names are specified, the corresponding get() call will fail with a runtime error.

Arguments:

NameTypeDescription
resourceNames String[] Array of recommendation resource names.

Return values:

TypeDescription
AdsApp.RecommendationSelector The selector restricted to the given resource names.