Labels

Labels are a powerful feature of AdWords that allow you to categorize your campaigns, ad groups, ads, and keywords, and use those categories to simplify your workflow. A few scenarios where labels could be helpful are:

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

See the Help Center article on using labels for additional information and an in-depth example of how labels work in AdWords.

This guide will walk you through the steps required to create labels, assign labels to your campaigns, use labels in CampaignService get and query requests, and retrieve and filter report results by labels. Although this guide focuses on campaigns, you can use the same approach for ad groups, ads, and keywords.

Create your labels

The only type of label currently available is the TextLabel. All you need to do to create a TextLabel is:

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 newly created labels for the next steps, so make sure you capture them from the mutate call's response, or simply use LabelService.get or LabelService.query to retrieve the IDs.

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

This is where the new mutateLabels operation comes into play. Using campaigns as an example, CampaignService.mutateLabels needs one or more CampaignLabel objects, each of which consists of:

• 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.

Use your labels to retrieve objects

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.

Utilize the new 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 will return a semicolon (;) separated list of label names and IDs in the Labels and LabelIds fields, e.g.,

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 CampaignManagement folder of each client library contains the following code examples for adding labels to campaigns and retrieving campaigns by label: