Labels

Labels let you organize elements in your account into meaningful groups so you can quickly filter and report on the data that is most interesting to you. Google Ads scripts support labels at the account, campaign, ad group, ad, and keyword levels.

Use cases

Within Google Ads accounts, labels can be used to associate arbitrary data with Google Ads entities. Within manager accounts, labels can be used to group similar child accounts. Labels help with a number of 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 (for example, "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.
• 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 Google Ads UI, 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 mark 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 could 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

Google Ads scripts let you create labels within manager accounts, as well as apply labels to Google Ads accounts under that manager account:

const labelName = 'High spending accounts';
AdsManagerApp.createAccountLabel(labelName);

You can apply the label to the accounts of your choice using the applyLabel method:

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

const accounts = AdsManagerApp.accounts().withIds(accountIds).get();
for (const account of accounts) {
  account.applyLabel(labelName);
}

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

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

const accounts = AdsManagerApp.accounts().withIds(accountIds).get();
for (const account of accounts) {
  account.removeLabel(labelName);
}

The most common use of account labels is to process a group of accounts sharing the same account label:

const labelName = 'High spending accounts';

const accounts = AdsManagerApp.accounts()
    .withCondition(`LabelNames CONTAINS "${labelName}"`)
    .get();

Note: LabelNames is a convenience method, and requires an extra API call behind the scenes to look up the label's resource name. If you already have a label object, you should use a filter of customer_client.applied_labels CONTAINS ALL (${label.getResourceName()}) instead. See the reporting section below for more details on resource names.

Refer to our manager account scripts guide to learn more about processing multiple accounts in a single script execution.

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:

const campaign = AdsApp.campaigns()
    .withCondition('campaign.name = "My first campaign"').get().next();
campaign.applyLabel('High performing campaign');

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

const campaign = AdsApp.campaigns()
    .withCondition('campaign.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:

const label = AdsApp.labels()
    .withCondition('label.name = "Christmas promotions"')
    .get().next();
var campaignIterator = label.campaigns().get();
for (const campaign of campaignIterator) {
  campaign.pause();
}

Reporting

You can use label resource names to filter for entities when running performance reports for Google Ads accounts. Resource names are a concept from the Google Ads API and are sometimes used when running reports with GAQL. A label resource name is always in the format:

customers/[customer id]/labels/[label id]

You can fetch a label's resource name using its getResourceName method.

The following code snippet shows how to run a campaign report for all campaigns that have a "Christmas promotions" label:

const label = AdsApp.labels()
    .withCondition("label.name = 'Christmas promotions'")
    .get().next();
const query = `SELECT campaign.name, metrics.clicks, metrics.impressions, metrics.cost ` +
    `FROM campaign WHERE campaign.labels CONTAINS ANY ` +
    `["${label.getResourceName()}"] AND segments.date DURING THIS_MONTH`;
const result = AdsApp.search(query);

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