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

#!/usr/bin/env python
#
# Copyright 2016 Google Inc. All Rights Reserved.
#
# 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.

"""This example adds various types of targeting criteria to a given campaign.

To get campaigns, run get_campaigns.py.

The LoadFromStorage method is pulling credentials and properties from a
"googleads.yaml" file. By default, it looks for this file in your home
directory. For more information, see the "Caching authentication information"
section of our README.

"""

from googleads import adwords


CAMPAIGN_ID = 'INSERT_CAMPAIGN_ID_HERE'
# Replace the value below with the 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 None.
LOCATION_FEED_ID = 'INSERT_LOCATION_FEED_ID_HERE'


def main(client, campaign_id, location_feed_id=None):
  # Initialize appropriate service.
  campaign_criterion_service = client.GetService(
      'CampaignCriterionService', version='v201809')

  # Create locations. The IDs can be found in the documentation or retrieved
  # with the LocationCriterionService.
  california = {
      'xsi_type': 'Location',
      'id': '21137'
  }
  mexico = {
      'xsi_type': 'Location',
      'id': '2484'
  }

  # Create languages. The IDs can be found in the documentation or retrieved
  # with the ConstantDataService.
  english = {
      'xsi_type': 'Language',
      'id': '1000'
  }
  spanish = {
      'xsi_type': 'Language',
      'id': '1003'
  }

  # Create a negative campaign criterion operation.
  negative_campaign_criterion_operand = {
      'xsi_type': 'NegativeCampaignCriterion',
      'campaignId': campaign_id,
      'criterion': {
          'xsi_type': 'Keyword',
          'matchType': 'BROAD',
          'text': 'jupiter cruise'
      }
  }
  criteria = [california, mexico, english, spanish]
  if location_feed_id:
      # Distance targeting. Area of 10 miles around targets above.
    criteria.append({
        'xsi_type': 'LocationGroups',
        'feedId': location_feed_id,
        'matchingFunction': {
            'operator': 'IDENTITY',
            'lhsOperand': [{
                'xsi_type': 'LocationExtensionOperand',
                'radius': {
                    'xsi_type': 'ConstantOperand',
                    'type': 'DOUBLE',
                    'unit': 'MILES',
                    'doubleValue': 10
                }
            }]
        }
    })
  # Create operations
  operations = []
  for criterion in criteria:
    operations.append({
        'operator': 'ADD',
        'operand': {
            'campaignId': campaign_id,
            'criterion': criterion
        }
    })
  # Add the negative campaign criterion.
  operations.append({
      'operator': 'ADD',
      'operand': negative_campaign_criterion_operand
  })

  # Make the mutate request.
  result = campaign_criterion_service.mutate(operations)

  # Display the resulting campaign criteria.
  for campaign_criterion in result['value']:
    print('Campaign criterion with campaign id "%s", criterion id "%s", '
          'and type "%s" was added.'
          % (campaign_criterion['campaignId'],
              campaign_criterion['criterion']['id'],
              campaign_criterion['criterion']['type']))

if __name__ == '__main__':
  # Initialize client object.
  adwords_client = adwords.AdWordsClient.LoadFromStorage()

  main(adwords_client, CAMPAIGN_ID, LOCATION_FEED_ID)

Add negative criteria to a customer

#!/usr/bin/env python
#
# Copyright 2017 Google Inc. All Rights Reserved.
#
# 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.

"""This example adds various types of negative criteria to a customer.

These criteria will be applied to all campaigns for the customer.

The LoadFromStorage method is pulling credentials and properties from a
"googleads.yaml" file. By default, it looks for this file in your home
directory. For more information, see the "Caching authentication information"
section of our README.

"""

from googleads import adwords


def main(client):
  # Initialize appropriate service.
  customer_negative_criterion_service = client.GetService(
      'CustomerNegativeCriterionService', version='v201809')

  criteria = [
      # Exclude tragedy & conflict content.
      {
          'xsi_type': 'ContentLabel',
          'contentLabelType': 'TRAGEDY'
      },
      # Exclude a specific placement.
      {
          'xsi_type': 'Placement',
          'url': 'http://www.example.com'
      }
      # 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.
  operations = [{
      'operator': 'ADD',
      'operand': {
          'criterion': criterion
      }
  } for criterion in criteria]

  # Make the mutate request.
  result = customer_negative_criterion_service.mutate(operations)

  # Display the resulting campaign criteria.
  for negative_criterion in result['value']:
    print('Customer negative criterion with criterion ID "%s", and type "%s" '
          'was added.' % (negative_criterion['criterion']['id'],
                          negative_criterion['criterion']['type']))


if __name__ == '__main__':
  # Initialize client object.
  adwords_client = adwords.AdWordsClient.LoadFromStorage()

  main(adwords_client)

Add demographic critera to an ad group

#!/usr/bin/env python
#
# Copyright 2016 Google Inc. All Rights Reserved.
#
# 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.

"""This example adds demographic criteria to an ad group.

To get a list of ad groups, run get_ad_groups.py.

The LoadFromStorage method is pulling credentials and properties from a
"googleads.yaml" file. By default, it looks for this file in your home
directory. For more information, see the "Caching authentication information"
section of our README.

"""

from googleads import adwords


GENDER_MALE = '10'
AGE_RANGE_UNDETERMINED = '503999'

AD_GROUP_ID = 'INSERT_AD_GROUP_ID_HERE'


def main(client, ad_group_id):
  # Initialize appropriate service.
  ad_group_criterion_service = client.GetService(
      'AdGroupCriterionService', version='v201809')

  # Create the ad group criteria.
  ad_group_criteria = [
      # Targeting criterion.
      {
          'xsi_type': 'BiddableAdGroupCriterion',
          'adGroupId': ad_group_id,
          'criterion': {
              'xsi_type': 'Gender',
              # Create gender criteria. The IDs can be found in the
              # documentation:
              # https://developers.google.com/adwords/api/docs/appendix/genders.
              'id': GENDER_MALE
          }
      },
      # Exclusion criterion.
      {
          'xsi_type': 'NegativeAdGroupCriterion',
          'adGroupId': ad_group_id,
          'criterion': {
              'xsi_type': 'AgeRange',
              # Create age range criteria. The IDs can be found in the
              # documentation:
              # https://developers.google.com/adwords/api/docs/appendix/ages.
              'id': AGE_RANGE_UNDETERMINED
          }
      }
  ]

  # Create operations.
  operations = []
  for criterion in ad_group_criteria:
    operations.append({
        'operator': 'ADD',
        'operand': criterion
    })

  response = ad_group_criterion_service.mutate(operations)

  if response and response['value']:
    criteria = response['value']
    for ad_group_criterion in criteria:
      criterion = ad_group_criterion['criterion']
      print('Ad group criterion with ad group ID %s, criterion ID %s and '
            'type "%s" was added.' %
            (ad_group_criterion['adGroupId'], criterion['id'],
             criterion['type']))
  else:
    print('No criteria were returned.')


if __name__ == '__main__':
  # Initialize client object.
  adwords_client = adwords.AdWordsClient.LoadFromStorage()

  main(adwords_client, AD_GROUP_ID)

Get all campaign criteria

#!/usr/bin/env python
#
# Copyright 2016 Google Inc. All Rights Reserved.
#
# 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.

"""This example illustrates how to retrieve all the campaign targets.

To set campaign targets, run add_campaign_targeting_criteria.py.

The LoadFromStorage method is pulling credentials and properties from a
"googleads.yaml" file. By default, it looks for this file in your home
directory. For more information, see the "Caching authentication information"
section of our README.

"""

from googleads import adwords


PAGE_SIZE = 500


def main(client):
  # Initialize appropriate service.
  campaign_criterion_service = client.GetService(
      'CampaignCriterionService', version='v201809')

  # Construct selector and get all campaign targets.
  offset = 0
  selector = {
      'fields': ['CampaignId', 'Id', 'CriteriaType', 'PlatformName',
                 'LanguageName', 'LocationName', 'KeywordText'],
      'predicates': [{
          'field': 'CriteriaType',
          'operator': 'IN',
          'values': ['KEYWORD', 'LANGUAGE', 'LOCATION', 'PLATFORM']
      }],
      'paging': {
          'startIndex': str(offset),
          'numberResults': str(PAGE_SIZE)
      }
  }
  more_pages = True
  while more_pages:
    page = campaign_criterion_service.get(selector)

    # Display results.
    if 'entries' in page:
      for campaign_criterion in page['entries']:
        negative = ''
        if (campaign_criterion['CampaignCriterion.Type']
            == 'NegativeCampaignCriterion'):
          negative = 'Negative '
        criterion = campaign_criterion['criterion']
        criteria = (criterion['text'] if 'text' in criterion else
                    criterion['platformName'] if 'platformName' in criterion
                    else criterion['name'] if 'name' in criterion else
                    criterion['locationName'] if 'locationName' in criterion
                    else None)
        print('%sCampaign Criterion found for Campaign ID %s with type %s and '
              'criteria "%s".' % (negative, campaign_criterion['campaignId'],
                                  criterion['type'], criteria))
    else:
      print('No campaign targets were found.')
    offset += PAGE_SIZE
    selector['paging']['startIndex'] = str(offset)
    more_pages = offset < int(page['totalNumEntries'])


if __name__ == '__main__':
  # Initialize client object.
  adwords_client = adwords.AdWordsClient.LoadFromStorage()

  main(adwords_client)

Get all targetable languages and carriers

#!/usr/bin/env python
#
# Copyright 2016 Google Inc. All Rights Reserved.
#
# 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.

"""Retrieves all languages and carriers available for targeting.

The LoadFromStorage method is pulling credentials and properties from a
"googleads.yaml" file. By default, it looks for this file in your home
directory. For more information, see the "Caching authentication information"
section of our README.

"""

from googleads import adwords


def main(client):
  # Initialize appropriate service.
  constant_data_service = client.GetService(
      'ConstantDataService', version='v201809')

  # Get all languages.
  languages = constant_data_service.getLanguageCriterion()

  # Display results.
  for language in languages:
    print('Language with name "%s" and ID "%s" was found.'
          % (language['name'], language['id']))

  # Get all carriers.
  carriers = constant_data_service.getCarrierCriterion()

  # Display results.
  for carrier in carriers:
    print('Carrier with name "%s", ID "%s", and country code "%s" was '
          'found.' % (
              carrier['name'], carrier['id'],
              getattr(carrier, 'countryCode', 'N/A')))


if __name__ == '__main__':
  # Initialize client object.
  adwords_client = adwords.AdWordsClient.LoadFromStorage()

  main(adwords_client)

Get location criteria by name

#!/usr/bin/env python
#
# Copyright 2016 Google Inc. All Rights Reserved.
#
# 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.

"""This example gets all LocationCriterion.

The LoadFromStorage method is pulling credentials and properties from a
"googleads.yaml" file. By default, it looks for this file in your home
directory. For more information, see the "Caching authentication information"
section of our README.

"""

from googleads import adwords


def GetLocationString(location):
  return '%s (%s)' % (location['locationName'], location['displayType']
                      if 'displayType' in location else None)


def main(client):
  # Initialize appropriate service.
  location_criterion_service = client.GetService(
      'LocationCriterionService', version='v201809')

  location_names = ['Paris', 'Quebec', 'Spain', 'Deutschland']

  # Create the selector.
  selector = {
      'fields': ['Id', 'LocationName', 'DisplayType', 'CanonicalName',
                 'ParentLocations', 'Reach', 'TargetingStatus'],
      'predicates': [{
          'field': 'LocationName',
          'operator': 'IN',
          'values': location_names
      }, {
          'field': 'Locale',
          'operator': 'EQUALS',
          'values': ['en']
      }]
  }

  # Make the get request.
  location_criteria = location_criterion_service.get(selector)

  # Display the resulting location criteria.
  for location_criterion in location_criteria:
    parent_string = ''
    if ('parentLocations' in location_criterion['location']
        and location_criterion['location']['parentLocations']):
      parent_string = ', '.join([GetLocationString(parent)for parent in
                                 location_criterion['location']
                                 ['parentLocations']])
    print('The search term "%s" returned the location "%s" of type "%s"'
          ' with parent locations "%s", reach "%s" and id "%s" (%s)'
          % (location_criterion['searchTerm'],
              location_criterion['location']['locationName'],
              location_criterion['location']['displayType'], parent_string,
              location_criterion['reach']
              if 'reach' in location_criterion else None,
              location_criterion['location']['id'],
              location_criterion['location']['targetingStatus']))


if __name__ == '__main__':
  # Initialize client object.
  adwords_client = adwords.AdWordsClient.LoadFromStorage()

  main(adwords_client)