Skip to content

Latest commit

 

History

History
203 lines (154 loc) · 10.5 KB

KeywordSelector.md

File metadata and controls

203 lines (154 loc) · 10.5 KB
title description author ms.author ms.service ms.topic
KeywordSelector object
Contains the methods for filtering the list of keywords to return.
jonmeyers
jonmeyers
bing-ads-scripts
article

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.

[!INCLUDEdate-range-objects]

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.

[!INCLUDEdate-range-constants]

[!INCLUDEdate-range-conditions-message]

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");

[!INCLUDEorder-by-limit]

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:

[!INCLUDEoperators]

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:
  • ENABLED
  • PAUSED
  • REMOVED
withCondition("Status = ENABLED")
Status
CombinedApprovalStatus string The keyword's approval status. Possible case-sensitive values are:
  • APPROVED
  • APPROVED_LIMITED
  • UNDER_REVIEW
  • DISAPPROVED
For information about these values, see Editorial approval status values.

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:
  • BROAD
  • EXACT
  • PHRASE
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:
  • ENABLED
  • PAUSED
  • REMOVED
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:
  • ENABLED
  • PAUSED
  • REMOVED
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.

[!INCLUDEwith-ids-chaining] 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