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 ruby # Encoding: utf-8 # # Copyright:: Copyright 2011, Google Inc. All Rights Reserved. # # License:: 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 campaign. To get # campaigns list, run get_campaigns.rb. require 'adwords_api' def add_campaign_targeting_criteria(campaign_id, location_feed_id = nil) # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml # when called without parameters. adwords = AdwordsApi::Api.new # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in # the configuration file or provide your own logger: # adwords.logger = Logger.new('adwords_xml.log') campaign_criterion_srv = adwords.service(:CampaignCriterionService, API_VERSION) # Create campaign criteria. campaign_criteria = [ # Location criteria. The IDs can be found in the documentation or retrieved # with the LocationCriterionService. {:xsi_type => 'Location', :id => 21137}, # California, USA {:xsi_type => 'Location', :id => 2484}, # Mexico # Language criteria. The IDs can be found in the documentation or retrieved # with the ConstantDataService. {:xsi_type => 'Language', :id => 1000}, # English {:xsi_type => 'Language', :id => 1003}, # Spanish ] # Distance targeting. Area of 10 miles around targets above. unless location_feed_id.nil? campaign_criteria << { :xsi_type => 'LocationGroups', :feed_id => location_feed_id, :matching_function => { :operator => 'IDENTITY', :lhs_operand => [{ :xsi_type => 'LocationExtensionOperand', :radius => { :xsi_type => 'ConstantOperand', :type => 'DOUBLE', :unit => 'MILES', :double_value => 10 } }] } } end # Create operations. operations = campaign_criteria.map do |criterion| {:operator => 'ADD', :operand => { :campaign_id => campaign_id, :criterion => criterion} } end # Add negative campaign criterion. operations << { :operator => 'ADD', :operand => { # The 'xsi_type' field allows you to specify the xsi:type of the object # being created. It's only necessary when you must provide an explicit # type that the client library can't infer. :xsi_type => 'NegativeCampaignCriterion', :campaign_id => campaign_id, :criterion => { :xsi_type => 'Keyword', :text => 'jupiter cruise', :match_type => 'BROAD' } } } response = campaign_criterion_srv.mutate(operations) if response and response[:value] criteria = response[:value] criteria.each do |campaign_criterion| criterion = campaign_criterion[:criterion] puts ("Campaign criterion with campaign ID %d, criterion ID %d and " + "type '%s' was added.") % [campaign_criterion[:campaign_id], criterion[:id], criterion[:criterion_type]] end else puts 'No criteria were returned.' end end if __FILE__ == $0 API_VERSION = :v201809 begin campaign_id = 'INSERT_CAMPAIGN_ID_HERE' # Replace the value below with the ID 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 nil or delete # the variable. location_feed_id = 'INSERT_LOCATION_FEED_ID_HERE' add_campaign_targeting_criteria(campaign_id, location_feed_id) # Authorization error. rescue AdsCommon::Errors::OAuth2VerificationRequired => e puts "Authorization credentials are not valid. Edit adwords_api.yml for " + "OAuth2 client ID and secret and run misc/setup_oauth2.rb example " + "to retrieve and store OAuth2 tokens." puts "See this wiki page for more details:\n\n " + 'https://github.com/googleads/google-api-ads-ruby/wiki/OAuth2' # HTTP errors. rescue AdsCommon::Errors::HttpError => e puts "HTTP Error: %s" % e # API errors. rescue AdwordsApi::Errors::ApiException => e puts "Message: %s" % e.message puts 'Errors:' e.errors.each_with_index do |error, index| puts "\tError [%d]:" % (index + 1) error.each do |field, value| puts "\t\t%s: %s" % [field, value] end end end end
Add negative criteria to a customer
#!/usr/bin/env ruby # Encoding: utf-8 # # Copyright:: Copyright 2017, Google Inc. All Rights Reserved. # # License:: 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. require 'adwords_api' def add_customer_negative_criteria() # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml # when called without parameters. adwords = AdwordsApi::Api.new # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in # the configuration file or provide your own logger: # adwords.logger = Logger.new('adwords_xml.log') customer_negative_criterion_srv = adwords.service( :CustomerNegativeCriterionService, API_VERSION) criteria = [] # Exclude tragedy & conflict content. criteria << { :xsi_type => 'ContentLabel', :content_label_type => 'TRAGEDY' } # Exclude a specific placement. criteria << { :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 = criteria.map do |criterion| { :operator => 'ADD', :operand => { :criterion => criterion } } end # Send the request to add the criteria. result = customer_negative_criterion_srv.mutate(operations) # Display the results. result[:value].each do |negative_criterion| puts ("Customer negative criterion with criterion ID %d and type '%s' " + "was added.") % [negative_criterion[:criterion][:id], negative_criterion[:criterion][:criterion_type]] end end if __FILE__ == $0 API_VERSION = :v201809 begin add_customer_negative_criteria() # Authorization error. rescue AdsCommon::Errors::OAuth2VerificationRequired => e puts "Authorization credentials are not valid. Edit adwords_api.yml for " + "OAuth2 client ID and secret and run misc/setup_oauth2.rb example " + "to retrieve and store OAuth2 tokens." puts "See this wiki page for more details:\n\n " + 'https://github.com/googleads/google-api-ads-ruby/wiki/OAuth2' # HTTP errors. rescue AdsCommon::Errors::HttpError => e puts "HTTP Error: %s" % e # API errors. rescue AdwordsApi::Errors::ApiException => e puts "Message: %s" % e.message puts 'Errors:' e.errors.each_with_index do |error, index| puts "\tError [%d]:" % (index + 1) error.each do |field, value| puts "\t\t%s: %s" % [field, value] end end end end
Add demographic critera to an ad group
#!/usr/bin/env ruby # Encoding: utf-8 # # Copyright:: Copyright 2012, Google Inc. All Rights Reserved. # # License:: 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 ad groups list, # run get_ad_groups.rb. require 'adwords_api' def add_demographic_targeting_criteria(ad_group_id) # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml # when called without parameters. adwords = AdwordsApi::Api.new # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in # the configuration file or provide your own logger: # adwords.logger = Logger.new('adwords_xml.log') ad_group_criterion_srv = adwords.service(:AdGroupCriterionService, API_VERSION) # Create ad group criteria. ad_group_criteria = [ # Targeting criterion. { :xsi_type => 'BiddableAdGroupCriterion', :ad_group_id => ad_group_id, :criterion => { :xsi_type => 'Gender', # See system codes section for IDs: # https://developers.google.com/adwords/api/docs/appendix/genders :id => 11 } }, # Exclusion criterion. { :xsi_type => 'NegativeAdGroupCriterion', :ad_group_id => ad_group_id, :criterion => { :xsi_type => 'AgeRange', # See system codes section for IDs: # https://developers.google.com/adwords/api/docs/appendix/ages :id => 503999 } } ] # Create operations. operations = ad_group_criteria.map do |criterion| {:operator => 'ADD', :operand => criterion} end response = ad_group_criterion_srv.mutate(operations) if response and response[:value] criteria = response[:value] criteria.each do |ad_group_criterion| criterion = ad_group_criterion[:criterion] puts ("Ad group criterion with ad group ID %d, criterion ID %d and " + "type '%s' was added.") % [ad_group_criterion[:ad_group_id], criterion[:id], criterion[:criterion_type]] end else puts 'No criteria were returned.' end end if __FILE__ == $0 API_VERSION = :v201809 begin ad_group_id = 'INSERT_AD_GROUP_ID_HERE' add_demographic_targeting_criteria(ad_group_id) # Authorization error. rescue AdsCommon::Errors::OAuth2VerificationRequired => e puts "Authorization credentials are not valid. Edit adwords_api.yml for " + "OAuth2 client ID and secret and run misc/setup_oauth2.rb example " + "to retrieve and store OAuth2 tokens." puts "See this wiki page for more details:\n\n " + 'https://github.com/googleads/google-api-ads-ruby/wiki/OAuth2' # HTTP errors. rescue AdsCommon::Errors::HttpError => e puts "HTTP Error: %s" % e # API errors. rescue AdwordsApi::Errors::ApiException => e puts "Message: %s" % e.message puts 'Errors:' e.errors.each_with_index do |error, index| puts "\tError [%d]:" % (index + 1) error.each do |field, value| puts "\t\t%s: %s" % [field, value] end end end end
Get all campaign criteria
#!/usr/bin/env ruby # Encoding: utf-8 # # Copyright:: Copyright 2011, Google Inc. All Rights Reserved. # # License:: 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.rb. require 'adwords_api' def get_campaign_targeting_criteria(campaign_id) # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml # when called without parameters. adwords = AdwordsApi::Api.new # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in # the configuration file or provide your own logger: # adwords.logger = Logger.new('adwords_xml.log') campaign_criterion_srv = adwords.service(:CampaignCriterionService, API_VERSION) # Selector to get all the targeting for this campaign. selector = { :fields => ['Id', 'CriteriaType', 'KeywordText'], :predicates => [ {:field => 'CampaignId', :operator => 'EQUALS', :values => [campaign_id]} ], :paging => { :start_index => 0, :number_results => PAGE_SIZE } } # Set initial values. offset, page = 0, {} begin page = campaign_criterion_srv.get(selector) if page[:entries] page[:entries].each do |typed_criterion| negative = typed_criterion[:xsi_type] == 'NegativeCampaignCriterion' ? ' (negative)' : '' criterion = typed_criterion[:criterion] puts ("Campaign criterion%s with ID %d, type '%s' and text '%s'" + " was found.") % [negative, criterion[:id], criterion[:type], criterion[:text]] end # Increment values to request the next page. offset += PAGE_SIZE selector[:paging][:start_index] = offset end end while page[:total_num_entries] > offset if page.include?(:total_num_entries) puts "\tCampaign ID %d has %d criteria." % [campaign_id, page[:total_num_entries]] end end if __FILE__ == $0 API_VERSION = :v201809 PAGE_SIZE = 500 begin # Specify campaign ID to get targeting for. campaign_id = 'INSERT_CAMPAIGN_ID_HERE'.to_i get_campaign_targeting_criteria(campaign_id) # Authorization error. rescue AdsCommon::Errors::OAuth2VerificationRequired => e puts "Authorization credentials are not valid. Edit adwords_api.yml for " + "OAuth2 client ID and secret and run misc/setup_oauth2.rb example " + "to retrieve and store OAuth2 tokens." puts "See this wiki page for more details:\n\n " + 'https://github.com/googleads/google-api-ads-ruby/wiki/OAuth2' # HTTP errors. rescue AdsCommon::Errors::HttpError => e puts "HTTP Error: %s" % e # API errors. rescue AdwordsApi::Errors::ApiException => e puts "Message: %s" % e.message puts 'Errors:' e.errors.each_with_index do |error, index| puts "\tError [%d]:" % (index + 1) error.each do |field, value| puts "\t\t%s: %s" % [field, value] end end end end
Get all targetable languages and carriers
#!/usr/bin/env ruby # Encoding: utf-8 # # Copyright:: Copyright 2011, Google Inc. All Rights Reserved. # # License:: 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 languages and carriers available # for targeting. require 'adwords_api' def get_targetable_languages_and_carriers() # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml # when called without parameters. adwords = AdwordsApi::Api.new # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in # the configuration file or provide your own logger: # adwords.logger = Logger.new('adwords_xml.log') constant_data_srv = adwords.service(:ConstantDataService, API_VERSION) # Get all languages from ConstantDataService. languages = constant_data_srv.get_language_criterion() if languages languages.each do |language| puts "Language name is '%s', ID is %d and code is '%s'." % [language[:name], language[:id], language[:code]] end else puts 'No languages were found.' end # Get all carriers from ConstantDataService. carriers = constant_data_srv.get_carrier_criterion() if carriers carriers.each do |carrier| puts "Carrier name is '%s', ID is %d and country code is '%s'." % [carrier[:name], carrier[:id], carrier[:country_code]] end else puts 'No carriers were retrieved.' end end if __FILE__ == $0 API_VERSION = :v201809 begin get_targetable_languages_and_carriers() # Authorization error. rescue AdsCommon::Errors::OAuth2VerificationRequired => e puts "Authorization credentials are not valid. Edit adwords_api.yml for " + "OAuth2 client ID and secret and run misc/setup_oauth2.rb example " + "to retrieve and store OAuth2 tokens." puts "See this wiki page for more details:\n\n " + 'https://github.com/googleads/google-api-ads-ruby/wiki/OAuth2' # HTTP errors. rescue AdsCommon::Errors::HttpError => e puts "HTTP Error: %s" % e # API errors. rescue AdwordsApi::Errors::ApiException => e puts "Message: %s" % e.message puts 'Errors:' e.errors.each_with_index do |error, index| puts "\tError [%d]:" % (index + 1) error.each do |field, value| puts "\t\t%s: %s" % [field, value] end end end end
Get location criteria by name
#!/usr/bin/env ruby # Encoding: utf-8 # # Copyright:: Copyright 2011, Google Inc. All Rights Reserved. # # License:: 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 location criteria by name. require 'adwords_api' def lookup_location() # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml # when called without parameters. adwords = AdwordsApi::Api.new # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in # the configuration file or provide your own logger: # adwords.logger = Logger.new('adwords_xml.log') location_criterion_srv = adwords.service(:LocationCriterionService, API_VERSION) # List of locations to look up. location_names = ['Paris', 'Quebec', 'Spain', 'Deutschland'] # Locale to retrieve names in. locale = 'en' # Get the criteria by names. selector = { :fields => ['Id', 'LocationName', 'CanonicalName', 'DisplayType', 'ParentLocations', 'Reach', 'TargetingStatus'], :predicates => [ # Location names must match exactly, only EQUALS and IN are supported. {:field => 'LocationName', :operator => 'IN', :values => location_names}, # Set the locale of the returned location names. {:field => 'Locale', :operator => 'EQUALS', :values => [locale]} ] } criteria = location_criterion_srv.get(selector) if criteria criteria.each do |criterion| # Extract all parent location names as one comma-separated string. parent_location = if criterion[:location][:parent_locations] and !criterion[:location][:parent_locations].empty? locations_array = criterion[:location][:parent_locations].map do |loc| loc[:location_name] end locations_array.join(', ') else 'N/A' end puts ("The search term '%s' returned the location '%s' of type '%s' " + "with ID %d, parent locations '%s' and reach %d (%s)") % [criterion[:search_term], criterion[:location][:location_name], criterion[:location][:criterion_type], criterion[:location][:id], parent_location, criterion[:reach], criterion[:location][:targeting_status]] end else puts 'No criteria were returned.' end end if __FILE__ == $0 API_VERSION = :v201809 begin lookup_location() # Authorization error. rescue AdsCommon::Errors::OAuth2VerificationRequired => e puts "Authorization credentials are not valid. Edit adwords_api.yml for " + "OAuth2 client ID and secret and run misc/setup_oauth2.rb example " + "to retrieve and store OAuth2 tokens." puts "See this wiki page for more details:\n\n " + 'https://github.com/googleads/google-api-ads-ruby/wiki/OAuth2' # HTTP errors. rescue AdsCommon::Errors::HttpError => e puts "HTTP Error: %s" % e # API errors. rescue AdwordsApi::Errors::ApiException => e puts "Message: %s" % e.message puts 'Errors:' e.errors.each_with_index do |error, index| puts "\tError [%d]:" % (index + 1) error.each do |field, value| puts "\t\t%s: %s" % [field, value] end end end end