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()
andquery()
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
:
- Create a
TextLabel
object. - Set its name.
- Wrap the
TextLabel
in aLabelOperation
and send it toLabelService.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 labelcampaignId
- 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:
- Make sure you filter by label ID, not label name.
- The only supported operators are:
CONTAINS_ALL
,CONTAINS_ANY
, andCONTAINS_NONE
.
Use the Labels field in reports
Each of the following reports has Labels
and LabelIds
fields:
- Campaign Performance Report
- Ad Group Performance Report
- Ad Performance Report
- Keywords Performance Report
- Criteria Performance Report
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: