adwords4r 13.0.1 → 15.0.1

data/examples/create_all.rb

@@ -1,6 +1,6 @@
 #!/usr/bin/ruby
 #
-# Copyright 2008, Google Inc. All Rights Reserved.
+# Copyright 2009, 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.
@@ -18,7 +18,7 @@
 # keywords, and website criteria, all in one fell swoop.
 
 require 'rubygems'
-gem 'soap4r', '>= 1.5.8'
+gem 'soap4r', '= 1.5.8'
 require 'adwords4r'
 
 
@@ -38,72 +38,76 @@ def main()
     # 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',
-    #   'alternateUrl' => 'https://sandbox.google.com/api/adwords/v13/',
+    #     'developerToken' => 'user@domain.com++USD',
+    #     'useragent' => 'Sample User Agent',
+    #     'password' => 'password',
+    #     'email' => 'user@domain.com',
+    #     'clientEmail' => 'client_1+user@domain.com',
+    #     'applicationToken' => 'IGNORED',
+    #     'alternateUrl' => 'https://sandbox.google.com/api/adwords/v13/',
     # }
-    # adwords = AdWords::API.new(AdWords::AdWordsCredentials.new(creds), 13)
-
+    # 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 the campaign so that it doesn't actually run.
-      # Default geo and network targeting will be used.
+        :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  = adwords.addCampaign(campaign_data).addCampaignReturn
+    campaign_srv = adwords.get_service(13, 'Campaign')
+    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.
+        :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 = adwords.addAdGroup(campaign.id, ad_group_data).addAdGroupReturn
+    ad_group_srv = adwords.get_service(13, 'AdGroup')
+    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/',
+        :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 = adwords.addAds([ad_data])[0]
+    ad_srv = adwords.get_service(13, 'Ad')
+    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.
+        :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.
+        :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.
     }
 
-    criteria = adwords.addCriteria([keyword_data, website_data])
+    criterion_srv = adwords.get_service(13, 'Criterion')
+    criteria = criterion_srv.addCriteria([keyword_data, website_data])
     criteria.each do |criterion|
       puts 'Criterion id %d was successfully added.' % criterion.id
     end
@@ -111,16 +115,14 @@ def main()
   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
@@ -133,7 +135,6 @@ def main()
     #     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
@@ -141,13 +142,11 @@ def main()
   ensure
     # Display API unit usage info. This data is stored as a class variable
     # in the AdWords::API class and accessed via static methods.
-    # AdWords::API.get_total_units() returns a running total of units used in
-    # the scope of the current program.
-    # AdWords::API.get_last_units() returns the number used in the last call.
-
+    # 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::API.get_total_units(), AdWords::API.get_last_units()]
+        [adwords.total_units, adwords.last_units]
   end
 end
 
@@ -158,7 +157,6 @@ if __FILE__ == $0
   # To enable this, set the ADWORDS4R_DEBUG environement varaible to 'true'.
   # This can be done either from your operating system environment or via
   # code, as done below.
-
   ENV['ADWORDS4R_DEBUG'] = 'false'
 
   main()

data/examples/create_all_v200902.rb

@@ -0,0 +1,204 @@
+#!/usr/bin/ruby
+#
+# Copyright 2009, 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 code sample illustrates how to create a new campaign, ad group, text ad,
+# keywords, and website criteria, all in one fell swoop, in the v200902 sandbox.
+
+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.
+    # The latest versioned release of the API will be assumed.
+    #
+    # In this case, we'll assume v200902 sandbox credentials, so only the
+    # email, password and clientEmail fields are used.
+    # v2009 Sandbox environment credentials overview:
+    # http://code.google.com/apis/adwords/v2009/docs/headers.html
+    #
+    # Instead of reading them from a file, the credentials can be
+    # specified inline as a hash:
+    #
+    # creds = {
+    #     'email' => 'user@domain.com',
+    #     'password' => 'password',
+    #     'clientEmail' => 'client_1+user@domain.com'
+    # }
+    # adwords = AdWords::API.new(AdWords::AdWordsCredentials.new(creds))
+    adwords = AdWords::API.new
+
+    campaign_srv = adwords.get_service(200902, 'Campaign')
+    ad_group_srv = adwords.get_service(200902, 'AdGroup')
+    ad_group_ad_srv = adwords.get_service(200902, 'AdGroupAd')
+    ad_group_criterion_srv = adwords.get_service(200902, 'AdGroupCriterion')
+
+    # You can create the required items either via hashes or as new Campaign,
+    # AdGroup, etc. objects and set their properties. You can even mix both
+    # approaches, as is done below.
+
+    # Prepare for adding campaign.
+    operation = {
+      :operand => {
+        :name => 'Sample Campaign - %s' % Time.new,
+        :status => 'ACTIVE',
+        :biddingStrategy => AdWords::V200902::CampaignService::ManualCPC.new,
+        :budget => {
+          :period => 'DAILY',
+          :amount => {
+            :currencyCode => 'EUR',
+            :microAmount => 50000000
+          },
+          :deliveryMethod => 'STANDARD'
+        }
+      },
+      :operator => 'ADD'
+    }
+    # Add campaign.
+    response = campaign_srv.mutate([operation])
+    campaign = response.rval.value.first
+    puts 'Campaign id %d was successfully added.' % campaign.id.id
+
+    # Prepare for adding ad group.
+    bids = AdWords::V200902::AdGroupService::ManualCPCAdGroupBids.new
+    keyword_max_cpc = {
+      :amount => {
+        :currencyCode => 'USD',
+        :microAmount => 10000000
+      }
+    }
+    bids.keywordMaxCpc = keyword_max_cpc
+    operation = {
+      :operand => {
+        :name => 'Sample Ad Group - %s' % Time.new,
+        :status => 'ENABLED',
+        :campaignId => {
+          :id => campaign.id.id
+        },
+        :bids => bids,
+      },
+      :operator => 'ADD'
+    }
+    # Add ad group.
+    response = ad_group_srv.mutate([operation])
+    ad_group = response.rval.value.first
+    puts 'Ad group id %d was successfully added.' % ad_group.id.id
+
+    # Prepare for adding ad.
+    text_ad = AdWords::V200902::AdGroupAdService::TextAd.new
+    text_ad.url = 'http://www.example.com'
+    text_ad.displayUrl = 'www.example.com'
+    text_ad.headline = 'Luxury Cruise to Mars'
+    text_ad.description1 = 'Visit the Red Planet in style.'
+    text_ad.description2 = 'Low-gravity fun for everyone!'
+    operation = {
+      :operand => {
+        :adGroupId => {
+          :id => ad_group.id.id
+        },
+        :ad => text_ad
+      },
+      :operator => 'ADD'
+    }
+    # Add ad.
+    response = ad_group_ad_srv.mutate([operation])
+    ad = response.rval.value.first.ad
+    puts 'Text ad id %d was successfully added.' % ad.id.id
+
+    # Prepare for adding keyword.
+    kwd_operation =
+        AdWords::V200902::AdGroupCriterionService::AdGroupCriterionOperation.new
+    kwd_operand =
+        AdWords::V200902::AdGroupCriterionService::BiddableAdGroupCriterion.new
+    kwd_operand.adGroupId = { :id => ad_group.id.id }
+    keyword = AdWords::V200902::AdGroupCriterionService::Keyword.new
+    keyword.matchType = 'BROAD'
+    keyword.text = 'mars cruise'
+    kwd_operand.criterion = keyword
+    kwd_operation.operand = kwd_operand
+    kwd_operation.operator = 'ADD'
+    kwd_operation.exemptionRequests = []
+    # Prepare for adding placement.
+    plc_operation =
+        AdWords::V200902::AdGroupCriterionService::AdGroupCriterionOperation.new
+    plc_operand =
+        AdWords::V200902::AdGroupCriterionService::BiddableAdGroupCriterion.new
+    plc_operand.adGroupId = { :id => ad_group.id.id }
+    placement = AdWords::V200902::AdGroupCriterionService::Placement.new
+    placement.url = 'http://www.ruby-forum.com/'
+    plc_operand.criterion = placement
+    plc_operation.operand = plc_operand
+    plc_operation.operator = 'ADD'
+    plc_operation.exemptionRequests = []
+    # Add both criteria.
+    response = ad_group_criterion_srv.mutate([kwd_operation, plc_operation])
+    criteria = response.rval.value
+    criteria.each do |criterion|
+      puts 'Criterion id %d was successfully added.' % criterion.criterion.id.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 varaible 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/keyword_suggestions.rb

@@ -1,6 +1,6 @@
 #!/usr/bin/ruby
 #
-# Copyright 2008, Google Inc. All Rights Reserved.
+# Copyright 2009, 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.
@@ -18,7 +18,7 @@
 # and then estimate the traffic that the "top" variations might receive.
 
 require 'rubygems'
-gem 'soap4r', '>= 1.5.8'
+gem 'soap4r', '= 1.5.8'
 require 'adwords4r'
 
 
@@ -38,21 +38,19 @@ def main()
     # 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',
-    #   'alternateUrl' => 'https://sandbox.google.com/api/adwords/v13/',
+    #     'developerToken' => 'user@domain.com++USD',
+    #     'useragent' => 'Sample User Agent',
+    #     'password' => 'password',
+    #     'email' => 'user@domain.com',
+    #     'clientEmail' => 'client_1+user@domain.com',
+    #     'applicationToken' => 'IGNORED',
+    #     'alternateUrl' => 'https://sandbox.google.com/api/adwords/v13/',
     # }
-    # adwords = AdWords::API.new(AdWords::AdWordsCredentials.new(creds), 13)
-
+    # adwords = AdWords::API.new(AdWords::AdWordsCredentials.new(creds))
     adwords = AdWords::API.new
 
     # Modify the following values to set the seed keywords, language,
     # country targeting, and synonyms options.
-
     keywords = ['new york']
     languages = %w{en}
     countries = %w{US}
@@ -60,15 +58,16 @@ def main()
 
     seed_keywords = []
     keywords.each do |keyword|
-      seed_keyword = AdWords::KeywordToolService::SeedKeyword.new
+      seed_keyword = AdWords::V13::KeywordToolService::SeedKeyword.new
       seed_keyword.text = keyword
       seed_keyword.type = 'Broad'  # Or 'Phrase' or 'Exact' if desired.
       seed_keywords << seed_keyword
     end
 
-    variations = adwords.getKeywordVariations(seed_keywords, use_synonyms,
-					      languages, countries
-					      ).getKeywordVariationsReturn
+    kwdtool_srv = adwords.get_service(13, 'KeywordTool')
+    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
@@ -83,9 +82,9 @@ def main()
     end
     variation_objects.sort! do |a, b|
       if b.avgSearchVolume == a.avgSearchVolume
-	a.lastMonthSearchVolume <=> b.lastMonthSearchVolume
+        a.lastMonthSearchVolume <=> b.lastMonthSearchVolume
       else
-	b.avgSearchVolume <=> a.avgSearchVolume
+        b.avgSearchVolume <=> a.avgSearchVolume
       end
     end
 
@@ -95,27 +94,31 @@ def main()
       keywords_to_estimate << variation_object.text
     end
 
-    ad_group_request = AdWords::TrafficEstimatorService::AdGroupRequest.new
+    ad_group_request = AdWords::V13::TrafficEstimatorService::AdGroupRequest.new
     ad_group_request.maxCpc = 1000000
     keywords_to_estimate.each do |keyword_to_estimate|
-      keyword_request = AdWords::TrafficEstimatorService::KeywordRequest.new
+      keyword_request =
+          AdWords::V13::TrafficEstimatorService::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 = AdWords::TrafficEstimatorService::GeoTarget.new
-    countryTargets = AdWords::TrafficEstimatorService::CountryTargets.new
+    geo_targeting = AdWords::V13::TrafficEstimatorService::GeoTarget.new
+    countryTargets = AdWords::V13::TrafficEstimatorService::CountryTargets.new
     countryTargets.countries = countries
     geo_targeting.countryTargets = countryTargets
 
-    campaign_request = AdWords::TrafficEstimatorService::CampaignRequest.new
+    campaign_request =
+        AdWords::V13::TrafficEstimatorService::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 = adwords.estimateCampaignList([campaign_request]).first
+    traffic_est_srv = adwords.get_service(13, 'TrafficEstimator')
+    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
@@ -123,24 +126,22 @@ def main()
       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]
+          [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
@@ -153,7 +154,6 @@ def main()
     #     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
@@ -161,13 +161,11 @@ def main()
   ensure
     # Display API unit usage info. This data is stored as a class variable
     # in the AdWords::API class and accessed via static methods.
-    # AdWords::API.get_total_units() returns a running total of units used in
-    # the scope of the current program.
-    # AdWords::API.get_last_units() returns the number used in the last call.
-
+    # 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::API.get_total_units(), AdWords::API.get_last_units()]
+        [adwords.total_units, adwords.last_units]
   end
 end
 
@@ -178,7 +176,6 @@ if __FILE__ == $0
   # To enable this, set the ADWORDS4R_DEBUG environement varaible to 'true'.
   # This can be done either from your operating system environment or via
   # code, as done below.
-
   ENV['ADWORDS4R_DEBUG'] = 'false'
 
   main()