google-adwords-api 0.5.1 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. data/ChangeLog +4 -0
  2. data/README +2 -1
  3. data/examples/v201109/account_management/create_account.rb +2 -2
  4. data/examples/v201109/account_management/get_account_alerts.rb +3 -3
  5. data/examples/v201109/account_management/get_account_changes.rb +2 -2
  6. data/examples/v201109/account_management/get_account_hierarchy.rb +2 -2
  7. data/examples/v201109/account_management/get_client_customer_id.rb +6 -8
  8. data/examples/v201109/account_management/get_client_unit_usage.rb +6 -7
  9. data/examples/v201109/basic_operations/add_ad_groups.rb +111 -0
  10. data/examples/v201109/basic_operations/add_campaigns.rb +125 -0
  11. data/examples/v201109/basic_operations/add_keywords.rb +16 -11
  12. data/examples/v201109/basic_operations/add_text_ads.rb +23 -19
  13. data/examples/v201109/basic_operations/delete_ad.rb +7 -7
  14. data/examples/v201109/basic_operations/delete_ad_group.rb +7 -7
  15. data/examples/v201109/basic_operations/delete_campaign.rb +7 -7
  16. data/examples/v201109/basic_operations/delete_keyword.rb +7 -7
  17. data/examples/v201109/basic_operations/get_ad_groups.rb +7 -7
  18. data/examples/v201109/basic_operations/get_campaigns.rb +3 -3
  19. data/examples/v201109/basic_operations/get_keywords.rb +7 -7
  20. data/examples/v201109/basic_operations/get_text_ads.rb +7 -7
  21. data/examples/v201109/basic_operations/pause_ad.rb +7 -7
  22. data/examples/v201109/basic_operations/update_ad_group.rb +6 -6
  23. data/examples/v201109/basic_operations/update_campaign.rb +6 -6
  24. data/examples/v201109/basic_operations/update_keyword.rb +7 -7
  25. data/examples/v201109/campaign_management/add_experiment.rb +14 -9
  26. data/examples/v201109/campaign_management/add_keywords_in_bulk.rb +5 -5
  27. data/examples/v201109/campaign_management/add_location_extension.rb +13 -7
  28. data/examples/v201109/campaign_management/add_location_extension_override.rb +7 -7
  29. data/examples/v201109/campaign_management/get_all_disapproved_ads.rb +6 -6
  30. data/examples/v201109/campaign_management/promote_experiment.rb +5 -6
  31. data/examples/v201109/campaign_management/set_ad_parameters.rb +8 -8
  32. data/examples/v201109/campaign_management/validate_text_ad.rb +7 -9
  33. data/examples/v201109/error_handling/handle_captcha_challenge.rb +3 -4
  34. data/examples/v201109/error_handling/handle_partial_failures.rb +5 -6
  35. data/examples/v201109/error_handling/handle_policy_violation_error.rb +5 -6
  36. data/examples/v201109/error_handling/handle_two_factor_authorization_error.rb +2 -2
  37. data/examples/v201109/misc/get_all_images_and_videos.rb +3 -3
  38. data/examples/v201109/misc/upload_image.rb +2 -2
  39. data/examples/v201109/misc/use_oauth.rb +3 -3
  40. data/examples/v201109/optimization/estimate_keyword_traffic.rb +2 -2
  41. data/examples/v201109/optimization/get_keyword_bid_simulations.rb +6 -7
  42. data/examples/v201109/optimization/get_keyword_ideas.rb +6 -7
  43. data/examples/v201109/optimization/get_placement_ideas.rb +6 -7
  44. data/examples/v201109/remarketing/add_audience.rb +5 -3
  45. data/examples/v201109/remarketing/add_conversion_tracker.rb +12 -3
  46. data/examples/v201109/reporting/download_criteria_report.rb +7 -8
  47. data/examples/v201109/reporting/download_defined_report.rb +6 -7
  48. data/examples/v201109/reporting/get_campaign_stats.rb +105 -0
  49. data/examples/v201109/reporting/get_defined_reports.rb +2 -2
  50. data/examples/v201109/reporting/get_report_fields.rb +6 -7
  51. data/examples/v201109/reporting/parallel_report_download.rb +8 -8
  52. data/examples/v201109/targeting/add_campaign_targeting_criteria.rb +5 -6
  53. data/examples/v201109/targeting/get_campaign_targeting_criteria.rb +7 -8
  54. data/examples/v201109/targeting/get_targetable_languages_and_carriers.rb +2 -2
  55. data/examples/v201109/targeting/lookup_location.rb +2 -2
  56. data/lib/adwords_api/version.rb +1 -1
  57. data/test/examples/v201109/test_account_management.rb +60 -0
  58. data/test/examples/v201109/test_basic_operations.rb +172 -0
  59. data/test/examples/v201109/test_campaign_management.rb +116 -0
  60. data/test/examples/v201109/test_error_handling.rb +63 -0
  61. data/test/examples/v201109/test_misc.rb +45 -0
  62. data/test/examples/v201109/test_optimization.rb +63 -0
  63. data/test/examples/v201109/test_remarketing.rb +39 -0
  64. data/test/examples/v201109/test_reporting.rb +89 -0
  65. data/test/examples/v201109/test_targeting.rb +60 -0
  66. data/test/examples/v201109/utils.rb +239 -0
  67. data/test/suite_exampletests.rb +31 -0
  68. metadata +18 -6
  69. data/examples/v201109/basic_operations/add_ad_group.rb +0 -89
  70. data/examples/v201109/basic_operations/add_campaign.rb +0 -99
@@ -27,9 +27,6 @@
27
27
  require 'adwords_api'
28
28
  require 'adwords_api/utils'
29
29
 
30
- API_VERSION = :v201109
31
- PAGE_SIZE = 500
32
-
33
30
  def get_all_images_and_videos()
34
31
  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
35
32
  # when called without parameters.
@@ -80,6 +77,9 @@ def get_all_images_and_videos()
80
77
  end
81
78
 
82
79
  if __FILE__ == $0
80
+ API_VERSION = :v201109
81
+ PAGE_SIZE = 500
82
+
83
83
  begin
84
84
  get_all_images_and_videos()
85
85
 
@@ -26,8 +26,6 @@ require 'adwords_api'
26
26
  require 'adwords_api/utils'
27
27
  require 'base64'
28
28
 
29
- API_VERSION = :v201109
30
-
31
29
  def upload_image()
32
30
  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
33
31
  # when called without parameters.
@@ -69,6 +67,8 @@ def upload_image()
69
67
  end
70
68
 
71
69
  if __FILE__ == $0
70
+ API_VERSION = :v201109
71
+
72
72
  begin
73
73
  upload_image()
74
74
 
@@ -24,9 +24,6 @@
24
24
 
25
25
  require 'adwords_api'
26
26
 
27
- API_VERSION = :v201109
28
- MAX_RETRIES = 3
29
-
30
27
  def use_oauth()
31
28
  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
32
29
  # when called without parameters.
@@ -76,6 +73,9 @@ def use_oauth()
76
73
  end
77
74
 
78
75
  if __FILE__ == $0
76
+ API_VERSION = :v201109
77
+ MAX_RETRIES = 3
78
+
79
79
  begin
80
80
  use_oauth()
81
81
 
@@ -24,8 +24,6 @@
24
24
 
25
25
  require 'adwords_api'
26
26
 
27
- API_VERSION = :v201109
28
-
29
27
  def estimate_keyword_traffic()
30
28
  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
31
29
  # when called without parameters.
@@ -108,6 +106,8 @@ def estimate_keyword_traffic()
108
106
  end
109
107
 
110
108
  if __FILE__ == $0
109
+ API_VERSION = :v201109
110
+
111
111
  begin
112
112
  estimate_keyword_traffic()
113
113
 
@@ -25,9 +25,7 @@
25
25
 
26
26
  require 'adwords_api'
27
27
 
28
- API_VERSION = :v201109
29
-
30
- def get_criterion_bid_landscapes()
28
+ def get_criterion_bid_landscapes(ad_group_id, keyword_id)
31
29
  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
32
30
  # when called without parameters.
33
31
  adwords = AdwordsApi::Api.new
@@ -38,9 +36,6 @@ def get_criterion_bid_landscapes()
38
36
 
39
37
  data_srv = adwords.service(:DataService, API_VERSION)
40
38
 
41
- ad_group_id = 'INSERT_ADGROUP_ID_HERE'.to_i
42
- keyword_id = 'INSERT_KEYWORD_ID_HERE'.to_i
43
-
44
39
  # Get keyword bid landscape.
45
40
  selector = {
46
41
  :fields => ['AdGroupId', 'CriterionId', 'StartDate', 'EndDate', 'Bid',
@@ -72,8 +67,12 @@ def get_criterion_bid_landscapes()
72
67
  end
73
68
 
74
69
  if __FILE__ == $0
70
+ API_VERSION = :v201109
71
+
75
72
  begin
76
- get_criterion_bid_landscapes()
73
+ ad_group_id = 'INSERT_ADGROUP_ID_HERE'.to_i
74
+ keyword_id = 'INSERT_KEYWORD_ID_HERE'.to_i
75
+ get_criterion_bid_landscapes(ad_group_id, keyword_id)
77
76
 
78
77
  # HTTP errors.
79
78
  rescue AdsCommon::Errors::HttpError => e
@@ -25,10 +25,7 @@
25
25
  require 'adwords_api'
26
26
  require 'adwords_api/utils'
27
27
 
28
- API_VERSION = :v201109
29
- PAGE_SIZE = 100
30
-
31
- def get_keyword_ideas()
28
+ def get_keyword_ideas(keyword_text)
32
29
  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
33
30
  # when called without parameters.
34
31
  adwords = AdwordsApi::Api.new
@@ -39,8 +36,6 @@ def get_keyword_ideas()
39
36
 
40
37
  targeting_idea_srv = adwords.service(:TargetingIdeaService, API_VERSION)
41
38
 
42
- keyword_text = 'INSERT_KEYWORD_TEXT_HERE'
43
-
44
39
  # Construct selector object.
45
40
  selector = {
46
41
  :idea_type => 'KEYWORD',
@@ -87,8 +82,12 @@ def get_keyword_ideas()
87
82
  end
88
83
 
89
84
  if __FILE__ == $0
85
+ API_VERSION = :v201109
86
+ PAGE_SIZE = 100
87
+
90
88
  begin
91
- get_keyword_ideas()
89
+ keyword_text = 'INSERT_KEYWORD_TEXT_HERE'
90
+ get_keyword_ideas(keyword_text)
92
91
 
93
92
  # HTTP errors.
94
93
  rescue AdsCommon::Errors::HttpError => e
@@ -26,10 +26,7 @@
26
26
  require 'adwords_api'
27
27
  require 'adwords_api/utils'
28
28
 
29
- API_VERSION = :v201109
30
- PAGE_SIZE = 100
31
-
32
- def get_placement_ideas()
29
+ def get_placement_ideas(url)
33
30
  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
34
31
  # when called without parameters.
35
32
  adwords = AdwordsApi::Api.new
@@ -40,8 +37,6 @@ def get_placement_ideas()
40
37
 
41
38
  targeting_idea_srv = adwords.service(:TargetingIdeaService, API_VERSION)
42
39
 
43
- url = 'INSERT_PLACEMENT_URL_HERE'
44
-
45
40
  # Construct selector.
46
41
  selector = {
47
42
  :idea_type => 'PLACEMENT',
@@ -86,8 +81,12 @@ def get_placement_ideas()
86
81
  end
87
82
 
88
83
  if __FILE__ == $0
84
+ API_VERSION = :v201109
85
+ PAGE_SIZE = 100
86
+
89
87
  begin
90
- get_placement_ideas()
88
+ url = 'INSERT_PLACEMENT_URL_HERE'
89
+ get_placement_ideas(url)
91
90
 
92
91
  # HTTP errors.
93
92
  rescue AdsCommon::Errors::HttpError => e
@@ -25,8 +25,6 @@
25
25
 
26
26
  require 'adwords_api'
27
27
 
28
- API_VERSION = :v201109
29
-
30
28
  def add_audience()
31
29
  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
32
30
  # when called without parameters.
@@ -52,7 +50,9 @@ def add_audience()
52
50
  :description => 'A list of mars cruise customers in the last year',
53
51
  :status => 'OPEN',
54
52
  :membership_life_span => 365,
55
- :conversion_types => [{:name => name}]
53
+ :conversion_types => [{:name => name}],
54
+ # Optional field.
55
+ :status => 'OPEN'
56
56
  }
57
57
  }
58
58
 
@@ -92,6 +92,8 @@ def add_audience()
92
92
  end
93
93
 
94
94
  if __FILE__ == $0
95
+ API_VERSION = :v201109
96
+
95
97
  begin
96
98
  add_audience()
97
99
 
@@ -24,8 +24,6 @@
24
24
 
25
25
  require 'adwords_api'
26
26
 
27
- API_VERSION = :v201109
28
-
29
27
  def add_conversion_tracker()
30
28
  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
31
29
  # when called without parameters.
@@ -50,7 +48,16 @@ def add_conversion_tracker()
50
48
  :category => 'DEFAULT',
51
49
  :markup_language => 'HTML',
52
50
  :http_protocol => 'HTTP',
53
- :text_format => 'HIDDEN'
51
+ :text_format => 'HIDDEN',
52
+ # Optional fields:
53
+ :status => 'ENABLED',
54
+ :viewthrough_lookback_window => 15,
55
+ :viewthrough_conversion_de_dup_search => true,
56
+ :is_product_ads_chargeable => true,
57
+ :product_ads_chargeable_conversion_window => 15,
58
+ :conversion_page_language => 'en',
59
+ :background_color => '#0000FF',
60
+ :user_revenue_value => 'someJavascriptVariable'
54
61
  }
55
62
  }
56
63
 
@@ -67,6 +74,8 @@ def add_conversion_tracker()
67
74
  end
68
75
 
69
76
  if __FILE__ == $0
77
+ API_VERSION = :v201109
78
+
70
79
  begin
71
80
  add_conversion_tracker()
72
81
 
@@ -22,9 +22,7 @@
22
22
 
23
23
  require 'adwords_api'
24
24
 
25
- API_VERSION = :v201109
26
-
27
- def download_criteria_report()
25
+ def download_criteria_report(file_name)
28
26
  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
29
27
  # when called without parameters.
30
28
  adwords = AdwordsApi::Api.new
@@ -36,10 +34,6 @@ def download_criteria_report()
36
34
  # Get report utilities for the version.
37
35
  report_utils = adwords.report_utils(API_VERSION)
38
36
 
39
- # File name to write report to. To retrieve the report as return value, use
40
- # "download_report" method.
41
- file_name = 'INSERT_OUTPUT_FILE_NAME_HERE'
42
-
43
37
  # Define report definition. You can also pass your own XML text as a string.
44
38
  report_definition = {
45
39
  :selector => {
@@ -61,13 +55,18 @@ def download_criteria_report()
61
55
  }
62
56
 
63
57
  # Download report, using "download_report_as_file" utility method.
58
+ # To retrieve the report as return value, use "download_report" method.
64
59
  report_utils.download_report_as_file(report_definition, file_name)
65
60
  puts "Report was downloaded to '%s'." % file_name
66
61
  end
67
62
 
68
63
  if __FILE__ == $0
64
+ API_VERSION = :v201109
65
+
69
66
  begin
70
- download_criteria_report()
67
+ # File name to write report to.
68
+ file_name = 'INSERT_OUTPUT_FILE_NAME_HERE'
69
+ download_criteria_report(file_name)
71
70
 
72
71
  # HTTP errors.
73
72
  rescue AdsCommon::Errors::HttpError => e
@@ -24,9 +24,7 @@
24
24
 
25
25
  require 'adwords_api'
26
26
 
27
- API_VERSION = :v201109
28
-
29
- def download_defined_report()
27
+ def download_defined_report(report_definition_id, file_name)
30
28
  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
31
29
  # when called without parameters.
32
30
  adwords = AdwordsApi::Api.new
@@ -37,9 +35,6 @@ def download_defined_report()
37
35
 
38
36
  report_def_srv = adwords.service(:ReportDefinitionService, API_VERSION)
39
37
 
40
- report_definition_id = 'INSERT_REPORT_DEFINITION_ID'.to_i
41
- file_name = 'INSERT_OUTPUT_FILE_NAME_HERE'
42
-
43
38
  # Download report, using "download_report_as_file" extension method.
44
39
  report_def_srv.download_report_as_file(report_definition_id, file_name)
45
40
  puts 'Report with definition id %d was downloaded to \'%s\'.' %
@@ -47,8 +42,12 @@ def download_defined_report()
47
42
  end
48
43
 
49
44
  if __FILE__ == $0
45
+ API_VERSION = :v201109
46
+
50
47
  begin
51
- download_defined_report()
48
+ report_definition_id = 'INSERT_REPORT_DEFINITION_ID'.to_i
49
+ file_name = 'INSERT_OUTPUT_FILE_NAME_HERE'
50
+ download_defined_report(report_definition_id, file_name)
52
51
 
53
52
  # HTTP errors.
54
53
  rescue AdsCommon::Errors::HttpError => e
@@ -0,0 +1,105 @@
1
+ #!/usr/bin/env ruby
2
+ # Encoding: utf-8
3
+ #
4
+ # Author:: api.dklimkin@gmail.com (Danial Klimkin)
5
+ #
6
+ # Copyright:: Copyright 2012, Google Inc. All Rights Reserved.
7
+ #
8
+ # License:: Licensed under the Apache License, Version 2.0 (the "License");
9
+ # you may not use this file except in compliance with the License.
10
+ # You may obtain a copy of the License at
11
+ #
12
+ # http://www.apache.org/licenses/LICENSE-2.0
13
+ #
14
+ # Unless required by applicable law or agreed to in writing, software
15
+ # distributed under the License is distributed on an "AS IS" BASIS,
16
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
17
+ # implied.
18
+ # See the License for the specific language governing permissions and
19
+ # limitations under the License.
20
+ #
21
+ # This example gets various statistics for campaigns that received at least one
22
+ # impression during the last week. To get campaigns, run get_campaigns.rb.
23
+ #
24
+ # Tags: CampaignService.get
25
+
26
+ require 'adwords_api'
27
+ require 'date'
28
+
29
+ def get_campaign_stats()
30
+ # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
31
+ # when called without parameters.
32
+ adwords = AdwordsApi::Api.new
33
+
34
+ # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
35
+ # the configuration file or provide your own logger:
36
+ # adwords.logger = Logger.new('adwords_xml.log')
37
+
38
+ campaign_srv = adwords.service(:CampaignService, API_VERSION)
39
+
40
+ # Prepare start and end date for the last week.
41
+ start_date = DateTime.parse((Date.today - 7).to_s).strftime("%Y%m%d")
42
+ end_date = DateTime.parse((Date.today - 1).to_s).strftime("%Y%m%d")
43
+
44
+ # Get all the campaigns for this account.
45
+ selector = {
46
+ :fields => ['Id', 'Name', 'Impressions', 'Clicks', 'Cost', 'Ctr'],
47
+ :predicates => [
48
+ {:field => 'Impressions', :operator => 'GREATER_THAN', :values => [0]}
49
+ ],
50
+ :date_range => {:min => start_date, :max => end_date},
51
+ :paging => {
52
+ :start_index => 0,
53
+ :number_results => PAGE_SIZE
54
+ }
55
+ }
56
+
57
+ # Set initial values.
58
+ offset, page = 0, {}
59
+
60
+ begin
61
+ page = campaign_srv.get(selector)
62
+ if page[:entries]
63
+ page[:entries].each do |campaign|
64
+ puts ("Campaign with ID %d, name '%s' had the following stats during" +
65
+ " the last week: ") % [campaign[:id], campaign[:name]]
66
+ stats = campaign[:campaign_stats]
67
+ puts "\tImpressions: %d" % stats[:impressions]
68
+ puts "\tClicks: %d" % stats[:clicks]
69
+ puts "\tCost: %.2f" % (stats[:cost][:micro_amount] / 1000000)
70
+ puts "\tCTR: %.2f%%" % (stats[:ctr] * 100)
71
+ end
72
+ # Increment values to request the next page.
73
+ offset += PAGE_SIZE
74
+ selector[:paging][:start_index] = offset
75
+ end
76
+ end while page[:total_num_entries] > offset
77
+
78
+ if page.include?(:total_num_entries)
79
+ puts "Total number of campaigns found: %d." % [page[:total_num_entries]]
80
+ end
81
+ end
82
+
83
+ if __FILE__ == $0
84
+ API_VERSION = :v201109
85
+ PAGE_SIZE = 500
86
+
87
+ begin
88
+ get_campaign_stats()
89
+
90
+ # HTTP errors.
91
+ rescue AdsCommon::Errors::HttpError => e
92
+ puts "HTTP Error: %s" % e
93
+
94
+ # API errors.
95
+ rescue AdwordsApi::Errors::ApiException => e
96
+ puts "Message: %s" % e.message
97
+ puts 'Errors:'
98
+ e.errors.each_with_index do |error, index|
99
+ puts "\tError [%d]:" % (index + 1)
100
+ error.each do |field, value|
101
+ puts "\t\t%s: %s" % [field, value]
102
+ end
103
+ end
104
+ end
105
+ end
@@ -25,8 +25,6 @@
25
25
 
26
26
  require 'adwords_api'
27
27
 
28
- API_VERSION = :v201109
29
-
30
28
  def get_defined_reports()
31
29
  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
32
30
  # when called without parameters.
@@ -54,6 +52,8 @@ def get_defined_reports()
54
52
  end
55
53
 
56
54
  if __FILE__ == $0
55
+ API_VERSION = :v201109
56
+
57
57
  begin
58
58
  get_defined_reports()
59
59