Fetches user lists. Supports filtering and sorting.
Typical usage:
var userListSelector = AdsApp.userlists()
.withCondition("metrics.impressions > 100")
.orderBy("metrics.clicks DESC");
var userListIterator = userListSelector.get();
while (userListIterator.hasNext()) {
var userList = userListIterator.next();
}
Related:
Methods:
get()
Fetches the requested user lists and returns an iterator.
Return values:
orderBy(orderBy)
Specifies the ordering of the resulting entities.
orderBy
parameter can have one of the following forms:
orderBy("user_list.membership_life_span")
- orders
results by user_list.membership_life_span, in ascending order.
orderBy("user_list.size_for_search ASC")
- orders
results by user_list.size_for_search, in ascending order.
orderBy("user_list.name DESC")
- orders results by
user_list.name, in descending order.
See UserListSelector.withCondition(String)
for enumeration of columns that can be used.
orderBy()
may be called multiple times. Consider the
following example:
selector = selector.orderBy("user_list.name ASC")
.orderBy("user_list.membership_life_span DESC");
The results will be ordered by user_list.name in ascending order.
Results with equal user_list.name values will be ordered by
user_list.membership_life_span in descending order.
Arguments:
Name | Type | Description |
orderBy |
String |
Ordering to apply. |
Return values:
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("user_list.membership_life_span > 30")
.withCondition("user_list.size_for_search > 1000");
All specified conditions are
AND
-ed together. The above
example will retrieve entities with a membership life span of more than 30
days and 100 members eligible for search campaigns/ad groups.
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.
user_list.size_for_search):
< <= > >= = !=
- For
String
columns (e.g. user_list.name):
= != (NOT) (LIKE | CONTAINS | REGEXP_MATCH)
- For
Enumeration
columns (ones that can only take one
value from a predefined list, such as user_list.status):
= != IN () NOT IN ()
Conditions using
IN
,
NOT IN
,
CONTAINS
ALL
,
CONTAINS ANY
and
CONTAINS NONE
operators look as follows:
withCondition("ColumnName IN (Value1, Value2)")
Columns
All column names are case-sensitive, and so are all values of enumerated
columns (such as Status).
Column |
Type |
Example |
User list attributes
|
user_list.id |
Long |
withCondition("user_list.id = 123456789") . |
user_list.name |
String |
withCondition("user_list.name REGEXP_MATCH '.*visitor.*'") |
user_list.description |
String |
withCondition("user_list.description = 'Description of a user list'") |
user_list.type |
Enumeration: UNKNOWN , REMARKETING ,
LOGICAL , EXTERNAL_REMARKETING ,
RULE_BASED , SIMILAR , CRM_BASED
|
withCondition("user_list.type = CRM_BASED") |
user_list.membership_status |
Enumeration: UNKNOWN , OPEN ,
CLOSED
|
withCondition("user_list.membership_status = OPEN") |
user_list.membership_life_span |
Long |
withCondition("user_list.membership_life_span > 30") |
user_list.size_for_display |
Long |
withCondition("user_list.size_for_display < 5000") |
user_list.size_for_search |
Long |
withCondition("user_list.size_for_search < 5000") |
user_list.size_range_for_display |
Enumeration: LESS_THAN_FIVE_HUNDRED ,
LESS_THAN_ONE_THOUSAND ,
ONE_THOUSAND_TO_TEN_THOUSAND ,
TEN_THOUSAND_TO_FIFTY_THOUSAND ,
FIFTY_THOUSAND_TO_ONE_HUNDRED_THOUSAND ,
ONE_HUNDRED_THOUSAND_TO_THREE_HUNDRED_THOUSAND ,
THREE_HUNDRED_THOUSAND_TO_FIVE_HUNDRED_THOUSAND ,
FIVE_HUNDRED_THOUSAND_TO_ONE_MILLION ,
ONE_MILLION_TO_TWO_MILLION ,
TWO_MILLION_TO_THREE_MILLION ,
THREE_MILLION_TO_FIVE_MILLION ,
FIVE_MILLION_TO_TEN_MILLION ,
TEN_MILLION_TO_TWENTY_MILLION ,
TWENTY_MILLION_TO_THIRTY_MILLION ,
THIRTY_MILLION_TO_FIFTY_MILLION ,
OVER_FIFTY_MILLION
|
withCondition("user_list.size_range_for_display =
FIFTY_THOUSAND_TO_ONE_HUNDRED_THOUSAND")
|
user_list.size_range_for_search |
Enumeration: LESS_THAN_FIVE_HUNDRED ,
LESS_THAN_ONE_THOUSAND ,
ONE_THOUSAND_TO_TEN_THOUSAND ,
TEN_THOUSAND_TO_FIFTY_THOUSAND ,
FIFTY_THOUSAND_TO_ONE_HUNDRED_THOUSAND ,
ONE_HUNDRED_THOUSAND_TO_THREE_HUNDRED_THOUSAND ,
THREE_HUNDRED_THOUSAND_TO_FIVE_HUNDRED_THOUSAND ,
FIVE_HUNDRED_THOUSAND_TO_ONE_MILLION ,
ONE_MILLION_TO_TWO_MILLION ,
TWO_MILLION_TO_THREE_MILLION ,
THREE_MILLION_TO_FIVE_MILLION ,
FIVE_MILLION_TO_TEN_MILLION ,
TEN_MILLION_TO_TWENTY_MILLION ,
TWENTY_MILLION_TO_THIRTY_MILLION ,
THIRTY_MILLION_TO_FIFTY_MILLION ,
OVER_FIFTY_MILLION
|
withCondition("user_list.size_range_for_search =
FIFTY_THOUSAND_TO_ONE_HUNDRED_THOUSAND")
|
user_list.eligible_for_display |
Boolean |
withCondition("user_list.eligible_for_display = true") |
user_list.eligible_for_search |
Boolean |
withCondition("user_list.eligible_for_search = true") |
Arguments:
Name | Type | Description |
condition |
String |
Condition to add to the selector. |
Return values:
withIds(ids)
Restricts this selector to return only user lists with the
given
user list IDs.
var userListIds = ['12345', '23456', '34567'];
selector = selector.withIds(userListIds);
The resulting selector can be further refined by applying additional
conditions to it. The ID-based condition will then be AND-ed together with
all the other conditions, including any other ID-based conditions. So, for
instance, the following selector:
AdsApp.userLists().userLists()
.withIds(['12345', '23456', '34567'])
.withIds(['34567', '45678', '56789']);
will only get the user list with ID
34567
, since it
would be the only
user list that satisfies both ID conditions.
The selector can only support up to 10,000 IDs. If more than 10,000 IDs
are specified, the corresponding get() call will fail with a runtime error.
Arguments:
Name | Type | Description |
ids |
Object[] |
Array of user list IDs. |
Return values:
withLimit(limit)
Specifies limit for the selector to use. For instance,
withLimit(50)
returns only the first 50 entities.
Arguments:
Name | Type | Description |
limit |
int |
How many entities to return. |
Return values:
withResourceNames(resourceNames)
Restricts this selector to return only user lists with the
given Google Ads API resource names.
const userListResourceNames = [
'customers/1234567890/userLists/111',
'customers/1234567890/userLists/222',
'customers/1234567890/userLists/333',
];
selector = selector.withResourceNames(userListResourceNames);
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:
Name | Type | Description |
resourceNames |
String[] |
Array of user list resource names. |
Return values: