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

The AdWords API will sunset on April 27, 2022. Migrate to the Google Ads API to take advantage of the latest Google Ads features.

Targeting Samples

The code samples below provide examples of common targeting functions using the AdWords API. Client Library.

Add targeting criteria to a campaign

// Copyright 2018 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

using Google.Api.Ads.AdWords.Lib;
using Google.Api.Ads.AdWords.v201809;

using System;
using System.Collections.Generic;

namespace Google.Api.Ads.AdWords.Examples.CSharp.v201809
{
    /// <summary>
    /// This code example adds various types of targeting criteria to a campaign.
    /// To get a list of campaigns, run GetCampaigns.cs.
    /// </summary>
    public class AddCampaignTargetingCriteria : ExampleBase
    {
        /// <summary>
        /// Main method, to run this code example as a standalone application.
        /// </summary>
        /// <param name="args">The command line arguments.</param>
        public static void Main(string[] args)
        {
            AddCampaignTargetingCriteria codeExample = new AddCampaignTargetingCriteria();
            Console.WriteLine(codeExample.Description);
            try
            {
                long campaignId = long.Parse("INSERT_CAMPAIGN_ID_HERE");
                string feedIdText = "INSERT_LOCATION_FEED_ID_HERE";

                long? feedId = null;
                long temp;

                if (long.TryParse(feedIdText, out temp))
                {
                    feedId = temp;
                }

                codeExample.Run(new AdWordsUser(), campaignId, feedId);
            }
            catch (Exception e)
            {
                Console.WriteLine("An exception occurred while running this code example. {0}",
                    ExampleUtilities.FormatException(e));
            }
        }

        /// <summary>
        /// Returns a description about the code example.
        /// </summary>
        public override string Description
        {
            get
            {
                return "This code example adds various types of targeting criteria to a " +
                    "campaign. To get a list of campaigns, run GetCampaigns.cs.";
            }
        }

        /// <summary>
        /// Runs the code example.
        /// </summary>
        /// <param name="user">The AdWords user.</param>
        /// <param name="campaignId">Id of the campaign to which targeting criteria
        /// are added.</param>
        /// <param name="feedId">ID of a feed that has been configured for location
        /// targeting, meaning it has an ENABLED FeedMapping with criterionType of
        /// 77. Feeds linked to a GMB account automatically have this FeedMapping.
        /// If you don't have such a feed, set this value to null.</param>
        public void Run(AdWordsUser user, long campaignId, long? feedId)
        {
            using (CampaignCriterionService campaignCriterionService =
                (CampaignCriterionService) user.GetService(AdWordsService.v201809
                    .CampaignCriterionService))
            {
                // Create locations. The IDs can be found in the documentation or
                // retrieved with the LocationCriterionService.
                Location california = new Location()
                {
                    id = 21137L
                };

                Location mexico = new Location()
                {
                    id = 2484L
                };

                // Create languages. The IDs can be found in the documentation or
                // retrieved with the ConstantDataService.
                Language english = new Language()
                {
                    id = 1000L
                };

                Language spanish = new Language()
                {
                    id = 1003L
                };

                List<Criterion> criteria = new List<Criterion>()
                {
                    california,
                    mexico,
                    english,
                    spanish
                };

                // Distance targeting. Area of 10 miles around the locations in the location feed.
                if (feedId != null)
                {
                    LocationGroups radiusLocationGroup = new LocationGroups()
                    {
                        feedId = feedId.Value,
                        matchingFunction = new Function()
                        {
                            @operator = FunctionOperator.IDENTITY,
                            lhsOperand = new FunctionArgumentOperand[]
                            {
                                new LocationExtensionOperand()
                                {
                                    radius = new ConstantOperand()
                                    {
                                        type = ConstantOperandConstantType.DOUBLE,
                                        unit = ConstantOperandUnit.MILES,
                                        doubleValue = 10
                                    }
                                }
                            }
                        }
                    };

                    criteria.Add(radiusLocationGroup);
                }

                // Create operations to add each of the criteria above.
                List<CampaignCriterionOperation>
                    operations = new List<CampaignCriterionOperation>();
                foreach (Criterion criterion in criteria)
                {
                    CampaignCriterionOperation operation = new CampaignCriterionOperation()
                    {
                        operand = new CampaignCriterion()
                        {
                            campaignId = campaignId,
                            criterion = criterion
                        },
                        @operator = Operator.ADD
                    };

                    operations.Add(operation);
                }

                // Add a negative campaign criterion.

                CampaignCriterion negativeCriterion = new NegativeCampaignCriterion()
                {
                    campaignId = campaignId,
                    criterion = new Keyword()
                    {
                        text = "jupiter cruise",
                        matchType = KeywordMatchType.BROAD
                    }
                };

                CampaignCriterionOperation negativeCriterionOperation =
                    new CampaignCriterionOperation()
                    {
                        operand = negativeCriterion,
                        @operator = Operator.ADD
                    };

                operations.Add(negativeCriterionOperation);

                try
                {
                    // Set the campaign targets.
                    CampaignCriterionReturnValue retVal =
                        campaignCriterionService.mutate(operations.ToArray());

                    if (retVal != null && retVal.value != null)
                    {
                        // Display campaign targets.
                        foreach (CampaignCriterion criterion in retVal.value)
                        {
                            Console.WriteLine(
                                "Campaign criteria of type '{0}' was set to campaign with" +
                                " id = '{1}'.", criterion.criterion.CriterionType,
                                criterion.campaignId);
                        }
                    }
                }
                catch (Exception e)
                {
                    throw new System.ApplicationException("Failed to set Campaign criteria.", e);
                }
            }
        }
    }
}

Add negative criteria to a customer

// Copyright 2018 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

using Google.Api.Ads.AdWords.Lib;
using Google.Api.Ads.AdWords.v201809;

using System;
using System.Collections.Generic;

namespace Google.Api.Ads.AdWords.Examples.CSharp.v201809
{
    /// <summary>
    /// This code example adds various types of negative criteria to a customer. These criteria
    /// will be applied to all campaigns for the customer.
    /// </summary>
    public class AddCustomerNegativeCriteria : ExampleBase
    {
        /// <summary>
        /// Main method, to run this code example as a standalone application.
        /// </summary>
        /// <param name="args">The command line arguments.</param>
        public static void Main(string[] args)
        {
            AddCustomerNegativeCriteria codeExample = new AddCustomerNegativeCriteria();
            Console.WriteLine(codeExample.Description);
            try
            {
                codeExample.Run(new AdWordsUser());
            }
            catch (Exception e)
            {
                Console.WriteLine("An exception occurred while running this code example. {0}",
                    ExampleUtilities.FormatException(e));
            }
        }

        /// <summary>
        /// Returns a description about the code example.
        /// </summary>
        public override string Description
        {
            get
            {
                return "This code example adds various types of negative criteria to a customer. " +
                    "These criteria will be applied to all campaigns for the customer.";
            }
        }

        /// <summary>
        /// Runs the code example.
        /// </summary>
        /// <param name="user">The AdWords user.</param>
        public void Run(AdWordsUser user)
        {
            using (CustomerNegativeCriterionService customerNegativeCriterionService =
                (CustomerNegativeCriterionService) user.GetService(AdWordsService.v201809
                    .CustomerNegativeCriterionService))
            {
                List<Criterion> criteria = new List<Criterion>();

                // Exclude tragedy & conflict content.
                ContentLabel tragedyContentLabel = new ContentLabel
                {
                    contentLabelType = ContentLabelType.TRAGEDY
                };
                criteria.Add(tragedyContentLabel);

                // Exclude a specific placement.
                Placement placement = new Placement
                {
                    url = "http://www.example.com"
                };
                criteria.Add(placement);

                // Additional criteria types are available for this service. See the types listed
                // under Criterion here:
                // https://developers.google.com/adwords/api/docs/reference/latest/CustomerNegativeCriterionService.Criterion

                // Create operations to add each of the criteria above.
                List<CustomerNegativeCriterionOperation> operations =
                    new List<CustomerNegativeCriterionOperation>();
                foreach (Criterion criterion in criteria)
                {
                    CustomerNegativeCriterion negativeCriterion = new CustomerNegativeCriterion
                    {
                        criterion = criterion
                    };
                    CustomerNegativeCriterionOperation operation =
                        new CustomerNegativeCriterionOperation
                        {
                            @operator = Operator.ADD,
                            operand = negativeCriterion
                        };
                    operations.Add(operation);
                }

                try
                {
                    // Send the request to add the criteria.
                    CustomerNegativeCriterionReturnValue result =
                        customerNegativeCriterionService.mutate(operations.ToArray());

                    // Display the results.
                    foreach (CustomerNegativeCriterion negativeCriterion in result.value)
                    {
                        Console.WriteLine(
                            "Customer negative criterion with criterion ID {0} and type '{1}' " +
                            "was added.", negativeCriterion.criterion.id,
                            negativeCriterion.criterion.type);
                    }
                }
                catch (Exception e)
                {
                    throw new System.ApplicationException(
                        "Failed to set customer negative criteria.", e);
                }
            }

        }
    }
}

Get all campaign criteria

// Copyright 2018 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

using Google.Api.Ads.AdWords.Lib;
using Google.Api.Ads.AdWords.v201809;

using System;

namespace Google.Api.Ads.AdWords.Examples.CSharp.v201809
{
    /// <summary>
    /// This code example gets all targeting criteria for a campaign. To set
    /// campaign targeting criteria, run AddCampaignTargetingCriteria.cs. To get
    /// campaigns, run GetCampaigns.cs.
    /// </summary>
    public class GetCampaignTargetingCriteria : ExampleBase
    {
        /// <summary>
        /// Main method, to run this code example as a standalone application.
        /// </summary>
        /// <param name="args">The command line arguments.</param>
        public static void Main(string[] args)
        {
            GetCampaignTargetingCriteria codeExample = new GetCampaignTargetingCriteria();
            Console.WriteLine(codeExample.Description);
            try
            {
                long campaignId = long.Parse("INSERT_CAMPAIGN_ID_HERE");
                codeExample.Run(new AdWordsUser(), campaignId);
            }
            catch (Exception e)
            {
                Console.WriteLine("An exception occurred while running this code example. {0}",
                    ExampleUtilities.FormatException(e));
            }
        }

        /// <summary>
        /// Returns a description about the code example.
        /// </summary>
        public override string Description
        {
            get
            {
                return "This code example gets all targeting criteria for a campaign. To set " +
                    "campaign targeting criteria, run AddCampaignTargetingCriteria.cs. To get " +
                    "campaigns, run GetCampaigns.cs.";
            }
        }

        /// <summary>
        /// Runs the code example.
        /// </summary>
        /// <param name="user">The AdWords user.</param>
        /// <param name="campaignId">Id of the campaign from which targeting
        /// criteria are retrieved.</param>
        public void Run(AdWordsUser user, long campaignId)
        {
            using (CampaignCriterionService campaignCriterionService =
                (CampaignCriterionService) user.GetService(AdWordsService.v201809
                    .CampaignCriterionService))
            {
                // Create the selector.
                Selector selector = new Selector()
                {
                    fields = new string[]
                    {
                        Criterion.Fields.Id,
                        Criterion.Fields.CriteriaType,
                        CampaignCriterion.Fields.CampaignId
                    },
                    predicates = new Predicate[]
                    {
                        Predicate.Equals(CampaignCriterion.Fields.CampaignId, campaignId)
                    },
                    paging = Paging.Default
                };

                CampaignCriterionPage page = new CampaignCriterionPage();

                try
                {
                    do
                    {
                        // Get all campaign targets.
                        page = campaignCriterionService.get(selector);

                        // Display the results.
                        if (page != null && page.entries != null)
                        {
                            int i = selector.paging.startIndex;
                            foreach (CampaignCriterion campaignCriterion in page.entries)
                            {
                                string negative = (campaignCriterion is NegativeCampaignCriterion)
                                    ? "Negative "
                                    : "";
                                Console.WriteLine(
                                    "{0}) {1}Campaign criterion with id = '{2}' and Type = {3} " +
                                    "was found for campaign id '{4}'", i + 1, negative,
                                    campaignCriterion.criterion.id,
                                    campaignCriterion.criterion.type, campaignCriterion.campaignId);
                                i++;
                            }
                        }

                        selector.paging.IncreaseOffset();
                    } while (selector.paging.startIndex < page.totalNumEntries);

                    Console.WriteLine("Number of campaign targeting criteria found: {0}",
                        page.totalNumEntries);
                }
                catch (Exception e)
                {
                    throw new System.ApplicationException(
                        "Failed to get campaign targeting criteria.", e);
                }
            }
        }
    }
}

Get all targetable languages and carriers

// Copyright 2018 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

using Google.Api.Ads.AdWords.Lib;
using Google.Api.Ads.AdWords.v201809;

using System;

namespace Google.Api.Ads.AdWords.Examples.CSharp.v201809
{
    /// <summary>
    /// This code example illustrates how to retrieve all carriers and languages
    /// available for targeting.
    /// </summary>
    public class GetTargetableLanguagesAndCarriers : ExampleBase
    {
        /// <summary>
        /// Main method, to run this code example as a standalone application.
        /// </summary>
        /// <param name="args">The command line arguments.</param>
        public static void Main(string[] args)
        {
            GetTargetableLanguagesAndCarriers codeExample = new GetTargetableLanguagesAndCarriers();
            Console.WriteLine(codeExample.Description);
            try
            {
                codeExample.Run(new AdWordsUser());
            }
            catch (Exception e)
            {
                Console.WriteLine("An exception occurred while running this code example. {0}",
                    ExampleUtilities.FormatException(e));
            }
        }

        /// <summary>
        /// Returns a description about the code example.
        /// </summary>
        public override string Description
        {
            get
            {
                return "This code example illustrates how to retrieve all carriers and languages " +
                    "available for targeting.";
            }
        }

        /// <summary>
        /// Runs the code example.
        /// </summary>
        /// <param name="user">The AdWords user.</param>
        public void Run(AdWordsUser user)
        {
            using (ConstantDataService constantDataService =
                (ConstantDataService) user.GetService(AdWordsService.v201809.ConstantDataService))
            {
                try
                {
                    // Get all carriers.
                    Carrier[] carriers = constantDataService.getCarrierCriterion();

                    // Display the results.
                    if (carriers != null)
                    {
                        foreach (Carrier carrier in carriers)
                        {
                            Console.WriteLine(
                                "Carrier name is '{0}', ID is {1} and country code is '{2}'.",
                                carrier.name, carrier.id, carrier.countryCode);
                        }
                    }
                    else
                    {
                        Console.WriteLine("No carriers were retrieved.");
                    }

                    // Get all languages.
                    Language[] languages = constantDataService.getLanguageCriterion();

                    // Display the results.
                    if (languages != null)
                    {
                        foreach (Language language in languages)
                        {
                            Console.WriteLine(
                                "Language name is '{0}', ID is {1} and code is '{2}'.",
                                language.name, language.id, language.code);
                        }
                    }
                    else
                    {
                        Console.WriteLine("No languages were found.");
                    }
                }
                catch (Exception e)
                {
                    throw new System.ApplicationException(
                        "Failed to get targetable carriers and languages.", e);
                }
            }
        }
    }
}

Get location criteria by name

// Copyright 2018 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

using Google.Api.Ads.AdWords.Lib;
using Google.Api.Ads.AdWords.v201809;

using System;
using System.Collections.Generic;

namespace Google.Api.Ads.AdWords.Examples.CSharp.v201809
{
    /// <summary>
    /// This code example gets location criteria by name.
    /// </summary>
    public class LookupLocation : ExampleBase
    {
        /// <summary>
        /// Main method, to run this code example as a standalone application.
        /// </summary>
        /// <param name="args">The command line arguments.</param>
        public static void Main(string[] args)
        {
            LookupLocation codeExample = new LookupLocation();
            Console.WriteLine(codeExample.Description);
            try
            {
                codeExample.Run(new AdWordsUser());
            }
            catch (Exception e)
            {
                Console.WriteLine("An exception occurred while running this code example. {0}",
                    ExampleUtilities.FormatException(e));
            }
        }

        /// <summary>
        /// Returns a description about the code example.
        /// </summary>
        public override string Description
        {
            get { return "This code example gets location criteria by name."; }
        }

        /// <summary>
        /// Runs the code example.
        /// </summary>
        /// <param name="user">The AdWords user.</param>
        public void Run(AdWordsUser user)
        {
            using (LocationCriterionService locationCriterionService =
                (LocationCriterionService) user.GetService(AdWordsService.v201809
                    .LocationCriterionService))
            {
                string[] locationNames = new string[]
                {
                    "Paris",
                    "Quebec",
                    "Spain",
                    "Deutschland"
                };

                Selector selector = new Selector()
                {
                    fields = new string[]
                    {
                        Location.Fields.Id,
                        Location.Fields.LocationName,
                        LocationCriterion.Fields.CanonicalName,
                        Location.Fields.DisplayType,
                        Location.Fields.ParentLocations,
                        LocationCriterion.Fields.Reach,
                        Location.Fields.TargetingStatus
                    },

                    predicates = new Predicate[]
                    {
                        // Location names must match exactly, only EQUALS and IN are supported.
                        Predicate.In(Location.Fields.LocationName, locationNames),

                        // Set the locale of the returned location names.
                        Predicate.Equals(LocationCriterion.Fields.Locale, "en")
                    }
                };

                try
                {
                    // Make the get request.
                    LocationCriterion[] locationCriteria = locationCriterionService.get(selector);

                    // Display the resulting location criteria.
                    foreach (LocationCriterion locationCriterion in locationCriteria)
                    {
                        string parentLocations = "N/A";

                        if (locationCriterion.location != null &&
                            locationCriterion.location.parentLocations != null)
                        {
                            List<string> parentLocationList = new List<string>();
                            foreach (Location location in locationCriterion.location.parentLocations
                            )
                            {
                                parentLocationList.Add(GetLocationString(location));
                            }

                            parentLocations = string.Join(", ", parentLocationList);
                        }

                        Console.WriteLine(
                            "The search term '{0}' returned the location '{1}' of type '{2}' " +
                            "with parent locations '{3}',  reach '{4}' and targeting status '{5}.",
                            locationCriterion.searchTerm, locationCriterion.location.locationName,
                            locationCriterion.location.displayType, parentLocations,
                            locationCriterion.reach, locationCriterion.location.targetingStatus);
                    }
                }
                catch (Exception e)
                {
                    throw new System.ApplicationException("Failed to get location criteria.", e);
                }
            }
        }

        /// <summary>
        /// Gets a string representation for a location.
        /// </summary>
        /// <param name="location">The location</param>
        /// <returns>The string representation</returns>
        public string GetLocationString(Location location)
        {
            return string.Format("{0} ({1})", location.locationName, location.displayType);
        }
    }
}