Labels

Labels allow you to categorize your campaigns, ad groups, ads, and keywords, and use those categories to simplify your workflow in a variety of ways.

This guide covers the steps required to do the following:

  • Create labels.
  • Assign labels to your campaigns.
  • Retrieve and filter report results by label, using CampaignService get() and query() requests.

This guide focuses on campaigns, but you can use the same approach for ad groups, ads, and keywords.

Use cases

Typical scenarios for using labels include the following:

  • Your account has campaigns you enable only during certain times of the year, and you want to easily include or exclude those campaigns from reports.
  • You added a new set of keywords to your ad group and you want to compare their stats to other keywords in your ad group.
  • Users of your Google Ads account each manage a subset of campaigns and you want an easy way to identify the set of campaigns for each user.
  • Your application needs to mark the status of certain objects as processed, audited, highlighted, etc.

See the Help Center article on using labels for additional information and an example of how labels work in Google Ads.

Create labels

You create labels using a TextLabel object. To create a TextLabel:

  1. Create a TextLabel object.
  2. Set its name.
  3. Wrap the TextLabel in a LabelOperation and send it to LabelService.mutate().

You'll need the IDs of the new labels for the next steps, so make sure you capture them from the mutate call's response, or use LabelService.get() or LabelService.query() to retrieve the IDs.

Assign labels to your campaigns, ad groups, criteria, or ads

Use the mutateLabels operation to assign labels. For example, to assign labels to a campaign, use CampaignService.mutateLabels with one or more CampaignLabel objects, each of which consists of the following:

  • labelId - The ID of a label
  • campaignId - The ID of a campaign

Create a CampaignLabel object for each label/campaign pair you want to add, wrap it in a CampaignLabelOperation with the ADD operator, and send it to CampaignService.mutateLabels.

Retrieve objects using their labels

Now that you've assigned labels to your campaigns, you can use the Labels field to retrieve objects that have one or more specific labels. For example, here's a CampaignService.query AWQL statement that will select the ID, name, and labels for each campaign associated with any one of three label IDs.

SELECT Id, Name, Labels
WHERE Labels CONTAINS_ANY [123456, 789012, 345678]

A few tips to keep in mind when defining filters with labels:

  1. Make sure you filter by label ID, not label name.
  2. The only supported operators are: CONTAINS_ALL, CONTAINS_ANY, and CONTAINS_NONE.

Use the Labels field in reports

Each of the following reports has Labels and LabelIds fields:

As with other fields of type List, you can filter reporting results by LabelIds using CONTAINS_ANY, CONTAINS_ALL, or CONTAINS_NONE.

The reporting service returns a semicolon-separated list of label names and IDs in the Labels and LabelIds fields, for example:

CAMPAIGN_PERFORMANCE_REPORT (Jul 1, 2014-Jul 7, 2014)
Campaign ID,Labels,Label IDs
1999999,Label 1; Label 2,456; 678
2999999,Label 2;678
Total, --, --

Code examples

The Campaign Management folder of each client library contains code examples for adding labels to campaigns and retrieving campaigns by label:

Java

C#

PHP

Perl

Python

Ruby