CampaignSelector

Article
03/20/2023

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

Example usage:

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

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

Methods

Method Name	Return Type	Description
forDateRange(Object dateFrom, Object dateTo)	CampaignSelector	Applies the start and end dates for selecting performance metrics.
forDateRange(string dateRange)	CampaignSelector	Applies the predefined date range for selecting performance metrics.
get	CampaignIterator	Gets an iterator used to iterate through the list of campaigns.
orderBy(string orderBy)	CampaignSelector	Applies the specified ordering to the selected campaigns.
withCondition(string condition)	CampaignSelector	Applies the filter to the list of campaigns.
withIds(string[] ids)	CampaignSelector	Gets campaigns with the specified IDs.
withLimit(int limit)	CampaignSelector	Gets the top n campaigns 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
CampaignSelector	Selector with date range applied.

forDateRange(string dateRange)

Applies the predefined date range for selecting performance metrics.

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

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.

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
CampaignSelector	Selector with date range applied.

get

Gets an iterator used to iterate through the list of campaigns.

Returns

Type	Description
CampaignIterator	An iterator used to iterate through the selected campaigns.

orderBy(string orderBy)

Applies the specified ordering to the selected campaigns.

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 campaigns 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
CampaignSelector	Selector with ordering applied.

withCondition(string condition)

Applies the filter to the list of campaigns campaigns.

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

columnName is one of the supported columns. If columName is set to a performance metric column name, you must specify a date range using forDateRange(String dateRange) or forDateRange(Object dateFrom, Object dateTo).
operator is one of the supported operators.

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 for campaign filtering. The column 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 campaign's status. Possible case-sensitive values are: ENABLED PAUSED REMOVED BUDGET_PAUSED BUDGET_AND_USER_PAUSED This example returns only enabled enabled. `withCondition("Status = ENABLED")`
Name	string	The campaign's name. `withCondition("Name CONTAINS_IGNORE_CASE 'clearance'")`
Budget	double	The campaign's budget. `withCondition("Budget > 500.0")`
BudgetType	enumeration	The campaign's budget type. Possible case-sensitive values are: STANDARD ACCELERATED `withCondition("BudgetType = 'STANDARD'")`
DeliveryStatus	enumeration	The campaign's delivery status. Possible case-sensitive values are: ELIGIBLE LIMITED_BY_BUDGET HOLD CAMPAIGN_OUT_OF_BUDGET CAMPAIGN_SUSPENDED CAMPAIGN_PAUSED `withCondition("DeliveryStatus NOT_IN ['LIMITED_BY_BUDGET', 'HOLD', 'CAMPAIGN_OUT_OF_BUDGET']")`
LabelNames	string set	A list of one or more case-sensitive label names. Use to get campaigns associated with the named labels. `withCondition("LabelNames CONTAINS_ANY ['bar', 'foo']")`
Type	enumeration	The campaign's type. Possible case-sensitive values are: SEARCH_AND_CONTENT SHOPPING DYNAMIC_SEARCH_ADS This example returns only campaigns whose type is Shopping. `withCondition("CampaignType = SHOPPING")`

Arguments

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

Returns

Type	Description
CampaignSelector	Selector with the condition applied.

withIds(string[] ids)

Gets campaigns 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 campaign 33333.

AdsApp.campaigns()
    .withIds(['11111', '22222', '33333'])
    .withIds(['33333', '44444', '55555']);

Arguments

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

Returns

Type	Description
CampaignSelector	Selector with the IDs applied.

withLimit(int limit)

Gets the top n campaigns that match the selection criteria.

Arguments

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

Returns

Type	Description
CampaignSelector	Selector with limit applied.

Share via

CampaignSelector

Methods

forDateRange(Object dateFrom, Object dateTo)

Arguments

Returns

forDateRange(string dateRange)

Arguments

Returns

get

Returns

orderBy(string orderBy)

Arguments

Returns

withCondition(string condition)

Operators

Arguments

Returns

withIds(string[] ids)

Arguments

Returns

withLimit(int limit)

Arguments

Returns

See also

Feedback

Additional resources