If you have a set of keywords or placements that gives you unwanted impressions or clicks across multiple campaigns, you can create a central list of these negative keywords or placements in AdWords and add it to all of your campaigns. This feature, known as “shared sets”, is available through the AdWords API as a beta feature from version v201302 onwards.

This guide explains how to use version v201302 of the AdWords API to create and work with shared sets. The code examples in this guide use the AdWords API Java library. We have code examples for other supported client libraries as well.

Creating shared sets

To use a shared set of negative keywords, you need to first create a shared set, and then populate it with the list of keywords you want to exclude. The following code snippet creates a shared set of negative keywords using the SharedSetService.

// Create the operation.
SharedSetOperation operation = new SharedSetOperation();
operation.setOperator(Operator.ADD);

// Create the shared set.
SharedSet sharedSet = new SharedSet();
sharedSet.setName("API Negative keyword list for demo");

// Set the type of the shared set. This may be negative keywords or placements.
sharedSet.setType(SharedSetType.NEGATIVE_KEYWORDS);
operation.setOperand(sharedSet);

SharedSetReturnValue retval = sharedSetService.mutate(
    new SharedSetOperation[] {operation});
for (SharedSet set : retval.getValue()) {
  System.out.println("Shared set with id = " + set.getSharedSetId() + ", name = " +
      set.getName() + ", type = " + set.getType() + ", status = " + set.getStatus() +
      "was created.");
}

Once you have created the shared set, you can use the SharedCriterionService to add keywords to the newly created set. The following code snippet adds two new keywords to the shared set.

String[] keywordTexts = new String[] {"mars cruise", "mars hotels"};

List operations = new ArrayList();
for (String keywordText: keywordTexts) {
  // Create the shared criterion.
  Keyword keyword = new Keyword();
  keyword.setText(keywordText);
  keyword.setMatchType(KeywordMatchType.BROAD);

  SharedCriterion sharedCriterion = new SharedCriterion();
  sharedCriterion.setCriterion(keyword);
  sharedCriterion.setNegative(true);
  sharedCriterion.setSharedSetId(sharedSetId);

  SharedCriterionOperation operation = new SharedCriterionOperation();
  operation.setOperator(Operator.ADD);
  operation.setOperand(sharedCriterion);
  operations.add(operation);
}

SharedCriterionReturnValue retval = sharedSetService.mutate(operations.toArray(
    new SharedCriterionOperation[operations.size()]));
for (SharedCriterion sharedCriterion : retval.getValue()) {
  Keyword keyword = (Keyword) sharedCriterion.getCriterion();
  System.out.println("Added keyword with id = " + keyword.getId() + ", text = " +
      keyword.getText() + ", matchtype = " + keyword.getMatchType() + " to shared " +
      "set with id = " + sharedSetId + ".");
}

You can use the memberCount field to determine the number of keywords or placements in a shared set. Another useful field is the referenceCount field which tells you how many campaigns a shared set is associated with.

Applying shared sets to a campaign

Once you have created a shared set, you can attach it to multiple campaigns using CampaignSharedSetService. The following code shows how to attach an existing shared set to a campaign:

// Create the campaign shared set
CampaignSharedSet campaignSharedSet = new CampaignSharedSet();
campaignSharedSet.setCampaignId(campaignId);
campaignSharedSet.setSharedSetId(sharedSetId);

CampaignSharedSetOperation operation = new CampaignSharedSetOperation();
operation.setOperator(Operator.ADD);
operation.setOperand(campaignSharedSet);

CampaignSharedSetReturnValue retval = campaignSharedSetService.mutate(
    new CampaignSharedSetOperation[] {operation});
for (CampaignSharedSet attachedCampaignSharedSet : retval.value) {
  System.out.println("Attached shared set with id = " +
      attachedCampaignSharedSet.getSharedSetId() + " to campaign id " +
      attachedCampaignSharedSet.getCampaignId() + ".");
}

You can use the CampaignSharedSetService.get() method to retrieve the shared sets that have been applied to an existing campaign as shown below.

// Create the selector.
Selector selector = new Selector();
selector.setFields(new String[] {"SharedSetId", "CampaignId", "SharedSetName",
   "SharedSetType", "Status"});

// Filter your results by specific campaign id.
Predicate predicate = new Predicate();
predicate.setField("CampaignId");
predicate.setOperator(PredicateOperator.EQUALS);
predicate.setValues(new String[] {campaignId.toString()});

// Filter your results by the type of shared set.
Predicate predicate1 = new Predicate();
predicate1.setField("SharedSetType");
predicate1.setOperator(PredicateOperator.IN);
predicate1.setValues(new String[] {"NEGATIVE_KEYWORDS", "NEGATIVE_PLACEMENTS"});

selector.setPredicates(new Predicate[] {predicate});

CampaignSharedSetPage page = campaignSharedSetService.get(selector);
if (page.getEntries() != null) {
  for (CampaignSharedSet campaignSharedSet : page.getEntries()) {
    System.out.println("Shared set with id = " + campaignSharedSet.getSharedSetId() +
        ", name = " + campaignSharedSet.getSharedSetName() + ", type = " +
        campaignSharedSet.getSharedSetType() + " and status = " +
        campaignSharedSet.getStatus() + " was found.");
    }
  }
}

Reporting

Version v201302 of the AdWords API introduces three new report types to track the performance of shared sets. You can use SHARED_SET_REPORT to retrieve reports data for shared sets and CAMPAIGN_SHARED_SET_REPORT to retrieve reports data for campaign shared sets. SHARED_SET_CRITERIA_REPORT provides a downloadable snapshot of shared set criteria.

The shared set feature will help you manage your negative keywords and placement exclusions more easily and efficiently by removing the need for duplication of entities across your account. Download one of our client libraries to get started. And if you have further questions, feel free to post in the AdWords API Forum.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.