Labels

Labels allow you to organize elements in your account into meaningful groups so you can quickly and easily filter and report on the data that is of most interest to you. AdWords scripts support labels at the account, campaign, ad group, ad, and keyword levels.

Use cases

Within AdWords accounts, labels can be used to associate arbitrary data with AdWords entities. Within MCC accounts, labels can be used to group similar child accounts. Labels present a number of interesting use cases:

Process a list of accounts
If you are an agency, you could apply a plumber_accounts label to all the accounts for plumbers, and then a script can push plumber-related keywords (e.g. "emergency shower repair") into all campaigns in those accounts.
Process a list of entities
If you have a set of keywords that you want to enable only during weekends, you could apply a weekend_keywords label to them. A script could then enable all keywords with weekend_keywords on Friday evening, and pause them on Monday morning.
Process entities across multiple runs
If you have a large number of entities that cannot be processed in under 30 minutes, then you can create a processed label in your script and apply it to entities that have already been processed. Schedule the script to run hourly, and then process only entities that don’t have the processed label applied to them. See the link checker solution for an example.
Two-step changes
Instead of having the script execute a bid change across a large number of keywords, you can label the keywords with increase_bid_by_10%, log in to the AdWords user interface, filter out the keywords matching the label, review them, and if satisfied with the result, change their bids using Bulk edits.
Flexible bidding
A script could use labels to maintain a history of bid changes. For instance when a script increases a keyword bid by 20%, it can stick the account with a label, increased_20%. The next day when the script runs across the label and realizes it had already increased the bid previously, it may increase the bid by only 10%.
Quality score tracking
A script could label important keywords with their quality scores, then periodically check and report on keywords whose quality score no longer matches the label.

Labels at the account level

AdWords scripts allow you to create labels within MCC accounts, as well as apply labels to AdWords accounts under that MCC. You can create a label as follows:

var labelName = 'High spending accounts';
MccApp.createAccountLabel(labelName);

You can then apply this label to the accounts of your choice using the applyLabel method, as follows:

var accountIds = ['123-456-7890', '345-6789-2100'];
var labelName = 'High spending accounts';

var accounts = MccApp.accounts().withIds(accountIds).get();
while (accounts.hasNext()) {
  var account = accounts.next();
  account.applyLabel(labelName);
}

Similarly, you can remove a label from an account using the removeLabel method, as follows:

var accountIds = ['123-456-7890', '345-6789-2100'];
var labelName = 'High spending accounts';

var accounts = MccApp.accounts().withIds(accountIds).get();
while (accounts.hasNext()) {
  var account = accounts.next();
  account.removeLabel(labelName);
}

The most common use of account labels is to process a group of accounts sharing the same account label. The following code snippet shows how this is done:

var labelName = 'High spending accounts';

var accounts = MccApp.accounts()
    .withCondition('LabelNames CONTAINS "' + labelName + '"')
    .get();

Refer to our MCC scripts guide to learn more about processing multiple accounts in a single script execution. You can find more code examples here.

Labels within an account

You can create and apply labels to an account's campaigns, ad groups, ads, and keywords. Here's how to apply a label to a campaign:

var campaign = AdWordsApp.campaigns()
    .withCondition('Name = "My first campaign"').get().next();
campaign.applyLabel('High performing campaign');

Similarly, you can remove a label using the removeLabel method, as follows:

var campaign = AdWordsApp.campaigns()
    .withCondition('Name = "My first campaign"').get().next();
campaign.removeLabel('High performing campaign');

Labels are most commonly used to process a set of similar entities grouped together by a label. The following code snippet shows how to pause a group of campaigns sharing a common label:

var label = AdWordsApp.labels()
    .withCondition('Name = "Christmas promotions"')
    .get().next();
var campaignIterator = label.campaigns().get();
while (campaignIterator.hasNext()) {
  var campaign = campaignIterator.next();
  campaign.pause();
}

Reporting

You can use label IDs to filter for entities when running performance reports for AdWords accounts. The following code snippet shows how to run a campaign performance report for all campaigns that have a Christmas promotions label:

var label = AdWordsApp.labels()
    .withCondition("Name = 'Christmas promotions'")
    .get().next();
var query = "SELECT CampaignName, Clicks, Impressions, Cost " +
    "FROM CAMPAIGN_PERFORMANCE_REPORT WHERE Labels CONTAINS_ANY " +
    "[" + label.getId() + "] DURING THIS_MONTH"
var rows = AdWordsApp.report(query).rows();

Keep in mind that you can use only CONTAINS_ALL, CONTAINS_ANY and CONTAINS_NONE operators for filtering by label IDs.

You can explore our Labels for Branded Keywords solution to learn more about labels in AdWords accounts. You can find more code examples here.

Send feedback about...

AdWords Scripts
AdWords Scripts
Need help? Visit our support page.