Edit

AdGroupSelector

  • Article

Contains the methods for filtering and sorting a list of ad groups. For information about selectors, see Selectors.

Example usage:

    var iterator = AdsApp.adGroups()
        .withCondition("ClickConversionRate > 0.3")
        .forDateRange("LAST_WEEK")
        .orderBy("Clicks DESC")
        .get();

    while (iterator.hasNext()) {
        var adGroup = iterator.next();
        var metrics = adGroup.getStats();
    }

Methods

Method Name Return Type Description
forDateRange(Object dateFrom, Object dateTo) AdGroupSelector Applies the start and end dates for selecting performance metrics.
forDateRange(string dateRange) AdGroupSelector Applies the predefined date range for selecting performance metrics.
get AdGroupIterator Gets an iterator used to iterate through the list of ad groups.
orderBy(string orderBy) AdGroupSelector Applies the specified ordering to the selected ad groups.
withCondition(string condition) AdGroupSelector Applies filter criteria to the ad groups.
withIds(string[] ids) AdGroupSelector Gets ad groups with the specified IDs.
withLimit(int limit) AdGroupSelector Gets the top n ad groups that match the selection criteria.

forDateRange(Object dateFrom, Object dateTo)

Applies the start and end dates for selecting performance metrics.

Specify a date range only if:

  • You apply conditions or ordering that reference performance metric fields.
  • You want to get performance data for the objects you're selecting. For example, if you plan to call the getStats() method.

You may specify the date parameters using strings or objects. To use strings, specify the date in the form, YYYYMMDD. If you use objects, create an object with the following fields:

  • year
  • month
  • day

For example:

var date = {year: 2018, month: 5, day: 13};

The month is one-based where 1 is January and 12 is December.

The date range is inclusive. If you specify multiple date ranges, only the last date range is used.

Arguments

Name Type Description
dateFrom Object The start date of the date range that specifies the performance data to include in the selector.
dateTo Object The end date of the date range that specifies the performance data to include in the selector.

Returns

Type Description
AdGroupSelector Selector with date range applied.

forDateRange(String dateRange)

Applies the predefined date range for selecting performance metrics.

Specify a date range only if:

  • You apply conditions or ordering that reference performance metric fields.
  • You want to get performance data for the objects you're selecting. For example, if you plan to call the getStats() method.

If you specify multiple date ranges, only the last date range is used.

Supported date range values:

  • TODAY
  • YESTERDAY
  • LAST_WEEK
  • LAST_BUSINESS_WEEK
  • LAST_7_DAYS
  • THIS_WEEK_SUN_TODAY
  • LAST_14_DAYS
  • LAST_30_DAYS
  • LAST_WEEK_SUN_SAT
  • THIS_MONTH
  • LAST_MONTH
  • ALL_TIME

Arguments

Name Type Description
dateRange String The predefined date range string that specifies the performance data to include in the selector. The predefined date-range string is case sensitive.

Returns

Type Description
AdGroupSelector Selector with date range applied.

get

Gets an iterator used to iterate through the list of ad groups.

Returns

Type Description
AdGroupIterator An iterator used to iterate through the selected ad groups.

orderBy(String orderBy)

Applies the specified ordering to the selected ad groups.

Specify the orderBy parameter in the form, "columnName orderDirection" where:

  • columnName is one of the supported columns.
  • orderDirection is the order to sort the results in. Set to ASC to order the results in ascending order or DESC to order the results in descending order. The default is ASC.

For example, the following call returns ad groups in ascending order by AverageCpc.

selector = selector.orderBy("AverageCpc");

Selectors support ordering entities by one field only. You may not order the list of entities by field x, and within x by field y, and so on. If you specify more than one orderBy() call in a chain or in separate selector calls, Scripts orders the list of entities using the field specified in the last orderBy() call. 

Arguments

Name Type Description
orderBy string The ordering to apply.

Returns

Type Description
AdGroupSelector Selector with ordering applied.

withCondition(String condition)

Applies filter criteria to the ad groups.

Specify the condition parameter in the form, "columnName operator value" where:

Operators

The operator that you use depends on the column's type. Operators are case-sensitive. For example, use STARTS_WITH instead of starts_with.

Operators for columns that contain integers and long values:

<
<=
>
>=
=
!=

Operators for columns that contain double values:

<
>

Operators for columns that contain string values:

=
!=
STARTS_WITH
STARTS_WITH_IGNORE_CASE
CONTAINS
CONTAINS_IGNORE_CASE
DOES_NOT_CONTAIN
DOES_NOT_CONTAIN_IGNORE_CASE

Operators for columns that contain enumeration values:

=
!=
IN []
NOT_IN []

Operators for columns that contain an array of strings:

CONTAINS_ALL
CONTAINS_ANY
CONTAINS_NONE

Supported Columns

Supported columns for ad group filtering. The names are case sensitive.

The following are the performance metrics columns you may specify.

Column Type Example
AbsoluteTopImpressionRate double withCondition("AbsoluteTopImpressionRate > 0.25")
AverageCpc double withCondition("AverageCpc < 2.75")
AverageCpm double withCondition("AverageCpm > 0.65")
ClickConversionRate double withCondition("ClickConversionRate > 0.25")
Clicks long withCondition("Clicks >= 33")
ConvertedClicks long withCondition("ConvertedClicks >= 10")
Cost double withCondition("Cost > 3.25")

The cost is in the account's currency.
Ctr double withCondition("Ctr > 0.05")

The CTR is in the range 0..1, so use 0.05 for a 5% CTR.
Impressions long withCondition("Impressions > 10")
TopImpressionRate double withCondition("TopImpressionRate > 0.25")

The following are the entity properties you may specify.

Column Type Example
Status enumeration The ad group's status. Possible case-sensitive values are:
  • ENABLED
  • PAUSED
  • REMOVED
This example returns only enabled ad groups.

withCondition("Status = ENABLED")
Name string The ad group's name.

withCondition("Name CONTAINS_IGNORE_CASE 'sport'")
CampaignName string The campaign's name.

withCondition("CampaignName CONTAINS_IGNORE_CASE 'truck'")
KeywordMaxCpc double The ad group's CPC bid. The bid is in the account's currency.

withCondition("KeywordMaxCpc > 5.0")
CampaignStatus enumeration The campaign's status. Possible case-sensitive values are:
  • ENABLED
  • PAUSED
  • REMOVED
This example returns only ad groups whose parent campaign is paused.

withCondition("CampaignStatus = PAUSED")
LabelNames string set A list of one or more case-sensitive label names. Use to get ad groups associated with the named labels.

withCondition("LabelNames CONTAINS_ANY ['bar', 'foo']")
CampaignType enumeration The campaign's type. Possible case-sensitive values are:
  • SEARCH_AND_CONTENT
  • SHOPPING
  • DYNAMIC_SEARCH_ADS
This example returns only ad groups whose parent campaign's type is Shopping.

withCondition("CampaignType = SHOPPING")

Arguments

Name Type Description
condition string The condition to apply to the selector.

Returns

Type Description
AdGroupSelector Selector with the condition applied.

withIds(string[] ids)

Gets ad groups with the specified IDs.

You may apply one or more conditions to a selector. A chain of conditions is considered an AND operation. For example, the entity is selected only if condition A is true AND condition B is true. For example, the following call selects only ad group 33333.

var selector = AdsApp.adGroups()
    .withIds(['11111', '22222', '33333'])
    .withIds(['33333', '44444', '55555']);

Arguments

Name Type Description
ids string[] An array of ad group IDs. For limits, see Script execution limits.

Returns

Type Description
AdGroupSelector Selector with the IDs applied.

withLimit(int limit)

Gets the top n ad groups that match the selection criteria.

Arguments

Name Type Description
limit int The number of ad groups to return. The actual number may be less.

Returns

Type Description
AdGroupSelector Selector with limit applied.

See also

AdsApp.adGroups()