google-adwords-api 0.4.5 → 0.5.0

data/examples/v201109/{upload_image.rb → misc/upload_image.rb}

@@ -1,4 +1,5 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
 # Author:: api.sgomes@gmail.com (Sérgio Gomes)
 #

data/examples/v201109/{oauth_handling.rb → misc/use_oauth.rb}

@@ -1,4 +1,5 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
 # Author:: api.dklimkin@gmail.com (Danial Klimkin)
 #
@@ -27,7 +28,7 @@ require 'adwords_api'
 API_VERSION = :v201109
 MAX_RETRIES = 3
 
-def oauth_handling()
+def use_oauth()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -41,7 +42,9 @@ def oauth_handling()
   # Get all the campaigns for this account; empty selector.
   selector = {
     :fields => ['Id', 'Name', 'Status'],
-    :ordering => [{:field => 'Name', :sort_order => 'ASCENDING'}]
+    :ordering => [
+      {:field => 'Name', :sort_order => 'ASCENDING'}
+    ]
   }
 
   retry_count = 0
@@ -65,17 +68,17 @@ def oauth_handling()
   if response and response[:entries]
     campaigns = response[:entries]
     campaigns.each do |campaign|
-      puts "Campaign name is \"#{campaign[:name]}\", id is #{campaign[:id]} " +
-          "and status is \"#{campaign[:status]}\"."
+      puts "Campaign ID %d, name '%s' and status '%s'" %
+          [campaign[:id], campaign[:name], campaign[:status]]
     end
   else
-    puts "No campaigns were found."
+    puts 'No campaigns were found.'
   end
 end
 
 if __FILE__ == $0
   begin
-    oauth_handling()
+    use_oauth()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e

data/examples/v201109/{get_traffic_estimates.rb → optimization/estimate_keyword_traffic.rb}

@@ -1,4 +1,5 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
 # Author:: api.dklimkin@gmail.com (Danial Klimkin)
 #
@@ -26,7 +27,7 @@ require 'adwords_api'
 
 API_VERSION = :v201109
 
-def get_traffic_estimates()
+def estimate_keyword_traffic()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -109,7 +110,7 @@ end
 
 if __FILE__ == $0
   begin
-    get_traffic_estimates()
+    estimate_keyword_traffic()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e

data/examples/v201109/{get_criterion_bid_landscape.rb → optimization/get_keyword_bid_simulations.rb}

@@ -1,6 +1,7 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
-# Author:: api.sgomes@gmail.com (Sérgio Gomes)
+# Author:: api.dklimkin@gmail.com (Danial Klimkin)
 #
 # Copyright:: Copyright 2011, Google Inc. All Rights Reserved.
 #
@@ -17,8 +18,8 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# This example gets a bid landscapes for a criterion. To get criteria, run
-# get_all_ad_group_criteria.rb.
+# This example gets bid landscapes for a keyword. To get keywords, run
+# get_keywords.rb.
 #
 # Tags: DataService.getCriterionBidLandscape
 
@@ -39,35 +40,35 @@ def get_criterion_bid_landscapes()
   data_srv = adwords.service(:DataService, API_VERSION)
 
   ad_group_id = 'INSERT_ADGROUP_ID_HERE'.to_i
-  criterion_id = 'INSERT_CRITERION_ID_HERE'.to_i
+  keyword_id = 'INSERT_KEYWORD_ID_HERE'.to_i
 
-  # Get criterion bid landscape.
+  # Get keyword bid landscape.
   selector = {
-    :fields => ["AdGroupId", "CriterionId", "StartDate", "EndDate", "Bid",
-        "LocalClicks", "LocalCost", "MarginalCpc", "LocalImpressions"],
+    :fields => ['AdGroupId', 'CriterionId', 'StartDate', 'EndDate', 'Bid',
+        'LocalClicks', 'LocalCost', 'MarginalCpc', 'LocalImpressions'],
     :predicates => [
       {:field => 'AdGroupId', :operator => 'IN', :values => [ad_group_id]},
-      {:field => 'CriterionId', :operator => 'IN', :values => [criterion_id]},
+      {:field => 'CriterionId', :operator => 'IN', :values => [keyword_id]},
     ]
   }
   page = data_srv.get_criterion_bid_landscape(selector)
   if page and page[:entries]
-    puts "#{page[:entries].length} bid landscape(s) retrieved."
+    puts "Bid landscape(s) retrieved: %d." % [page[:entries].length]
     page[:entries].each do |bid_landscape|
-      puts "Retrieved criterion bid landscape with ad group id " +
-          "'#{bid_landscape[:ad_group_id]}', criterion id " +
-          "'#{bid_landscape[:criterion_id]}', start date " +
-          "'#{bid_landscape[:start_date]}', end date "+
-          "'#{bid_landscape[:end_date]}', with landscape points:"
+      puts ("Retrieved keyword bid landscape with ad group ID %d" +
+          ", keyword ID %d, start date '%s', end date '%s'" +
+          ", with landscape points:") %
+          [bid_landscape[:ad_group_id], bid_landscape[:criterion_id],
+           bid_landscape[:start_date], bid_landscape[:end_date]]
       bid_landscape[:landscape_points].each do |point|
-        puts "  #{point[:bid][:micro_amount]} => clicks: #{point.clicks}, " +
-            "cost: #{point[:cost][:micro_amount]}, marginalCpc: " +
-            "#{point[:marginal_cpc][:micro_amount]}, impressions: " +
-            "#{point[:impressions]}"
+        puts "\t%d => clicks: %d, cost: %d, marginalCpc: %d, impressions: %d" %
+            [point[:bid][:micro_amount], point.clicks,
+             point[:cost][:micro_amount], point[:marginal_cpc][:micro_amount],
+             point[:impressions]]
       end
     end
   else
-    puts "No bid landscapes retrieved."
+    puts 'No bid landscapes retrieved.'
   end
 end
 

data/examples/v201109/{get_related_keywords.rb → optimization/get_keyword_ideas.rb}

@@ -1,4 +1,5 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
 # Author:: api.sgomes@gmail.com (Sérgio Gomes)
 #
@@ -28,7 +29,7 @@ require 'adwords_api/utils'
 API_VERSION = :v201109
 PAGE_SIZE = 100
 
-def get_related_keywords()
+def get_keyword_ideas()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -80,15 +81,15 @@ def get_related_keywords()
   results.each do |result|
     data = AdwordsApi::Utils.map(result[:data])
     keyword = data['CRITERION'][:value]
-    puts "Found keyword with text \"%s\" and match type \"%s\"" %
+    puts "Found keyword with text '%s' and match type '%s'" %
         [keyword[:text], keyword[:match_type]]
   end
-  puts "Total keywords related to \"%s\": %d." % [keyword_text, results.length]
+  puts "Total keywords related to '%s': %d." % [keyword_text, results.length]
 end
 
 if __FILE__ == $0
   begin
-    get_related_keywords()
+    get_keyword_ideas()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e

data/examples/v201109/{get_keyword_opportunities.rb → optimization/get_keyword_opportunities.rb}

@@ -1,4 +1,5 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
 # Author:: api.sgomes@gmail.com (Sérgio Gomes)
 #

data/examples/v201109/{get_related_placements.rb → optimization/get_placement_ideas.rb}

@@ -1,4 +1,5 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
 # Author:: api.sgomes@gmail.com (Sérgio Gomes)
 #
@@ -29,7 +30,7 @@ require 'adwords_api/utils'
 API_VERSION = :v201109
 PAGE_SIZE = 100
 
-def get_related_placements()
+def get_placement_ideas()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -79,7 +80,7 @@ def get_related_placements()
   results.each do |result|
     data = AdwordsApi::Utils.map(result[:data])
     placement = data['CRITERION'][:value]
-    puts "Related content keywords found at URL [%s]" % placement[:url]
+    puts "Related placement found at URL [%s]" % placement[:url]
   end
   puts "Total URLs found with keywords related to keywords at [%s]: %d." %
       [url, results.length]
@@ -87,7 +88,7 @@ end
 
 if __FILE__ == $0
   begin
-    get_related_placements()
+    get_placement_ideas()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e

data/examples/v201109/{add_user_list.rb → remarketing/add_audience.rb}

@@ -1,4 +1,5 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
 # Author:: api.sgomes@gmail.com (Sérgio Gomes)
 #
@@ -17,8 +18,8 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# This example illustrates how to create a user list and show its associated
-# conversion tracker code snippet.
+# This example illustrates how to create a user list (a.k.a. Audience) and shows
+# its associated conversion tracker code snippet.
 #
 # Tags: UserListService.mutate, ConversionTrackerService.get
 
@@ -27,7 +28,7 @@ require 'adwords_api'
 
 API_VERSION = :v201109
 
-def add_user_list()
+def add_audience()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -93,7 +94,7 @@ end
 
 if __FILE__ == $0
   begin
-    add_user_list()
+    add_audience()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e

data/examples/v201109/{add_conversion.rb → remarketing/add_conversion_tracker.rb}

@@ -1,4 +1,5 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
 # Author:: api.sgomes@gmail.com (Sérgio Gomes)
 #
@@ -17,7 +18,7 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# This example illustrates how to add an AdWords conversion.
+# This example illustrates how to add an AdWords conversion tracker.
 #
 # Tags: ConversionTrackerService.mutate
 
@@ -26,7 +27,7 @@ require 'adwords_api'
 
 API_VERSION = :v201109
 
-def add_conversion()
+def add_conversion_tracker()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -58,9 +59,9 @@ def add_conversion()
   response = conv_tracker_srv.mutate([operation])
   if response and response[:value]
     conversion = response[:value].first
-    puts "Conversion with ID #{conversion[:id]}, name " +
-        "'#{conversion[:name]}', status '#{conversion[:status]}' and " +
-        " category '#{conversion[:category]}' was added."
+    puts ("Conversion with ID %d, name '%s', status '%s' and category '%s'" +
+        " was added.") % [conversion[:id], conversion[:name],
+        conversion[:status], conversion[:category]]
   else
     puts 'No conversions were added.'
   end
@@ -68,7 +69,7 @@ end
 
 if __FILE__ == $0
   begin
-    add_conversion()
+    add_conversion_tracker()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e

data/examples/v201109/{download_adhoc_report.rb → reporting/download_criteria_report.rb}

@@ -1,4 +1,5 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
 # Author:: api.dklimkin@gmail.com (Danial Klimkin)
 #
@@ -24,7 +25,7 @@ require 'adwords_api'
 
 API_VERSION = :v201109
 
-def download_adhoc_report()
+def download_criteria_report()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -43,20 +44,21 @@ def download_adhoc_report()
   # Define report definition. You can also pass your own XML text as a string.
   report_definition = {
     :selector => {
-        :fields => ['CampaignId', 'Id', 'Impressions', 'Clicks', 'Cost'],
-        # Predicates are optional.
-        :predicates => {
-          :field => 'Status',
-          :operator => 'IN',
-          :values => ['ENABLED', 'PAUSED']
-        }
-      },
-      :report_name => 'Custom ADGROUP_PERFORMANCE_REPORT',
-      :report_type => 'ADGROUP_PERFORMANCE_REPORT',
-      :download_format => 'CSV',
-      :date_range_type => 'LAST_7_DAYS',
-      # Enable to get rows with zero impressions.
-      :include_zero_impressions => false
+      :fields => ['CampaignId', 'AdGroupId', 'Id', 'Criteria', 'CriteriaType',
+          'Impressions', 'Clicks', 'Cost'],
+      # Predicates are optional.
+      :predicates => {
+        :field => 'Status',
+        :operator => 'IN',
+        :values => ['ACTIVE', 'PAUSED']
+      }
+    },
+    :report_name => 'Last 7 days CRITERIA_PERFORMANCE_REPORT',
+    :report_type => 'CRITERIA_PERFORMANCE_REPORT',
+    :download_format => 'CSV',
+    :date_range_type => 'LAST_7_DAYS',
+    # Enable to get rows with zero impressions.
+    :include_zero_impressions => false
   }
 
   # Download report, using "download_report_as_file" utility method.
@@ -66,7 +68,7 @@ end
 
 if __FILE__ == $0
   begin
-    download_adhoc_report()
+    download_criteria_report()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e

data/examples/v201109/{download_report.rb → reporting/download_defined_report.rb}

@@ -1,4 +1,5 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
 # Author:: api.sgomes@gmail.com (Sérgio Gomes)
 #
@@ -17,15 +18,16 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# This example gets and downloads a report from a report definition. To get a
-# report definition, run add_keywords_performance_report_definition.rb.
+# This example gets and downloads a report from a report definition.
+#
+# Note: defined reports are deprecated, please use AdHoc reporting.
 
 require 'rubygems'
 require 'adwords_api'
 
 API_VERSION = :v201109
 
-def download_report()
+def download_defined_report()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -47,7 +49,7 @@ end
 
 if __FILE__ == $0
   begin
-    download_report()
+    download_defined_report()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e

data/examples/v201109/{get_all_report_definitions.rb → reporting/get_defined_reports.rb}

@@ -1,4 +1,5 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
 # Author:: api.sgomes@gmail.com (Sérgio Gomes)
 #
@@ -17,8 +18,8 @@
 #           See the License for the specific language governing permissions and
 #           limitations under the License.
 #
-# This example gets all report definitions. To add a report definition, run
-# add_keywords_performance_report.rb.
+# This example gets all report definitions. Adding new definitions is
+# deprecated, please use AdHoc reporting.
 #
 # Tags: ReportDefinitionService.get
 
@@ -27,7 +28,7 @@ require 'adwords_api'
 
 API_VERSION = :v201109
 
-def get_all_report_definitions()
+def get_defined_reports()
   # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
   # when called without parameters.
   adwords = AdwordsApi::Api.new
@@ -49,13 +50,13 @@ def get_all_report_definitions()
           "\"#{entry[:report_name]}\"."
     end
   else
-    puts "No report definitions found."
+    puts 'No report definitions found.'
   end
 end
 
 if __FILE__ == $0
   begin
-    get_all_report_definitions()
+    get_defined_reports()
 
   # HTTP errors.
   rescue AdsCommon::Errors::HttpError => e

data/examples/v201109/{get_report_fields.rb → reporting/get_report_fields.rb}

@@ -1,4 +1,5 @@
-#!/usr/bin/ruby
+#!/usr/bin/env ruby
+# Encoding: utf-8
 #
 # Author:: api.sgomes@gmail.com (Sérgio Gomes)
 #