Labels

  • Labels help categorize campaigns, ad groups, ads, and keywords to streamline workflow.

  • You can programmatically create labels using LabelService and assign them using services like CampaignLabelService.

  • Reports can be filtered and retrieved by label ID using GoogleAdsService queries.

  • Labels can be used in various reports, including those with and without metrics, to find relationships between resources and labels.

Labels let you 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:

This guide focuses on campaigns, but you can use the same approach for ad groups, ads, and keywords. This API also provides CustomerLabelService, which allows manager accounts to assign labels to child accounts.

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 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 a way to identify the set of campaigns for each user.
  • Your app needs to mark the status of certain objects.

Create labels

Create labels with the TextLabel object:

  1. Create a TextLabel instance.
  2. Set a background color for this TextLabel.
  3. Enter text for this TextLabel using the description field.
  4. Wrap the TextLabel in a LabelOperation and send it to LabelService.MutateLabels.

Take note of the new labels' IDs for later queries. The IDs are embedded in the resource_name field in the MutateLabelResults returned in the MutateLabelsResponse.

You can use a GoogleAdsService Search or SearchStream request to retrieve the IDs.

Assign labels

You can assign labels to your campaigns, customers, ad groups, criteria, or ads. Use the Mutate operation in the appropriate service to assign labels.

For example, to assign labels to a campaign, pass one or more CampaignLabelOperation to CampaignLabelService.MutateCampaignLabels. Each CampaignLabelOperation includes a CampaignLabel instance, which contains these fields:

  • label: ID of a label
  • campaign: ID of a campaign

Create a CampaignLabel instance for each label-campaign pair. Wrap it in a CampaignLabelOperation with the create operation and send it to CampaignService.MutateCampaignLabels.

Add campaign labels

Here's a code example showing how to add a campaign label to a list of campaigns:

Java

private void runExample(
    GoogleAdsClient googleAdsClient, long customerId, List<Long> campaignIds, Long labelId) {
  // Gets the resource name of the label to be added across all given campaigns.
  String labelResourceName = ResourceNames.label(customerId, labelId);

  List<CampaignLabelOperation> operations = new ArrayList<>(campaignIds.size());
  // Creates a campaign label operation for each campaign.
  for (Long campaignId : campaignIds) {
    // Gets the resource name of the given campaign.
    String campaignResourceName = ResourceNames.campaign(customerId, campaignId);
    // Creates the campaign label.
    CampaignLabel campaignLabel =
        CampaignLabel.newBuilder()
            .setCampaign(campaignResourceName)
            .setLabel(labelResourceName)
            .build();

    operations.add(CampaignLabelOperation.newBuilder().setCreate(campaignLabel).build());
  }

  try (CampaignLabelServiceClient campaignLabelServiceClient =
      googleAdsClient.getLatestVersion().createCampaignLabelServiceClient()) {
    MutateCampaignLabelsResponse response =
        campaignLabelServiceClient.mutateCampaignLabels(Long.toString(customerId), operations);
    System.out.printf("Added %d campaign labels:%n", response.getResultsCount());
    for (MutateCampaignLabelResult result : response.getResultsList()) {
      System.out.println(result.getResourceName());
    }
  }
}
AddCampaignLabels.java

C#

public void Run(GoogleAdsClient client, long customerId, long[] campaignIds, long labelId)
{
    // Get the CampaignLabelServiceClient.
    CampaignLabelServiceClient campaignLabelService =
        client.GetService(Services.V22.CampaignLabelService);

    // Gets the resource name of the label to be added across all given campaigns.
    string labelResourceName = ResourceNames.Label(customerId, labelId);

    List<CampaignLabelOperation> operations = new List<CampaignLabelOperation>();
    // Creates a campaign label operation for each campaign.
    foreach (long campaignId in campaignIds)
    {
        // Gets the resource name of the given campaign.
        string campaignResourceName = ResourceNames.Campaign(customerId, campaignId);
        // Creates the campaign label.
        CampaignLabel campaignLabel = new CampaignLabel()
        {
            Campaign = campaignResourceName,
            Label = labelResourceName
        };

        operations.Add(new CampaignLabelOperation()
        {
            Create = campaignLabel
        });
    }

    // Send the operation in a mutate request.
    try
    {
        MutateCampaignLabelsResponse response =
            campaignLabelService.MutateCampaignLabels(customerId.ToString(), operations);
        Console.WriteLine($"Added {response.Results} campaign labels:");

        foreach (MutateCampaignLabelResult result in response.Results)
        {
            Console.WriteLine(result.ResourceName);
        }
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}
AddCampaignLabels.cs

PHP

public static function runExample(
    GoogleAdsClient $googleAdsClient,
    int $customerId,
    array $campaignIds,
    int $labelId
) {
    // Gets the resource name of the label to be added across all given campaigns.
    $labelResourceName = ResourceNames::forLabel($customerId, $labelId);

    // Creates a campaign label operation for each campaign.
    $operations = [];
    foreach ($campaignIds as $campaignId) {
        // Creates the campaign label.
        $campaignLabel = new CampaignLabel([
            'campaign' => ResourceNames::forCampaign($customerId, $campaignId),
            'label' => $labelResourceName
        ]);
        $campaignLabelOperation = new CampaignLabelOperation();
        $campaignLabelOperation->setCreate($campaignLabel);
        $operations[] = $campaignLabelOperation;
    }

    // Issues a mutate request to add the labels to the campaigns.
    $campaignLabelServiceClient = $googleAdsClient->getCampaignLabelServiceClient();
    $response = $campaignLabelServiceClient->mutateCampaignLabels(
        MutateCampaignLabelsRequest::build($customerId, $operations)
    );

    printf("Added %d campaign labels:%s", $response->getResults()->count(), PHP_EOL);

    foreach ($response->getResults() as $addedCampaignLabel) {
        /** @var CampaignLabel $addedCampaignLabel */
        printf(
            "New campaign label added with resource name: '%s'.%s",
            $addedCampaignLabel->getResourceName(),
            PHP_EOL
        );
    }
}
AddCampaignLabels.php