google-adwords-api 0.4.0 → 0.4.1

data/examples/v201109/get_client_customer_id.rb

@@ -0,0 +1,87 @@
+#!/usr/bin/ruby
+#
+# Author:: api.dklimkin@gmail.com (Danial Klimkin)
+#
+# Copyright:: Copyright 2011, 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 find a client customer ID for a client email.
+# We recommend to use this script as a one off to convert your identifiers to
+# IDs and store them for future use.
+#
+# Tags: InfoService.get
+
+require 'rubygems'
+require 'adwords_api'
+require 'adwords_api/utils'
+
+API_VERSION = :v201109
+
+def get_client_customer_id()
+  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
+  # when called without parameters.
+  adwords = AdwordsApi::Api.new
+
+  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
+  # the configuration file or provide your own logger:
+  # adwords.logger = Logger.new('adwords_xml.log')
+
+  info_srv = adwords.service(:InfoService, API_VERSION)
+
+  # Email address to find ID for.
+  client_email = 'INSERT_EMAIL_ADDRESS_HERE'
+
+  today = Time.new.strftime('%Y%m%d')
+
+  selector = {
+    :client_emails => [client_email],
+    :api_usage_type => 'UNIT_COUNT_FOR_CLIENTS',
+    :include_sub_accounts => true,
+    :date_range => {:min => today, :max => today}
+  }
+
+  # Get the information for client email address.
+  info = adwords.use_mcc() {info_srv.get(selector)}
+
+  if info and info[:api_usage_records]
+    api_usage_records = info[:api_usage_records]
+    api_usage_records.each do |record|
+      puts "Found record with client email '%s' and ID %s." %
+          [record[:client_email],
+           AdwordsApi::Utils.format_id(record[:client_customer_id])]
+    end
+  end
+end
+
+if __FILE__ == $0
+  begin
+    get_client_customer_id()
+
+  # HTTP errors.
+  rescue AdsCommon::Errors::HttpError => e
+    puts "HTTP Error: %s" % e
+
+  # API errors.
+  rescue AdwordsApi::Errors::ApiException => e
+    puts "Message: %s" % e.message
+    puts 'Errors:'
+    e.errors.each_with_index do |error, index|
+      puts "\tError [%d]:" % (index + 1)
+      error.each do |field, value|
+        puts "\t\t%s: %s" % [field, value]
+      end
+    end
+  end
+end

data/examples/v201109/get_conversion_optimizer_eligibility.rb

@@ -0,0 +1,93 @@
+#!/usr/bin/ruby
+#
+# Author:: api.sgomes@gmail.com (Sérgio Gomes)
+#
+# Copyright:: Copyright 2011, 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 shows how to check for conversion optimizer eligibility by
+# examining the conversion_optimizer_eligibility field of the Campaign.
+#
+# Tags: CampaignService.get
+
+require 'rubygems'
+require 'adwords_api'
+require 'pp'
+
+API_VERSION = :v201109
+
+def get_conversion_optimizer_eligibility()
+  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
+  # when called without parameters.
+  adwords = AdwordsApi::Api.new
+
+  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
+  # the configuration file or provide your own logger:
+  # adwords.logger = Logger.new('adwords_xml.log')
+
+  campaign_srv = adwords.service(:CampaignService, API_VERSION)
+
+  campaign_id = 'INSERT_CAMPAIGN_ID_HERE'.to_i
+
+  # Get campaign.
+  selector = {
+    :fields => ['Id', 'Name', 'Eligible', 'RejectionReasons'],
+    :predicates => [{
+      :field => 'Id',
+      :operator => 'IN',
+      :values => [campaign_id]
+    }]
+  }
+  response = campaign_srv.get(selector)
+
+  if response and response[:entries]
+    campaigns = response[:entries]
+    campaigns.each do |campaign|
+      eligibility = campaign[:conversion_optimizer_eligibility]
+      if eligibility[:eligible]
+        puts "Campaign with name is \"#{campaign[:name]}\" and id " +
+            "#{campaign[:id]} is eligible to use the conversion optimizer."
+      else
+        puts "Campaign with name is \"#{campaign[:name]}\" and id " +
+            "#{campaign[:id]} is not eligible to use the conversion " +
+            "optimizer for the reasons: " +
+            eligibility[:rejection_reasons].pretty_inspect
+      end
+    end
+  else
+    puts "No campaigns were found."
+  end
+end
+
+if __FILE__ == $0
+  begin
+    get_conversion_optimizer_eligibility()
+
+  # HTTP errors.
+  rescue AdsCommon::Errors::HttpError => e
+    puts "HTTP Error: %s" % e
+
+  # API errors.
+  rescue AdwordsApi::Errors::ApiException => e
+    puts "Message: %s" % e.message
+    puts 'Errors:'
+    e.errors.each_with_index do |error, index|
+      puts "\tError [%d]:" % (index + 1)
+      error.each do |field, value|
+        puts "\t\t%s: %s" % [field, value]
+      end
+    end
+  end
+end

data/examples/v201109/get_criterion_bid_landscape.rb

@@ -0,0 +1,93 @@
+#!/usr/bin/ruby
+#
+# Author:: api.sgomes@gmail.com (Sérgio Gomes)
+#
+# Copyright:: Copyright 2011, 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 gets a bid landscapes for a criterion. To get criteria, run
+# get_all_ad_group_criteria.rb.
+#
+# Tags: DataService.getCriterionBidLandscape
+
+require 'rubygems'
+require 'adwords_api'
+
+API_VERSION = :v201109
+
+def get_criterion_bid_landscapes()
+  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
+  # when called without parameters.
+  adwords = AdwordsApi::Api.new
+
+  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
+  # the configuration file or provide your own logger:
+  # adwords.logger = Logger.new('adwords_xml.log')
+
+  data_srv = adwords.service(:DataService, API_VERSION)
+
+  ad_group_id = 'INSERT_ADGROUP_ID_HERE'.to_i
+  criterion_id = 'INSERT_CRITERION_ID_HERE'.to_i
+
+  # Get criterion bid landscape.
+  selector = {
+    :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]},
+    ]
+  }
+  page = data_srv.get_criterion_bid_landscape(selector)
+  if page and page[:entries]
+    puts "#{page[:entries].length} bid landscape(s) retrieved."
+    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:"
+      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]}"
+      end
+    end
+  else
+    puts "No bid landscapes retrieved."
+  end
+end
+
+if __FILE__ == $0
+  begin
+    get_criterion_bid_landscapes()
+
+  # HTTP errors.
+  rescue AdsCommon::Errors::HttpError => e
+    puts "HTTP Error: %s" % e
+
+  # API errors.
+  rescue AdwordsApi::Errors::ApiException => e
+    puts "Message: %s" % e.message
+    puts 'Errors:'
+    e.errors.each_with_index do |error, index|
+      puts "\tError [%d]:" % (index + 1)
+      error.each do |field, value|
+        puts "\t\t%s: %s" % [field, value]
+      end
+    end
+  end
+end

data/examples/v201109/get_geo_location_info.rb

@@ -0,0 +1,99 @@
+#!/usr/bin/ruby
+#
+# Author:: api.sgomes@gmail.com (Sérgio Gomes)
+#
+# Copyright:: Copyright 2011, 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 geo location information for
+# addresses.
+#
+# Tags: GeoLocationService.get
+
+require 'rubygems'
+require 'adwords_api'
+
+API_VERSION = :v201109
+
+def get_geo_location_info()
+  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
+  # when called without parameters.
+  adwords = AdwordsApi::Api.new
+
+  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
+  # the configuration file or provide your own logger:
+  # adwords.logger = Logger.new('adwords_xml.log')
+
+  geo_location_srv = adwords.service(:GeoLocationService, API_VERSION)
+
+  selector = {
+    :addresses => [
+      {
+        :street_address => '1600 Amphitheatre Parkway',
+        :city_name => 'Mountain View',
+        :province_code => 'US-CA',
+        :province_name => 'California',
+        :postal_code => '94043',
+        :country_code => 'US'
+      },
+      {
+        :street_address => '76 Ninth Avenue',
+        :city_name => 'New York',
+        :province_code => 'US-NY',
+        :province_name => 'New York',
+        :postal_code => '10011',
+        :country_code => 'US'
+      },
+      {
+        :street_address => '五四大街1号, Beijing东城区',
+        :country_code => 'CN'
+      }
+    ]
+  }
+
+  # Get the geo location info for the various addresses.
+  locations = geo_location_srv.get(selector)
+
+  if locations
+    locations.each do |location|
+      puts "Address \"#{location[:address][:street_address]}\" has latitude " +
+          "#{location[:geo_point][:latitude_in_micro_degrees]} and " +
+          "longitude #{location[:geo_point][:longitude_in_micro_degrees]}."
+    end
+  else
+    puts "No geo locations were returned."
+  end
+end
+
+if __FILE__ == $0
+  begin
+    get_geo_location_info()
+
+  # HTTP errors.
+  rescue AdsCommon::Errors::HttpError => e
+    puts "HTTP Error: %s" % e
+
+  # API errors.
+  rescue AdwordsApi::Errors::ApiException => e
+    puts "Message: %s" % e.message
+    puts 'Errors:'
+    e.errors.each_with_index do |error, index|
+      puts "\tError [%d]:" % (index + 1)
+      error.each do |field, value|
+        puts "\t\t%s: %s" % [field, value]
+      end
+    end
+  end
+end

data/examples/v201109/get_keyword_opportunities.rb

@@ -0,0 +1,95 @@
+#!/usr/bin/ruby
+#
+# Author:: api.sgomes@gmail.com (Sérgio Gomes)
+#
+# Copyright:: Copyright 2011, 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 reads all the keyword opportunities for the customer.
+#
+# Tags: BulkOpportunityService.get
+
+require 'rubygems'
+require 'adwords_api'
+require 'adwords_api/utils'
+
+API_VERSION = :v201109
+PAGE_SIZE = 20
+
+def get_keyword_opportunities()
+  # AdwordsApi::Api will read a config file from ENV['HOME']/adwords_api.yml
+  # when called without parameters.
+  adwords = AdwordsApi::Api.new
+
+  # To enable logging of SOAP requests, set the log_level value to 'DEBUG' in
+  # the configuration file or provide your own logger:
+  # adwords.logger = Logger.new('adwords_xml.log')
+
+  bulk_opportunity_srv = adwords.service(:BulkOpportunityService, API_VERSION)
+
+  # Construct selector object.
+  selector = {
+    :requested_attribute_types => ['KEYWORD', 'IDEA_TYPE'],
+    :paging => {
+      :start_index => 0,
+      :number_results => PAGE_SIZE
+    }
+  }
+
+  # Perform request.
+  ideas = []
+  index = 0
+  begin
+    page = bulk_opportunity_srv.get(selector)
+    if page and page[:entries]
+      page[:entries].each do |entry|
+        ideas += entry[:opportunity_ideas] if entry[:opportunity_ideas]
+      end
+    end
+    break if page[:total_num_entries] <= index
+    index += PAGE_SIZE
+    selector[:paging][:start_index] = index
+  end while page[:total_num_entries] > index
+
+  # Display results.
+  ideas.each do |idea|
+    data = AdwordsApi::Utils.map(idea[:data])
+    keyword = data['KEYWORD'][:value][:text]
+    idea_type = data['IDEA_TYPE'][:value]
+    puts " Found opportunity idea of type \"%s\": \"%s\"" % [idea_type, keyword]
+  end
+  puts "Total opportunity ideas: %d." % [ideas.length]
+end
+
+if __FILE__ == $0
+  begin
+    get_keyword_opportunities()
+
+  # HTTP errors.
+  rescue AdsCommon::Errors::HttpError => e
+    puts "HTTP Error: %s" % e
+
+  # API errors.
+  rescue AdwordsApi::Errors::ApiException => e
+    puts "Message: %s" % e.message
+    puts 'Errors:'
+    e.errors.each_with_index do |error, index|
+      puts "\tError [%d]:" % (index + 1)
+      error.each do |field, value|
+        puts "\t\t%s: %s" % [field, value]
+      end
+    end
+  end
+end