Skip to content

Latest commit

 

History

History
192 lines (140 loc) · 8.54 KB

AdSelector.md

File metadata and controls

192 lines (140 loc) · 8.54 KB
Raw
title description author ms.author ms.service ms.topic
AdSelector object
Contains the methods for filtering the list of ads to return.
jonmeyers
jonmeyers
bing-ads-scripts
article

AdSelector

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

Methods

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

forDateRange(String dateRange)

Applies the predefined date range for selecting performance metrics.

[!INCLUDEdate-range-conditions-message]

[!INCLUDEdate-range-constants]

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

get

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

Returns

Type Description
AdIterator An iterator used to iterate through the selected ads.

orderBy(String orderBy)

Applies the specified ordering to the selected ads.

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 ads 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
AdSelector Selector with ordering applied.

withCondition(String condition)

Applies filter criteria to the ads.

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

[!INCLUDEoperators]

Supported Columns

Supported columns for filtering ads. 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 ad's status. Possible case-sensitive values are:
  • ENABLED
  • PAUSED
  • REMOVED
This example returns only enabled ads.

withCondition("Status = ENABLED")
Type enumeration The ad's derived type. Possible case-sensitive values are:
  • EXPANDED_TEXT_AD
This example returns only expanded text ads.

withCondition("Type = EXPANDED_TEXT_AD")
CombinedApprovalStatus string The ad'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 ads that need attention.

withCondition("CombinedApprovalStatus IN ['APPROVED_LIMITED', 'DISAPPROVED']")
CreativeFinalUrls string The ad's final URL.

withCondition("CreativeFinalUrls CONTAINS_IGNORE_CASE 'contoso.com'")
AdGroupName string The name of the ad group that the ads belong to.

withCondition("AdGroupName CONTAINS_IGNORE_CASE 'truck'")
AdGroupStatus enumeration The status of the ad group that the ads belong to. Possible case-sensitive values are:
  • ENABLED
  • PAUSED
  • REMOVED
This example returns only ads whose parent ad group is paused.

withCondition("AdGroupStatus = PAUSED")
CampaignName string The name of the campaign that the ads belong to.

withCondition("CampaignName CONTAINS_IGNORE_CASE 'truck'")
CampaignStatus enumeration The status of the campaign that the ads belong to. Possible case-sensitive values are:
  • ENABLED
  • PAUSED
  • REMOVED
This example returns only ads whose parent campaign is paused.

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

withCondition("LabelNames CONTAINS_ANY ['bar', 'foo']")
Id Long The ID of the ad to test. For example, you can use this column to check for ads with IDs greater than the specified ID.

withCondition('Id > 1234')

Arguments

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

Returns

Type Description
AdSelector Selector with the condition applied.

withIds(string[] ids)

Gets ads with the specified IDs.

[!INCLUDEwith-ids-chaining] For example, the following call selects only ad 33333.

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

Arguments

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

Returns

Type Description
AdSelector Selector with the IDs applied.

withLimit(int limit)

Gets the top n ads that match the selection criteria.

Arguments

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

Returns

Type Description
AdSelector Selector with limit applied.

See also

AdsApp.ads()