adwords4r 18.0.0 → 19.0.0

data/examples/create_all.rb

@@ -1,165 +0,0 @@
-#!/usr/bin/ruby
-#
-# Author:: jeffy@google.com (Jeffrey Posnick)
-#
-# Copyright:: Copyright 2009, 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 code sample illustrates how to create a new campaign, ad group, text ad,
-# keywords, and website criteria, all in one fell swoop.
-
-require 'rubygems'
-gem 'soap4r', '= 1.5.8'
-require 'adwords4r'
-
-
-def main()
-  begin
-    # AdWords::AdWordsCredentials.new will read a credentials file from
-    # ENV['HOME']/adwords.properties when called without parameters.
-    #
-    # Credentials can be either for the production or Sandbox environments.
-    # Production environment credentials overview:
-    # http://www.google.com/apis/adwords/developer/index.html
-    # Sandbox environment credentials overview:
-    # http://www.google.com/apis/adwords/developer/adwords_api_sandbox.html
-    #
-    # Instead of reading them from a file, the credentials can be
-    # specified inline as a hash:
-    #
-    # creds = {
-    #     'developerToken' => 'user@domain.com++USD',
-    #     'useragent' => 'Sample User Agent',
-    #     'password' => 'password',
-    #     'email' => 'user@domain.com',
-    #     'clientEmail' => 'client_1+user@domain.com',
-    #     'applicationToken' => 'IGNORED',
-    #     'environment' => 'SANDBOX',
-    # }
-    # adwords = AdWords::API.new(AdWords::AdWordsCredentials.new(creds))
-    adwords = AdWords::API.new
-
-    # Alternatively, you can create new AdWords::Campaign, AdWords::AdGroup,
-    # etc. objects and set their properties instead of working with hashes.
-    campaign_data = {
-        :name => 'Sample Campaign %s' % Time.new.to_s, # Ensure name is unique.
-        :budgetAmount => 1000000, # 1000000 micros = 1 unit of currency.
-        :budgetPeriod => 'Daily',
-        :languageTargeting => ['en'], # If the default all-language targeting is
-                                      # used then website placements criteria
-                                      # would not be supported.
-        :status => 'Paused', # Pause campaign so that it doesn't actually run.
-        # Default geo and network targeting will be used.
-    }
-
-    campaign_srv = adwords.get_service('Campaign', 13)
-    campaign  = campaign_srv.addCampaign(campaign_data).addCampaignReturn
-    puts 'Campaign id %d was successfully added.' % campaign.id
-
-    ad_group_data = {
-        :name => 'Sample Ad Group %s' % Time.new.to_s, # Ensure name is unique.
-        :keywordMaxCpc => 100000, # 100000 micros = 0.1 unit of currency.
-        :siteMaxCpc => 100000, # 100000 micros = 0.1 unit of currency.
-    }
-
-    ad_group_srv = adwords.get_service('AdGroup', 13)
-    ad_group =
-        ad_group_srv.addAdGroup(campaign.id, ad_group_data).addAdGroupReturn
-    puts 'Ad group id %d was successfully added.' % ad_group.id
-
-    ad_data = {
-        :adGroupId => ad_group.id,
-        :adType => 'TextAd',
-        :headline => 'AdWords API Ruby Library',
-        :description1 => 'Write AdWords API apps in Ruby.',
-        :description2 => 'Use adwords4r!',
-        :destinationUrl => 'http://code.google.com/p/google-api-adwords-ruby/',
-        :displayUrl => 'http://code.google.com/',
-    }
-
-    ad_srv = adwords.get_service('Ad', 13)
-    ad = ad_srv.addAds([ad_data])[0]
-    puts 'Text ad id %d was successfully added.' % ad.id
-
-    keyword_data = {
-        :adGroupId => ad_group.id,
-        :criterionType => 'Keyword',
-        :text => 'adwords4r',
-        :type => 'Broad', # Or 'Phrase' or 'Exact' if desired.
-        # Default ad destination URL and ad group CPC values will be used.
-    }
-
-    website_data = {
-        :adGroupId => ad_group.id,
-        :criterionType => 'Website',
-        :url => 'http://www.ruby-forum.com/', # Target this site for ads.
-        # Default ad destination URL and ad group CPC values will be used.
-    }
-
-    criterion_srv = adwords.get_service('Criterion', 13)
-    criteria = criterion_srv.addCriteria([keyword_data, website_data])
-    criteria.each do |criterion|
-      puts 'Criterion id %d was successfully added.' % criterion.id
-    end
-
-  rescue Errno::ECONNRESET, SOAP::HTTPStreamError, SocketError => e
-    # This exception indicates a connection-level error.
-    # In general, it is likely to be transitory.
-    puts 'Connection Error: %s' % e
-    puts 'Source: %s' % e.backtrace.first
-
-  rescue AdWords::Error::UnknownAPICall => e
-    # This exception is thrown when an unknown SOAP method is invoked.
-    puts e
-    puts 'Source: %s' % e.backtrace.first
-
-  rescue AdWords::Error::ApiError => e
-    # This exception maps to receiving a SOAP Fault back from the service.
-    # The e.soap_faultstring_ex, e.code_ex, and potentially e.trigger_ex
-    # attributes are the most useful, but other attributes may be populated
-    # as well. To display all attributes, the following can be used:
-    #
-    # e.instance_variables.each do |var|
-    #   value = e.instance_variable_get(var)
-    #   if ! value.nil?
-    #     puts '%s => %s' % [var, value]
-    #   end
-    # end
-    puts 'SOAP Error: %s (code: %d)' % [e.soap_faultstring_ex, e.code_ex]
-    puts 'Trigger: %s' % e.trigger_ex unless e.trigger_ex.nil?
-    puts 'Source: %s' % e.backtrace.first
-
-  ensure
-    # Display API unit usage info. This data is stored as a class variable
-    # in the AdWords::API class and accessed via static methods.
-    # total_units() returns a running total of units used in the scope of the
-    # current program. last_units() returns the number used in the last call.
-    puts
-    puts '%d API units consumed total (%d in last call).' %
-        [adwords.total_units, adwords.last_units]
-  end
-end
-
-
-if __FILE__ == $0
-  # The adwords4r library can log all SOAP requests and responses to files.
-  # This is often useful for debugging purposes.
-  # To enable this, set the ADWORDS4R_DEBUG environement variable to 'true'.
-  # This can be done either from your operating system environment or via
-  # code, as done below.
-  ENV['ADWORDS4R_DEBUG'] = 'false'
-
-  main()
-end

data/examples/get_all_ad_params.rb

@@ -1,121 +0,0 @@
-#!/usr/bin/ruby
-#
-# Author:: api.sgomes@gmail.com (Sérgio Gomes)
-#
-# Copyright:: Copyright 2009, 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 ad parameters for an ad
-# group. To create an ad parameter, run set_ad_params.rb.
-
-require 'rubygems'
-gem 'soap4r', '= 1.5.8'
-require 'adwords4r'
-
-def get_all_ad_params()
-  # AdWords::AdWordsCredentials.new will read a credentials file from
-  # ENV['HOME']/adwords.properties when called without parameters.
-  #
-  # Instead of reading them from a file, the credentials can be
-  # specified inline as a hash:
-  #
-  # creds = {
-  #     'developerToken' => 'user@domain.com++USD',
-  #     'useragent' => 'Sample User Agent',
-  #     'password' => 'password',
-  #     'email' => 'user@domain.com',
-  #     'clientEmail' => 'client_1+user@domain.com',
-  #     'applicationToken' => 'IGNORED',
-  #     'environment' => 'SANDBOX',
-  # }
-  # $adwords = AdWords::API.new(AdWords::AdWordsCredentials.new(creds))
-  $adwords = AdWords::API.new
-
-  # Use the latest version for all services
-  latest = AdWords::Service.latest_version
-  ad_param_srv = $adwords.get_service('AdParam', latest)
-
-  # Get all the ad parameters for this ad group
-  # The 'module' method being called here provides a shortcut to the
-  # module containing the classes for this service. This helps us avoid
-  # typing the full class name every time we need to create an object,
-  # e.g. AdWords::V200909::AdParamService::AdParamSelector
-  selector = ad_param_srv.module::AdParamSelector.new
-  ad_group_id = 'INSERT_AD_GROUP_ID_HERE'.to_i
-  selector.adGroupIds = [ad_group_id]
-  response = ad_param_srv.get(selector)
-  if response and response.rval and response.rval.entries
-    ad_params = response.rval.entries
-    puts "Ad group ##{ad_group_id} has #{ad_params.length} ad param(s)."
-    ad_params.each do |ad_param|
-      puts "  Ad param name for criterion ##{ad_param.criterionId} has " +
-           "insertionText \"#{ad_param.insertionText}\" and " +
-           "paramIndex #{ad_param.paramIndex}."
-    end
-  else
-      puts "No ad params found for ad group ##{ad_group_id}."
-  end
-end
-
-if __FILE__ == $0
-  # The adwords4r library can log all SOAP requests and responses to files.
-  # This is often useful for debugging purposes.
-  # To enable this, set the ADWORDS4R_DEBUG environement variable to 'true'.
-  # This can be done either from your operating system environment or via
-  # code, as done below.
-  ENV['ADWORDS4R_DEBUG'] = 'false'
-
-  begin
-    get_all_ad_params()
-
-  rescue Errno::ECONNRESET, SOAP::HTTPStreamError, SocketError => e
-    # This exception indicates a connection-level error.
-    # In general, it is likely to be transitory.
-    puts 'Connection Error: %s' % e
-    puts 'Source: %s' % e.backtrace.first
-
-  rescue AdWords::Error::UnknownAPICall => e
-    # This exception is thrown when an unknown SOAP method is invoked.
-    puts e
-    puts 'Source: %s' % e.backtrace.first
-
-  rescue AdWords::Error::ApiError => e
-    # This exception maps to receiving a SOAP Fault back from the service.
-    # The e.soap_faultstring_ex, e.code_ex, and potentially e.trigger_ex
-    # attributes are the most useful, but other attributes may be populated
-    # as well. To display all attributes, the following can be used:
-    #
-    # e.instance_variables.each do |var|
-    #   value = e.instance_variable_get(var)
-    #   if ! value.nil?
-    #     puts '%s => %s' % [var, value]
-    #   end
-    # end
-    puts 'SOAP Error: %s (code: %d)' % [e.soap_faultstring_ex, e.code_ex]
-    puts 'Trigger: %s' % e.trigger_ex unless e.trigger_ex.nil?
-    puts 'Source: %s' % e.backtrace.first
-
-  ensure
-    if $adwords
-      # Display API unit usage info. This data is stored as a class variable
-      # in the AdWords::API class and accessed via static methods.
-      # total_units() returns a running total of units used in the scope of the
-      # current program. last_units() returns the number used in the last call.
-      puts
-      puts '%d API units consumed total (%d in last call).' %
-          [$adwords.total_units, $adwords.last_units]
-    end
-  end
-end

data/examples/keyword_suggestions.rb

@@ -1,189 +0,0 @@
-#!/usr/bin/ruby
-#
-# Author:: jeffy@google.com (Jeffrey Posnick)
-#
-# Copyright:: Copyright 2009, 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 code sample illustrates how to get keyword variations for seed keyword(s)
-# and then estimate the traffic that the "top" variations might receive.
-
-require 'rubygems'
-gem 'soap4r', '= 1.5.8'
-require 'adwords4r'
-
-
-def main()
-  begin
-    # AdWords::AdWordsCredentials.new will read a credentials file from
-    # ENV['HOME']/adwords.properties when called without parameters.
-    #
-    # Credentials can be either for the production or Sandbox environments.
-    # Production environment credentials overview:
-    # http://www.google.com/apis/adwords/developer/index.html
-    # Sandbox environment credentials overview:
-    # http://www.google.com/apis/adwords/developer/adwords_api_sandbox.html
-    #
-    # Instead of reading them from a file, the credentials can be
-    # specified inline as a hash:
-    #
-    # creds = {
-    #     'developerToken' => 'user@domain.com++USD',
-    #     'useragent' => 'Sample User Agent',
-    #     'password' => 'password',
-    #     'email' => 'user@domain.com',
-    #     'clientEmail' => 'client_1+user@domain.com',
-    #     'applicationToken' => 'IGNORED',
-    #     'environment' => 'SANDBOX',
-    # }
-    # adwords = AdWords::API.new(AdWords::AdWordsCredentials.new(creds))
-    adwords = AdWords::API.new
-
-    kwdtool_srv = adwords.get_service('KeywordTool', 13)
-
-    # Modify the following values to set the seed keywords, language,
-    # country targeting, and synonyms options.
-    keywords = ['new york']
-    languages = %w{en}
-    countries = %w{US}
-    use_synonyms = false
-
-    seed_keywords = []
-    keywords.each do |keyword|
-      # The 'module' method being called here provides a shortcut to the
-      # module containing the classes for this service. This helps us avoid
-      # typing the full class name every time we need to create an object, e.g.
-      # AdWords::V13::KeywordToolService::SeedKeyword
-      # It also makes it easier to migrate code between API versions.
-      seed_keyword = kwdtool_srv.module::SeedKeyword.new
-      seed_keyword.text = keyword
-      seed_keyword.type = 'Broad'  # Or 'Phrase' or 'Exact' if desired.
-      seed_keywords << seed_keyword
-    end
-
-    variations =
-        kwdtool_srv.getKeywordVariations(seed_keywords, use_synonyms, languages,
-                                         countries).getKeywordVariationsReturn
-
-    # Sort the list of variations using the following criteria:
-    #   - treat moreSpecific and additionalToConsider results identically
-    #   - sort in descending value based on lastMonthSearchVolume
-    #   - in case of ties, use avgSearchVolume
-    variation_objects = []
-    unless variations.moreSpecific.nil?
-      variation_objects.concat(variations.moreSpecific)
-    end
-    unless variations.additionalToConsider.nil?
-      variation_objects.concat(variations.additionalToConsider)
-    end
-    variation_objects.sort! do |a, b|
-      if b.avgSearchVolume == a.avgSearchVolume
-        a.lastMonthSearchVolume <=> b.lastMonthSearchVolume
-      else
-        b.avgSearchVolume <=> a.avgSearchVolume
-      end
-    end
-
-    max_estimates = 5
-    keywords_to_estimate = []
-    variation_objects[0..max_estimates - 1].each do |variation_object|
-      keywords_to_estimate << variation_object.text
-    end
-
-    traffic_est_srv = adwords.get_service('TrafficEstimator', 13)
-
-    ad_group_request = traffic_est_srv.module::AdGroupRequest.new
-    ad_group_request.maxCpc = 1000000
-    keywords_to_estimate.each do |keyword_to_estimate|
-      keyword_request = traffic_est_srv.module::KeywordRequest.new
-      keyword_request.text = keyword_to_estimate
-      keyword_request.type = 'Broad'  # Or 'Phrase' or 'Exact' if desired.
-      ad_group_request.keywordRequests << keyword_request
-    end
-
-    geo_targeting = traffic_est_srv.module::GeoTarget.new
-    countryTargets = traffic_est_srv.module::CountryTargets.new
-    countryTargets.countries = countries
-    geo_targeting.countryTargets = countryTargets
-
-    campaign_request = traffic_est_srv.module::CampaignRequest.new
-    campaign_request.adGroupRequests = ad_group_request
-    campaign_request.geoTargeting = geo_targeting
-    campaign_request.languageTargeting = languages
-    campaign_request.networkTargeting = %w{SearchNetwork ContentNetwork}
-
-    campaign_estimate =
-        traffic_est_srv.estimateCampaignList([campaign_request]).first
-    ad_group_estimate = campaign_estimate.adGroupEstimates.first
-    keyword_estimates = ad_group_estimate.keywordEstimates
-    for i in 0..keyword_estimates.length - 1
-      estimate = keyword_estimates[i]
-      text = keywords_to_estimate[i]
-
-      puts "Keyword: %s\tClicks: %f - %f\tCPC: %d - %d\tPosition: %f - %f" %
-          [text, estimate.lowerClicksPerDay, estimate.upperClicksPerDay,
-           estimate.lowerCpc, estimate.upperCpc, estimate.lowerAvgPosition,
-           estimate.upperAvgPosition]
-    end
-
-  rescue Errno::ECONNRESET, SOAP::HTTPStreamError, SocketError => e
-    # This exception indicates a connection-level error.
-    # In general, it is likely to be transitory.
-    puts 'Connection Error: %s' % e
-    puts 'Source: %s' % e.backtrace.first
-
-  rescue AdWords::Error::UnknownAPICall => e
-    # This exception is thrown when an unknown SOAP method is invoked.
-    puts e
-    puts 'Source: %s' % e.backtrace.first
-
-  rescue AdWords::Error::ApiError => e
-    # This exception maps to receiving a SOAP Fault back from the service.
-    # The e.soap_faultstring_ex, e.code_ex, and potentially e.trigger_ex
-    # attributes are the most useful, but other attributes may be populated
-    # as well. To display all attributes, the following can be used:
-    #
-    # e.instance_variables.each do |var|
-    #   value = e.instance_variable_get(var)
-    #   if ! value.nil?
-    #     puts '%s => %s' % [var, value]
-    #   end
-    # end
-    puts 'SOAP Error: %s (code: %d)' % [e.soap_faultstring_ex, e.code_ex]
-    puts 'Trigger: %s' % e.trigger_ex unless e.trigger_ex.nil?
-    puts 'Source: %s' % e.backtrace.first
-
-  ensure
-    # Display API unit usage info. This data is stored as a class variable
-    # in the AdWords::API class and accessed via static methods.
-    # total_units() returns a running total of units used in the scope of the
-    # current program. last_units() returns the number used in the last call.
-    puts
-    puts '%d API units consumed total (%d in last call).' %
-        [adwords.total_units, adwords.last_units]
-  end
-end
-
-
-if __FILE__ == $0
-  # The adwords4r library can log all SOAP requests and responses to files.
-  # This is often useful for debugging purposes.
-  # To enable this, set the ADWORDS4R_DEBUG environement variable to 'true'.
-  # This can be done either from your operating system environment or via
-  # code, as done below.
-  ENV['ADWORDS4R_DEBUG'] = 'false'
-
-  main()
-end