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='v201710')

  # 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 demographic targeting 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='v201710')

  # 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 targeting 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='v201710')

  # 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='v201710')

  # 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='v201710')

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

  # 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)

Send feedback about...

AdWords API
AdWords API
Need help? Visit our support page.