Share your feedback about the Google Ads (AdWords) API. Take the 2021 AdWords API and Google Ads API Annual Survey.

Create campaign criteria

In Get suggestions, we demonstrated how to retrieve a set of KeywordThemeConstant objects using a word or phrase. In this step, we use those same keyword theme constants to create a set of CampaignCriterion objects for the Smart campaign to target.

Similar to how we used the budget amount suggested by the SmartCampaignSuggestService when creating a budget, we recommend that you create campaign criteria based on the keyword theme constants retrieved from the KeywordThemeConstantService in Get suggestions.

Here are the key requirements for Smart campaign criteria:

In the following example, the keyword theme constants have been converted to KeywordThemeInfo objects by setting their resource name onto the KeywordThemeInfo.keyword_theme_constant field. We set the campaign field using the temporary resource name set on the campaign in the previous step.

Java

/**
 * Creates {@link com.google.ads.googleads.v9.resources.CampaignCriterion} operations for add each
 * {@link KeywordThemeInfo}.
 */
private Collection<? extends MutateOperation> createCampaignCriterionOperations(
    long customerId,
    List<KeywordThemeInfo> keywordThemeInfos,
    SmartCampaignSuggestionInfo suggestionInfo) {
  List<MutateOperation> keywordThemeOperations =
      keywordThemeInfos.stream()
          .map(
              keywordTheme -> {
                MutateOperation.Builder builder = MutateOperation.newBuilder();
                builder
                    .getCampaignCriterionOperationBuilder()
                    .getCreateBuilder()
                    .setCampaign(ResourceNames.campaign(customerId, SMART_CAMPAIGN_TEMPORARY_ID))
                    .setKeywordTheme(keywordTheme);
                return builder.build();
              })
          .collect(Collectors.toList());

  List<MutateOperation> locationOperations =
      suggestionInfo.getLocationList().getLocationsList().stream()
          .map(
              location -> {
                MutateOperation.Builder builder = MutateOperation.newBuilder();
                builder
                    .getCampaignCriterionOperationBuilder()
                    .getCreateBuilder()
                    .setCampaign(ResourceNames.campaign(customerId, SMART_CAMPAIGN_TEMPORARY_ID))
                    .setLocation(location);
                return builder.build();
              })
          .collect(Collectors.toList());

  return Stream.concat(keywordThemeOperations.stream(), locationOperations.stream())
      .collect(Collectors.toList());
}
      

C#

/// <summary>
/// Creates a list of MutateOperations that create new campaign criteria.
/// </summary>
/// <param name="customerId">The Google Ads customer ID.</param>
/// <param name="keywordThemeInfos">A list of KeywordThemeInfos.</param>
/// <returns>A list of MutateOperations that create new campaign criteria.</returns>
private IEnumerable<MutateOperation> CreateCampaignCriterionOperations(long customerId,
    IEnumerable<KeywordThemeInfo> keywordThemeInfos)
{
    return keywordThemeInfos.Select(keywordThemeInfo => new MutateOperation
    {
        CampaignCriterionOperation = new CampaignCriterionOperation
        {
            Create = new CampaignCriterion
            {
                // Set the campaign ID to a temporary ID.
                Campaign = ResourceNames.Campaign(customerId, SMART_CAMPAIGN_TEMPORARY_ID),
                // Set the criterion type to KeywordTheme.
                Type = CriterionType.KeywordTheme,
                // Set the keyword theme to each KeywordThemeInfo in turn.
                KeywordTheme = keywordThemeInfo,
            }
        }
    }).ToList();
}
      

PHP

private static function createCampaignCriterionOperations(
    int $customerId,
    array $keywordThemeInfos,
    SmartCampaignSuggestionInfo $smartCampaignSuggestionInfo
): array {
    $operations = [];
    foreach ($keywordThemeInfos as $info) {
        // Creates the campaign criterion object.
        $campaignCriterion = new CampaignCriterion([
            // Sets the campaign ID to a temporary ID.
            'campaign' =>
                ResourceNames::forCampaign($customerId, self::SMART_CAMPAIGN_TEMPORARY_ID),
            // Sets the keyword theme to the given KeywordThemeInfo.
            'keyword_theme' => $info
        ]);

        // Creates the MutateOperation that creates the campaign criterion and adds it to the
        // list of operations.
        $operations[] = new MutateOperation([
            'campaign_criterion_operation' => new CampaignCriterionOperation([
                'create' => $campaignCriterion
            ])
        ]);
    }

    // Create a location criterion for each location in the suggestion info object to add
    // corresponding location targeting to the Smart campaign.
    foreach ($smartCampaignSuggestionInfo->getLocationList()->getLocations() as $location) {
        // Creates the campaign criterion object.
        $campaignCriterion = new CampaignCriterion([
            // Sets the campaign ID to a temporary ID.
            'campaign' =>
                ResourceNames::forCampaign($customerId, self::SMART_CAMPAIGN_TEMPORARY_ID),
            // Set the location to the given location.
            'location' => $location
        ]);

        // Creates the MutateOperation that creates the campaign criterion and adds it to the
        // list of operations.
        $operations[] = new MutateOperation([
            'campaign_criterion_operation' => new CampaignCriterionOperation([
                'create' => $campaignCriterion
            ])
        ]);
    }

    return $operations;
}
      

Python

def _create_campaign_criterion_operations(
    client, customer_id, keyword_theme_infos, suggestion_info
):
    """Creates a list of MutateOperations that create new campaign criteria.

    Args:
        client: an initialized GoogleAdsClient instance.
        customer_id: a client customer ID.
        keyword_theme_infos: a list of KeywordThemeInfos.
        suggestion_info: A SmartCampaignSuggestionInfo instance.

    Returns:
        a list of MutateOperations that create new campaign criteria.
    """
    campaign_service = client.get_service("CampaignService")

    operations = []
    for info in keyword_theme_infos:
        mutate_operation = client.get_type("MutateOperation")
        campaign_criterion = (
            mutate_operation.campaign_criterion_operation.create
        )
        # Set the campaign ID to a temporary ID.
        campaign_criterion.campaign = campaign_service.campaign_path(
            customer_id, _SMART_CAMPAIGN_TEMPORARY_ID
        )
        # Set the keyword theme to the given KeywordThemeInfo.
        campaign_criterion.keyword_theme = info
        # Add the mutate operation to the list of other operations.
        operations.append(mutate_operation)

    # Create a location criterion for each location in the suggestion info
    # object to add corresponding location targeting to the Smart campaign
    for location_info in suggestion_info.location_list.locations:
        mutate_operation = client.get_type("MutateOperation")
        campaign_criterion = (
            mutate_operation.campaign_criterion_operation.create
        )
        # Set the campaign ID to a temporary ID.
        campaign_criterion.campaign = campaign_service.campaign_path(
            customer_id, _SMART_CAMPAIGN_TEMPORARY_ID
        )
        # Set the location to the given location.
        campaign_criterion.location = location_info
        # Add the mutate operation to the list of other operations.
        operations.append(mutate_operation)

    return operations
      

Ruby

# Creates a list of mutate_operations that create new campaign criteria.
def create_campaign_criterion_operations(
  client,
  customer_id,
  keyword_theme_infos)
  operations = []

  keyword_theme_infos.each do |info|
    operations << client.operation.mutate do |m|
      m.campaign_criterion_operation =
        client.operation.create_resource.campaign_criterion do |cc|
        # Sets the campaign ID to a temporary ID.
        cc.campaign = client.path.campaign(
          customer_id, SMART_CAMPAIGN_TEMPORARY_ID)
        # Sets the criterion type to KEYWORD_THEME.
        cc.type = :KEYWORD_THEME
        # Sets the keyword theme to the given keyword_theme_info.
        cc.keyword_theme = info
      end
    end
  end

  operations
end
      

Perl

# Creates a list of MutateOperations that create new campaign criteria.
sub _create_campaign_criterion_operations {
  my ($customer_id, $keyword_theme_infos, $suggestion_info) = @_;

  my $campaign_criterion_operations = [];

  foreach my $keyword_theme_info (@$keyword_theme_infos) {
    push @$campaign_criterion_operations,
      Google::Ads::GoogleAds::V9::Services::GoogleAdsService::MutateOperation->
      new({
        campaignCriterionOperation =>
          Google::Ads::GoogleAds::V9::Services::CampaignCriterionService::CampaignCriterionOperation
          ->new({
            create =>
              Google::Ads::GoogleAds::V9::Resources::CampaignCriterion->new({
                # Set the campaign ID to a temporary ID.
                campaign =>
                  Google::Ads::GoogleAds::V9::Utils::ResourceNames::campaign(
                  $customer_id, SMART_CAMPAIGN_TEMPORARY_ID
                  ),
                # Set the criterion type to KEYWORD_THEME.
                type => KEYWORD_THEME,
                # Set the keyword theme to the given KeywordThemeInfo.
                keywordTheme => $keyword_theme_info
              })})});
  }

  # Create a location criterion for each location in the suggestion info object
  # to add corresponding location targeting to the Smart campaign.
  foreach my $location_info (@{$suggestion_info->{locationList}{locations}}) {
    push @$campaign_criterion_operations,
      Google::Ads::GoogleAds::V9::Services::GoogleAdsService::MutateOperation->
      new({
        campaignCriterionOperation =>
          Google::Ads::GoogleAds::V9::Services::CampaignCriterionService::CampaignCriterionOperation
          ->new({
            create =>
              Google::Ads::GoogleAds::V9::Resources::CampaignCriterion->new({
                # Set the campaign ID to a temporary ID.
                campaign =>
                  Google::Ads::GoogleAds::V9::Utils::ResourceNames::campaign(
                  $customer_id, SMART_CAMPAIGN_TEMPORARY_ID
                  ),
                # Set the criterion type to LOCATION.
                type => LOCATION,
                # Set the location to the given location.
                location => $location_info
              })})});
  }

  return $campaign_criterion_operations;
}
      

Negative keyword theme campaign criteria

To negatively target a keyword theme campaign criterion in a Smart campaign, you must use a free-form keyword theme by setting the free_form_keyword_theme field on a KeywordThemeInfo instance.

Negative keyword theme criteria behave differently from positive keyword theme criteria. Whereas a positive keyword theme criterion is adjusted to target other similar criteria automatically, a negative keyword theme criterion is restricted to only negatively target the exact given term. The behavior is equivalent to how a negative phrase match keyword behaves.