KeywordSelector
Contains the methods for filtering and ordering a list of keywords. For information about selectors, see Selectors.
Example usage:
var iterator = AdsApp.keywords()
.withCondition("AdGroupName = 'AD GROUP NAME GOES HERE'")
.withCondition("CampaignName = 'CAMPAIGN NAME GOES HERE'")
.get();
while (iterator.hasNext()) {
var keyword = iterator.next();
}
Methods
| Method Name | Return Type | Description |
|---|---|---|
| forDateRange(Object dateFrom, Object dateTo) | KeywordSelector | Applies the start and end dates for selecting performance metrics. |
| forDateRange(string dateRange) | KeywordSelector | Applies the predefined date range for selecting performance metrics. |
| get | KeywordIterator | Gets an iterator used to iterate through the list of keywords. |
| orderBy(string orderBy) | KeywordSelector | Applies the specified ordering to the selected keywords. |
| withCondition(string condition) | KeywordSelector | Applies filter criteria to the keywords. |
| withIds(string[] ids) | KeywordSelector | Gets keywords with the specified IDs. |
| withLimit(int limit) | KeywordSelector | Gets the top n keywords 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 |
|---|---|
| KeywordSelector | 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 |
|---|---|
| KeywordSelector | Selector with date range applied. |
get
Gets an iterator used to iterate through the list of keywords.
Returns
| Type | Description |
|---|---|
| KeywordIterator | An iterator used to iterate through the selected keywords. |
orderBy(string orderBy)
Applies the specified ordering to the selected keywords.
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 results 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 |
|---|---|
| KeywordSelector | Selector with ordering applied. |
withCondition(String condition)
Applies filter criteria to the keywords.
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 keyword filtering. The column names are case sensitive.
The following are the performance metrics columns you may specify.
| Column | Type | Example | Microsoft Advertising web UI filter |
|---|---|---|---|
| AbsoluteTopImpressionRate | double | withCondition("AbsoluteTopImpressionRate > 0.25") |
Abs. Top Impr. Rate |
| AverageCpc | double | withCondition("AverageCpc < 2.75") |
Avg. CPC |
| AverageCpm | double | withCondition("AverageCpm > 0.65") |
Avg. CPM |
| ClickConversionRate | double | withCondition("ClickConversionRate > 0.25") |
Conv. Rate |
| Clicks | long | withCondition("Clicks >= 33") |
Clicks |
| ConvertedClicks | long | withCondition("ConvertedClicks >= 10") |
Conv. |
| Cost | double | withCondition("Cost > 3.25")The cost is in the account's currency. |
Spend |
| Ctr | double | withCondition("Ctr > 0.05")The CTR is in the range 0..1, so use 0.05 for a 5% CTR. |
CTR |
| Impressions | long | withCondition("Impressions > 10") |
Impr. |
| TopImpressionRate | double | withCondition("TopImpressionRate > 0.25") |
Top Impr. Rate |
The following are the entity properties you may specify.
| Column | Type | Example | Microsoft Advertising web UI filter |
|---|---|---|---|
| Status | enumeration | The keyword's status. Possible case-sensitive values are:
withCondition("Status = ENABLED") |
Status |
| CombinedApprovalStatus | string | The keyword's approval status. Possible case-sensitive values are:
This example returns keywords that need attention. withCondition("CombinedApprovalStatus IN ['APPROVED_LIMITED', 'DISAPPROVED']") |
|
| Text | string | The keyword's text. Include only the keyword's text. Don't include the keyword's match type in the text. For example, if the keyword is an exact match keyword such as [books], use books not [books].withCondition("Text STARTS_WITH 'flowers'") |
Keyword Text |
| KeywordMatchType | enumeration | The keyword's match type. Possible case-sensitive values are:
withCondition("KeywordMatchType = EXACT") |
Match type |
| MaxCpc | double | The keyword's maximum CPC bid amount. The CPC is in the account's currency.withCondition("MaxCpc > 0.40") |
Bid |
| DestinationUrl | string | withCondition("DestinationUrl STARTS_WITH 'http://www.contoso.com'") |
Destination URL |
| FinalUrls | string | withCondition("FinalUrls CONTAINS 'http://www.contoso.com'") |
|
| QualityScore | int | withCondition("QualityScore > 5") |
Qual. score |
| FirstPageCpc | double | The average amount an advertiser is charged each time their ad is clicked when it shows up on the sidebar. For example, if an advertiser paid a total of $48.35 for 300 clicks, the advertiser's average CPC is $0.16. Use this information to help decide whether to increase your keyword bid to improve the chance that your ad shows up on the sidebar. The CPC is in the account's currency.withCondition("FirstPageCpc > 6.00") |
Est. first page bid |
| TopOfPageCpc | double | The average amount an advertiser is charged each time their ad is clicked when it shows up above the organic search results. For example, if an advertiser paid a total of $48.35 for 300 clicks, the advertiser's average CPC is $0.16. Use this information to help decide whether to increase your keyword bid to improve the chance that your ad shows up above the organic search results. The CPC is in the currency of the current account.withCondition("TopOfPageCpc > 8.00") |
Best position |
| AdGroupName | string | The name of the ad group that contains the keywords.withCondition("AdGroupName = 'foo'") |
|
| AdGroupStatus | enumeration | The ad group's status. Possible case-sensitive values are:
withCondition("AdGroupStatus = ENABLED") |
|
| CampaignName | string | The name of the campaign that contains the keywords.withCondition("CampaignName = 'bar'") |
|
| CampaignStatus | enumeration | The campaign's status. Possible case-sensitive values are:
withCondition("CampaignStatus = ENABLED") |
|
| LabelNames | string set | A list of one or more case-sensitive label names. Use to get keywords associated with the named labels.withCondition("LabelNames CONTAINS_ANY ['bar', 'foo']") |
|
| Id | Long | The ID of the keyword to test. For example, you can use this column to check for keywords with IDs greater than the specified ID.withCondition('Id > 1234') |
Arguments
| Name | Type | Description |
|---|---|---|
| condition | string | The condition to add to the selector. |
Returns
| Type | Description |
|---|---|
| KeywordSelector | Selector with the condition applied. |
withIds(string[] ids)
Gets keywords 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 keyword 33333.
AdsApp.keywords()
.withIds(['11111', '22222', '33333'])
.withIds(['33333', '44444', '55555']);
Arguments
| Name | Type | Description |
|---|---|---|
| ids | string[] | An array of keyword IDs. For limits, see Script execution limits. |
Returns
| Type | Description |
|---|---|
| KeywordSelector | Selector with the IDs applied. |
withLimit(int limit)
Gets the top n keywords that match the selection criteria.
Arguments
| Name | Type | Description |
|---|---|---|
| limit | int | The number of keywords to return. The actual number may be less. |
Returns
| Type | Description |
|---|---|
| KeywordSelector | Selector with limit applied. |
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for