google-adwords-api 0.4.0 → 0.4.1

data/ChangeLog

@@ -1,3 +1,12 @@
+0.4.1:
+  - Support for v201109.
+  - Added support and example for AdHoc reports.
+  - Removed deprecated TrafficEstimatorService (v13 only).
+  - Support for proxies.
+  - Units spent count and other headers information can now be obtained by
+    passing user block to a method call.
+  - Require google-ads-common 0.5.2 or later from now on.
+
 0.4.0:
   - First experimental Savon-based release.
   - use_ruby_names is now deprecated and always true.

data/README

@@ -6,9 +6,9 @@ AdWords and DoubleClick Ad Exchange Buyer API!
 Please note that this is an early PREVIEW of the client library, still under
 development.
 
-It contains full support for v13, v200909, v201003, v201008 and v201101, with
-full stubs, and a simplified programming interface that lets you handle
-everything in native Ruby collections.
+It contains full support for v13, v200909, v201003, v201008, v201101 and
+v201109, with full stubs, and a simplified programming interface that lets you
+handle everything in native Ruby collections.
 
 
 = Docs for Users
@@ -27,9 +27,9 @@ Buyer client library examples. You need the AdWords library in order to use it
 which is installed automatically as a dependency.
 
 The following gem libraries are required:
-- savon v0.9.6
-- httpclient v2.1.2 or greater
-- google-ads-common v0.5.0 or later.
+  - savon v0.9.6
+  - httpclient v2.1.2 or greater
+  - google-ads-common v0.5.2 or later.
 
 
 == 2 - Using the client library:
@@ -63,7 +63,7 @@ You can also pass API a manually constructed config hash like:
          :user_agent => 'Ruby Sample',
          :password => 'PASSWORD',
          :email => 'user@domain.com',
-         :client_email => 'user2@domain.com'
+         :client_customer_id => '012-345-6789'
      },
      :service => {
        :environment => 'PRODUCTION'
@@ -71,18 +71,19 @@ You can also pass API a manually constructed config hash like:
    })
 
 Then, just specify which service you're looking to use, and which version:
-   campaign_srv = adwords.service(:CampaignService, :v201101)
+   campaign_srv = adwords.service(:CampaignService, :v201109)
 
 and you should now be able to just use the API methods in the object you were
 returned:
-   campaigns = campaign_srv.get({})    # Empty selector to get all
+   # Get 'Id', 'Name' and 'Status' fields of all campaigns.
+   campaigns = campaign_srv.get({:fields => ['Id', 'Name', 'Status']})
 
 See the code in the examples directory for working examples you can build from.
 
 *Note*: if your setup requires you to send connections through a proxy server,
 please set the appropriate options in the config file or config hash. E.g.:
    config[:connection] = {
-     :proxy => 'http://user:password@proxy_hostname:8080/path'
+     :proxy => 'http://user:password@proxy_hostname:8080'
    }
 
 
@@ -140,6 +141,21 @@ Request details and units spend are logged at the INFO log level, while raw HTTP
 headers and XML dumps are logged at the DEBUG log level. For more details on
 using Logger refer to the Ruby Logger documentation.
 
+=== 2.4 - Calculating unit spend:
+
+Each AdWords API operation performed consumes a certain number of API units, as
+specified in the rate sheet:
+  http://code.google.com/apis/adwords/docs/ratesheet.html
+
+The amount of units spent is returned in the header part of the SOAP response.
+This information can be obtained by passing a user block during method call:
+  response = report_def_srv.get(selector) do |header|
+    puts "Units spent: %d" % header[:units]
+  end
+
+You can also retrieve the response body as the second block parameter:
+  report_def_srv.get(selector) {|header, body| ... }
+
 
 = Docs for Developers
 

data/Rakefile

@@ -48,7 +48,7 @@ spec = Gem::Specification.new do |s|
   s.test_files = tests
   s.has_rdoc = true
   s.extra_rdoc_files = docs
-  s.add_dependency('google-ads-common', '~> 0.5.0')
+  s.add_dependency('google-ads-common', '~> 0.5.2')
   s.add_dependency('savon', '= 0.9.6')
 end
 

data/examples/v200909/add_ad_group.rb

@@ -44,7 +44,7 @@ def add_ad_group()
   operation = {
     :operator => 'ADD',
     :operand => {
-      :name => 'Earth to Mars Cruises #%s' % (Time.new.to_f * 1000).to_i,
+      :name => "Earth to Mars Cruises #%d" % (Time.new.to_f * 1000).to_i,
       :status => 'ENABLED',
       :campaign_id => campaign_id,
       :bids => {
@@ -64,7 +64,7 @@ def add_ad_group()
   # Add ad group.
   response = ad_group_srv.mutate([operation])
   ad_group = response[:value].first
-  puts 'Ad group id %d was successfully added.' % ad_group[:id]
+  puts "Ad group ID %d was successfully added." % ad_group[:id]
 end
 
 if __FILE__ == $0

data/examples/v200909/add_ads.rb

@@ -75,7 +75,7 @@ def add_ads()
       :ad_group_id => ad_group_id,
       :ad => {
         :xsi_type => 'ImageAd',
-        :name => 'Cruise to mars image ad #%s' % (Time.new.to_f * 1000).to_i,
+        :name => "Cruise to mars image ad #%d" % (Time.new.to_f * 1000).to_i,
         :url => 'http://www.example.com',
         :display_url => 'www.example.com',
         :image => {
@@ -91,11 +91,11 @@ def add_ads()
     ads = response[:value]
     puts "Added #{ads.length} ad(s) to ad group #{ad_group_id}."
     ads.each do |ad|
-      puts "  Ad id is #{ad[:ad][:id]}, type is #{ad[:ad][:xsi_type]} and " +
-          "status is \"#{ad[:status]}\"."
+      puts "  Ad ID is #{ad[:ad][:id]}, type is '#{ad[:ad][:xsi_type]}' and " +
+          "status is '#{ad[:status]}'."
     end
   else
-    puts "No ads were added."
+    puts 'No ads were added.'
   end
 end
 

data/examples/v200909/add_campaign.rb

@@ -41,7 +41,7 @@ def add_campaign()
   operation = {
     :operator => 'ADD',
     :operand => {
-      :name => 'Interplanetary Cruise #%s' % (Time.new.to_f * 1000).to_i,
+      :name => "Interplanetary Cruise #%d" % (Time.new.to_f * 1000).to_i,
       :status => 'PAUSED',
       :bidding_strategy => {
         # The 'xsi_type' field allows you to specify the xsi:type of the object
@@ -63,7 +63,7 @@ def add_campaign()
   response = campaign_srv.mutate([operation])
   if response and response[:value]
     campaign = response[:value].first
-    puts 'Campaign with name "%s" and id %d was added.' %
+    puts "Campaign with name '%s' and ID %d was added." %
         [campaign[:name], campaign[:id]]
   else
     puts 'No campaigns were added.'

data/examples/v200909/check_campaigns.rb

@@ -45,7 +45,7 @@ def check_campaigns()
   operation = {
     :operator => 'ADD',
     :operand => {
-      :name => 'Interplanetary Cruise #%s' % (Time.new.to_f * 1000).to_i,
+      :name => "Interplanetary Cruise #%d" % (Time.new.to_f * 1000).to_i,
       :status => 'PAUSED',
       :bidding_strategy => {
         # The 'xsi_type' field allows you to specify the xsi:type of the object
@@ -68,8 +68,8 @@ def check_campaigns()
   if response and response[:value]
     campaigns = response[:value]
     campaigns.each do |campaign|
-      puts "Unexpected campaign creation! Name \"#{campaign[:name]}\", id " +
-          "#{campaign[:id]} and status is \"#{campaign[:status]}\"."
+      puts "Unexpected campaign creation! Name '#{campaign[:name]}', ID " +
+          "#{campaign[:id]} and status is '#{campaign[:status]}'."
     end
   else
     puts 'No campaigns created.'
@@ -80,7 +80,7 @@ def check_campaigns()
   operation = {
     :operator => 'ADD',
     :operand => {
-      :name => 'Interplanetary Cruise #%s' % (Time.new.to_f * 1000).to_i,
+      :name => "Interplanetary Cruise #%d" % (Time.new.to_f * 1000).to_i,
       :status => 'PAUSED',
       :bidding_strategy => nil,
       :budget => {

data/examples/v201003/add_ad_group.rb

@@ -44,7 +44,7 @@ def add_ad_group()
   operation = {
     :operator => 'ADD',
     :operand => {
-      :name => 'Earth to Mars Cruises #%s' % (Time.new.to_f * 1000).to_i,
+      :name => "Earth to Mars Cruises #%d" % (Time.new.to_f * 1000).to_i,
       :status => 'ENABLED',
       :campaign_id => campaign_id,
       :bids => {
@@ -64,7 +64,7 @@ def add_ad_group()
   # Add ad group.
   response = ad_group_srv.mutate([operation])
   ad_group = response[:value].first
-  puts 'Ad group id %d was successfully added.' % ad_group[:id]
+  puts "Ad group ID %d was successfully added." % ad_group[:id]
 end
 
 if __FILE__ == $0

data/examples/v201003/add_ads.rb

@@ -78,7 +78,7 @@ def add_ads()
       :ad_group_id => ad_group_id,
       :ad => {
         :xsi_type => 'ImageAd',
-        :name => 'Cruise to mars image ad #%s' % (Time.new.to_f * 1000).to_i,
+        :name => "Cruise to mars image ad #%d" % (Time.new.to_f * 1000).to_i,
         :url => 'http://www.example.com',
         :display_url => 'www.example.com',
         :image => {
@@ -92,7 +92,7 @@ def add_ads()
   template_ad_operation = {
     :operator => 'ADD',
     :operand => {
-      :adGroupId => ad_group_id,
+      :ad_group_id => ad_group_id,
       :ad => {
         :xsi_type => 'TemplateAd',
         :template_id => 9,
@@ -100,7 +100,7 @@ def add_ads()
           :width => 300,
           :height => 250
         },
-        :name => 'Mars cruise video ad #%s' % (Time.new.to_f * 1000).to_i,
+        :name => "Mars cruise video ad #%d" % (Time.new.to_f * 1000).to_i,
         :display_url => 'www.example.com',
         :url => 'http://www.example.com',
         :template_elements => [{
@@ -144,11 +144,11 @@ def add_ads()
     ads = response[:value]
     puts "Added #{ads.length} ad(s) to ad group #{ad_group_id}."
     ads.each do |ad|
-      puts "  Ad id is #{ad[:ad][:id]}, type is #{ad[:ad][:xsi_type]} and " +
-          "status is \"#{ad[:status]}\"."
+      puts "  Ad ID is #{ad[:ad][:id]}, type is '#{ad[:ad][:xsi_type]}' and " +
+          "status is '#{ad[:status]}'."
     end
   else
-    puts "No ads were added."
+    puts 'No ads were added.'
   end
 end
 

data/examples/v201003/add_campaign.rb

@@ -41,7 +41,7 @@ def add_campaign()
   operation = {
     :operator => 'ADD',
     :operand => {
-      :name => 'Interplanetary Cruise #%s' % (Time.new.to_f * 1000).to_i,
+      :name => "Interplanetary Cruise #%d" % (Time.new.to_f * 1000).to_i,
       :status => 'PAUSED',
       :bidding_strategy => {
         # The 'xsi_type' field allows you to specify the xsi:type of the object
@@ -63,7 +63,7 @@ def add_campaign()
   response = campaign_srv.mutate([operation])
   if response and response[:value]
     campaign = response[:value].first
-    puts 'Campaign with name "%s" and id %d was added.' %
+    puts "Campaign with name '%s' and ID %d was added." %
         [campaign[:name], campaign[:id]]
   else
     puts 'No campaigns were added.'

data/examples/v201003/add_keywords_performance_report_definition.rb

@@ -59,7 +59,7 @@ def add_keywords_performance_report_definition()
           :max => end_date
         }
       },
-      :report_name => 'Keywords performance report #%s' %
+      :report_name => "Keywords performance report #%d" %
           (Time.new.to_f * 1000).to_i,
       :report_type => 'KEYWORDS_PERFORMANCE_REPORT',
       :date_range_type => 'CUSTOM_DATE',
@@ -71,7 +71,7 @@ def add_keywords_performance_report_definition()
   response = report_def_srv.mutate([operation])
   if response
     response.each do |report_definition|
-      puts 'Report definition with name \'%s\' and id \'%s\' was added' %
+      puts "Report definition with name '%s' and ID %d was added" %
           [report_definition[:report_name], report_definition[:id]]
     end
   end

data/examples/v201003/check_campaigns.rb

@@ -45,7 +45,7 @@ def check_campaigns()
   operation = {
     :operator => 'ADD',
     :operand => {
-      :name => 'Interplanetary Cruise #%s' % (Time.new.to_f * 1000).to_i,
+      :name => "Interplanetary Cruise #%d" % (Time.new.to_f * 1000).to_i,
       :status => 'PAUSED',
       :bidding_strategy => {
         # The 'xsi_type' field allows you to specify the xsi:type of the object
@@ -68,8 +68,8 @@ def check_campaigns()
   if response and response[:value]
     campaigns = response[:value]
     campaigns.each do |campaign|
-      puts "Unexpected campaign creation! Name \"#{campaign[:name]}\", id " +
-          "#{campaign[:id]} and status is \"#{campaign[:status]}\"."
+      puts "Unexpected campaign creation! Name '#{campaign[:name]}', ID " +
+          "#{campaign[:id]} and status is '#{campaign[:status]}'."
     end
   else
     puts 'No campaigns created.'
@@ -80,7 +80,7 @@ def check_campaigns()
   operation = {
     :operator => 'ADD',
     :operand => {
-      :name => 'Interplanetary Cruise #%s' % (Time.new.to_f * 1000).to_i,
+      :name => "Interplanetary Cruise #%d" % (Time.new.to_f * 1000).to_i,
       :status => 'PAUSED',
       :bidding_strategy => nil,
       :budget => {

data/examples/v201008/add_ad_group.rb

@@ -44,7 +44,7 @@ def add_ad_group()
   operation = {
     :operator => 'ADD',
     :operand => {
-      :name => 'Earth to Mars Cruises #%s' % (Time.new.to_f * 1000).to_i,
+      :name => "Earth to Mars Cruises #%d" % (Time.new.to_f * 1000).to_i,
       :status => 'ENABLED',
       :campaign_id => campaign_id,
       :bids => {
@@ -64,7 +64,7 @@ def add_ad_group()
   # Add ad group.
   response = ad_group_srv.mutate([operation])
   ad_group = response[:value].first
-  puts 'Ad group id %d was successfully added.' % ad_group[:id]
+  puts "Ad group ID %d was successfully added." % ad_group[:id]
 end
 
 if __FILE__ == $0

data/examples/v201008/add_ads.rb

@@ -78,7 +78,7 @@ def add_ads()
       :ad_group_id => ad_group_id,
       :ad => {
         :xsi_type => 'ImageAd',
-        :name => 'Cruise to mars image ad #%s' % (Time.new.to_f * 1000).to_i,
+        :name => "Cruise to mars image ad #%d" % (Time.new.to_f * 1000).to_i,
         :url => 'http://www.example.com',
         :display_url => 'www.example.com',
         :image => {
@@ -88,11 +88,11 @@ def add_ads()
     }
   }
 
-  # Create template ad, using the Click to Play Video template (id 9).
+  # Create template ad, using the Click to Play Video template (ID 9).
   template_ad_operation = {
     :operator => 'ADD',
     :operand => {
-      :adGroupId => ad_group_id,
+      :ad_group_id => ad_group_id,
       :ad => {
         :xsi_type => 'TemplateAd',
         :template_id => 9,
@@ -100,7 +100,7 @@ def add_ads()
           :width => 300,
           :height => 250
         },
-        :name => 'Mars cruise video ad #%s' % (Time.new.to_f * 1000).to_i,
+        :name => "Mars cruise video ad #%d" % (Time.new.to_f * 1000).to_i,
         :display_url => 'www.example.com',
         :url => 'http://www.example.com',
         :template_elements => [{
@@ -144,11 +144,11 @@ def add_ads()
     ads = response[:value]
     puts "Added #{ads.length} ad(s) to ad group #{ad_group_id}."
     ads.each do |ad|
-      puts "  Ad id is #{ad[:ad][:id]}, type is #{ad[:ad][:xsi_type]} and " +
-          "status is \"#{ad[:status]}\"."
+      puts "  Ad ID is #{ad[:ad][:id]}, type is '#{ad[:ad][:xsi_type]}' and " +
+          "status is '#{ad[:status]}'."
     end
   else
-    puts "No ads were added."
+    puts 'No ads were added.'
   end
 end
 

data/examples/v201008/add_campaign.rb

@@ -41,7 +41,7 @@ def add_campaign()
   operation = {
     :operator => 'ADD',
     :operand => {
-      :name => 'Interplanetary Cruise #%s' % (Time.new.to_f * 1000).to_i,
+      :name => "Interplanetary Cruise #%d" % (Time.new.to_f * 1000).to_i,
       :status => 'PAUSED',
       :bidding_strategy => {
         # The 'xsi_type' field allows you to specify the xsi:type of the object
@@ -63,7 +63,7 @@ def add_campaign()
   response = campaign_srv.mutate([operation])
   if response and response[:value]
     campaign = response[:value].first
-    puts 'Campaign with name "%s" and id %d was added.' %
+    puts "Campaign with name '%s' and ID %d was added." %
         [campaign[:name], campaign[:id]]
   else
     puts 'No campaigns were added.'

data/examples/v201008/add_experiment.rb

@@ -53,16 +53,16 @@ def add_experiment()
     :operator => 'ADD',
     :operand => {
       :campaign_id => campaign_id,
-      :name => 'Interplanetary Experiment #%s' % (Time.new.to_f * 1000).to_i,
+      :name => "Interplanetary Experiment #%d" % (Time.new.to_f * 1000).to_i,
       :query_percentage => 10,
-      :start_date_time => Time.now.strftime("%Y%m%d %H%M%S")
+      :start_date_time => Time.now.strftime('%Y%m%d %H%M%S')
     }
   }
 
   # Add experiment.
   response = experiment_srv.mutate([operation])
   experiment = response[:value].first
-  puts 'Experiment with name "%s" and id %d was added.' %
+  puts "Experiment with name '%s' and ID %d was added." %
       [experiment[:name], experiment[:id]]
 
   experiment_id = experiment[:id]
@@ -93,7 +93,7 @@ def add_experiment()
   # Update ad group.
   response = ad_group_srv.mutate([operation])
   ad_group = response[:value].first
-  puts 'Ad group id %d was updated for the experiment.' % ad_group[:id]
+  puts "Ad group ID %d was updated for the experiment." % ad_group[:id]
 
   # Setup ad group criterion for the experiment.
   ad_group_criterion = {
@@ -126,7 +126,7 @@ def add_experiment()
   # Update criterion.
   response = ad_group_criterion_srv.mutate([operation])
   criterion = response[:value].first
-  puts 'Criterion id %d was successfully updated for the experiment.' %
+  puts "Criterion ID %d was successfully updated for the experiment." %
       [criterion[:criterion][:id]]
 
 end

data/examples/v201008/add_keywords_performance_report_definition.rb

@@ -59,7 +59,7 @@ def add_keywords_performance_report_definition()
           :max => end_date
         }
       },
-      :report_name => 'Keywords performance report #%s' %
+      :report_name => "Keywords performance report #%d" %
           (Time.new.to_f * 1000).to_i,
       :report_type => 'KEYWORDS_PERFORMANCE_REPORT',
       :date_range_type => 'CUSTOM_DATE',
@@ -71,7 +71,7 @@ def add_keywords_performance_report_definition()
   response = report_def_srv.mutate([operation])
   if response
     response.each do |report_definition|
-      puts 'Report definition with name \'%s\' and id \'%s\' was added' %
+      puts "Report definition with name '%s' and ID %d was added." %
           [report_definition[:report_name], report_definition[:id]]
     end
   end