adwords4r 11.0.3 → 11.1.0

data/ChangeLog.txt

@@ -1,3 +1,15 @@
+11.1.0
+- Added additional attributes to the AdWords::Error::ApiError class.
+  This should make it easier to get all the useful SOAP fault information, some of which wasn't available in the previous version.
+  The extra attributes are :trigger_ex, :soap_faultcode_ex, :soap_faultstring_ex, and :code_ex
+- Added static methods to the AdWords::API class to retrieve API unit usage information.
+  AdWords::API.get_total_units() will return the a running total of API units used since the API was initialized.
+  AdWords::API.get_last_units() will return the number of API units used for the last API call.
+- Started the process of creating new sample code. The existing code samples are a bit lacking and were moved to the 'examples/old' directory.
+  A new sample program, 'examples/reports.rb' was created. This sample validates, schedules, and downloads a Keyword Structure report.
+  It's a fairly extensive sample and illustrates some of the new API features as well as general best-practices. 
+  Look for more sample code in future releases.
+
 11.0.3
 - update soap4r minimum version requirement in the .gem file to 1.5.8, as there are compatibility problems with 1.5.6
 - the ADWORDS4R_DEBUG environment variable was causing problems when it was not set instead of silently disabling debugging; this is fixed.

data/Copying.txt

@@ -1,28 +1,13 @@
-Copyright (c) 2006, Google Inc.
-All rights reserved.
+Copyright 2008, Google Inc. All Rights Reserved.
 
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are
-met:
+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
 
-    * Redistributions of source code must retain the above copyright
-notice, this list of conditions and the following disclaimer.
-    * Redistributions in binary form must reproduce the above
-copyright notice, this list of conditions and the following disclaimer
-in the documentation and/or other materials provided with the
-distribution.
-    * Neither the name of Google Inc. nor the names of its
-contributors may be used to endorse or promote products derived from
-this software without specific prior written permission.
+    http://www.apache.org/licenses/LICENSE-2.0
 
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+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.

data/Licence.txt

@@ -1,10 +1,13 @@
-Copyright (c) 2006, Google Inc
-All rights reserved.
+Copyright 2008, Google Inc. All Rights Reserved.
 
-Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+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
 
-    * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-    * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
-    * Neither the name of Google, Inc nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+    http://www.apache.org/licenses/LICENSE-2.0
 
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+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.

data/Rakefile

@@ -16,7 +16,7 @@ require 'lib/adwords4r/services'
 
 CLOBBER.include('pkg')
 
-CURRENT_VERSION = '11.0.3'
+CURRENT_VERSION = '11.1.0'
 PKG_VERSION = ENV['REL'] ? ENV['REL'] : CURRENT_VERSION
 
 SRC_RB = FileList['lib/**/*.rb']

data/Readme.txt

@@ -3,8 +3,6 @@ Google adwwords4r Library
 
 Welcome to adwords4r: Bringing the delights of ruby programming to the AdWords world!
 
-	 AdWords::API.new.getAllAdWordsCampaigns(123).each {|c| puts c.name}
-
 Documentation and comments are a work in progress.
 
 
@@ -12,7 +10,8 @@ Useful Web Resources
 --------------------
 
 - AdWords home: https://adwords.google.com/
-- The AdWords API main documentation: http://www.google.com/apis/adwords/developer/index.html
+- AdWords API discussion forum: http://groups.google.com/group/adwords-api
+- AdWords API documentation: http://www.google.com/apis/adwords/developer/index.html
 - This project's Google Code page: http://code.google.com/p/google-api-adwords-ruby/
 
 
@@ -24,10 +23,9 @@ adwords4r is a ruby gem.  See http://docs.rubygems.org/read/book/1
 Install it using the gem install command.
 > gem install --remote adwords4r
 
-Requirements are:
-    s.requirements << 'soap4r v 1.5.6 or greater'
-    s.requirements << 'http-access2 v 2.0.5 or greater'
-(see gem file for details)
+The following gem libraries are required:
+- soap4r v1.5.8 or greater
+- httpclient v2.1.2 or greater
 
 It's pretty easy to use.
 See http://docs.rubygems.org/read/chapter/3#page70 for how to set the rubygem environment.
@@ -42,36 +40,32 @@ Then
 require 'adwords4r'
 
 adwords = AdWords::API.new
-creates a driver for the latest version of AdWords API using credentials provided in ~/adwords.properties
-There is an example in the root adwords4r directory.
+creates a driver for the latest version of AdWords API using a credentials file in ENV['HOME']/adwords.properties
+There is an example credentials in the root adwords4r directory.
 You can also pass API a manually constructed AdWordsCredentials object like:
-adwords = AdWords::API.new(AdWords::AdWordsCredentials.new(
-{  'token' => 'mytoken',
-  'useragent' => 'P@ playing with the API from ruby',
-  'password' => 'mypasswd',
-  'email' => 'em...@example.com'}
-)) 
+adwords = AdWords::API.new(AdWords::AdWordsCredentials.new({
+  'developerToken' => 'DEVELOPER_TOKEN',
+  'applicationToken' => 'APPLICATION_TOKEN',
+  'useragent' => 'Ruby Sample',
+  'password' => 'PASSWORD',
+  'email' => 'user@domain.com'
+  'clientEmail' => 'user2@domain.com',
+}))
 
 If you want something more specific, use the optional parameters of the constructor
 adwords = AdWords::API.new(credentials, version)
 
 In order to use the sandbox, you can add a credential named
-alternateUrl, like:
+alternateUrl like:
 alternateUrl=https://sandbox.google.com/api/adwords/v11/
 
 Then just use methods of the API against your driver.
-adwords.getAllAdWordsCampaigns(123).each {|c| puts c.name}
-
-See sample code in examples.
-
-The client code will generate warnings in the console:
-Many: warning: already initialized constant XXX
-A few: at depth 0 - 20: unable to get local issuer certificate
-These are not serious: I need to make them go but they do not affect the correctness of the program.
+See sample code in examples, particularly reports.rb
 
 It is often useful to see a trace of the raw SOAP XML being sent and received.
 To enable this, set the ADWORDS4R_DEBUG environment variable to TRUE.
-e.g. in the bash shell, 'export ADWORDS4R_DEBUG=TRUE'
+e.g. in the bash shell, export ADWORDS4R_DEBUG=TRUE
+or from your Ruby code, ENV['ADWORDS4R_DEBUG'] = 'TRUE'
 The SOAP logs will be written to the current directory.
 
 
@@ -84,18 +78,21 @@ rake generate
     to regenerate the bindings if needed
 rake package
     to package the gem and create a release
-rake publish
-    to publish the gem to rubyforge
     
-adwords4r is licensed under the BSD License
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
-LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
-CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
-GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
-THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Copyright/License Info
+----------------------
+
+Copyright 2008, 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.

data/examples/reports.rb

@@ -0,0 +1,172 @@
+#!/usr/bin/ruby
+#
+# Copyright 2008, 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 schedule and download an AdWords report
+# using the adwords4r client library.
+
+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.
+    #
+    # Credentials can be either for the production or Sandbox environments.
+    # Production environment credentials overview:
+    # http://www.google.com/apis/adwords/developer/index.html
+    # Sandbox environment credentials overview:
+    # http://www.google.com/apis/adwords/developer/adwords_api_sandbox.html
+    #
+    # Instead of reading them from a file, the credentials can be
+    # 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/v11/',
+    # }
+    # adwords = AdWords::API.new(AdWords::AdWordsCredentials.new(creds), 11)
+
+    adwords = AdWords::API.new
+    
+    report_name = 'Report-%s' % DateTime.now.to_s
+    
+    # The following example creates a Structure report with Keyword aggregation.
+    # Because it is a Structure report, startDay and endDay values are ignored.
+    # See http://www.google.com/apis/adwords/developer/ReportService.html for
+    # more information about the different reports you can create.
+
+    job = AdWords::DefinedReportJob.new
+    job.selectedReportType = 'Structure'
+    job.aggregationTypes = 'Keyword'
+    job.name = report_name
+    job.selectedColumns = %w{Campaign AdGroup Keyword KeywordTypeDisplay}
+    job.startDay = '2008-01-01'
+    job.endDay = '2008-01-31'
+    
+    # Validate the report definition to make sure it is valid.
+    # If it is not, an AdWords::Error::ApiError will be thrown.
+
+    adwords.validateReportJob(job)
+    
+    # Since validation passed, schedule the report.
+
+    job_id = adwords.scheduleReportJob(job).scheduleReportJobReturn
+    sleep_interval = 10
+    puts 'Scheduled report with id %d. Now sleeping %d seconds.' %
+      [job_id, sleep_interval]
+    sleep(sleep_interval)
+    
+    # Repeatedly check the report status until it is finished.
+    # 'Pending' and 'InProgress' statuses indicate the job is still being run.
+
+    status = adwords.getReportJobStatus(job_id).getReportJobStatusReturn
+    while status != 'Completed' && status != 'Failed'
+      puts 'Report status is %s. Now sleeping another %d seconds.' %
+	[status, sleep_interval]
+      sleep(sleep_interval)
+      status = adwords.getReportJobStatus(job_id).getReportJobStatusReturn
+    end
+    
+    if status == 'Completed'
+      report_url = adwords.getReportDownloadUrl(job_id).
+	getReportDownloadUrlReturn
+      puts 'Report is completed. Downloading report from %s' % report_url
+      
+      # Download the report via the HTTPClient library and write it to disk.
+      # The report is an XML document; the actual element names vary depending
+      # on what type of report run and columns requested.
+
+      client = HTTPClient.new
+      report_data = client.get_content(report_url)
+      file_name = '%s.xml' % report_name  # Add path to write report elsewhere.
+      begin
+	open(file_name, 'w') {|file| file.puts(report_data)}
+	puts 'Report has been written to %s' % file_name
+
+      rescue Errno::ENOENT, Errno::EACCES => e
+	puts 'Unable to write file: %s' % e
+      end
+    else
+      # Reports that pass validation will normally not fail, but if there is
+      # an error in the report generation service it can sometimes happen.
+
+      puts 'Report generation failed.'
+    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 information. 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 API call.
+
+    puts
+    puts '%d API units consumed total (%d in last call).' %
+      [AdWords::API.get_total_units(), AdWords::API.get_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/lib/adwords4r.rb

@@ -6,6 +6,7 @@ rescue
 end
 require 'soap/soap'
 require 'soap/mapping'
+require 'soap/rpc/driver'
 require 'adwords4r/credentials'
 require 'adwords4r/services'
 
@@ -28,6 +29,26 @@ end
 module AdWords
 
   class API
+
+    @@total_units = 0
+    @@last_units = 0
+
+    def API.add_total_units(increment)
+      @@total_units += increment
+    end
+
+    def API.get_total_units()
+      return @@total_units
+    end
+    
+    def API.set_last_units(value)
+      @@last_units = value
+    end
+    
+    def API.get_last_units()
+      return @@last_units
+    end
+
     attr_reader :credentials, :drivers, :version
     @methodMap = Hash.new
 
@@ -49,7 +70,7 @@ module AdWords
       else
         raise(Error::UnknownAPICall, "Unknown API Call: #{requestName}", caller)
       end
-      # Handle AdWords Application-level error
+    # Handle AdWords Application-level error
     rescue SOAP::FaultError => fault
       raise(Error::ApiError.new(fault), "#{methodName} Call Failed: #{fault.faultstring.to_s}", caller)
     end
@@ -77,6 +98,9 @@ module AdWords
         driver = eval("AdWords::#{getServiceName(s)}.new")
       end
       @credentials.handlers.each {|h| driver.headerhandler << h}
+      
+      # Add response filter to this driver for API unit usage processing.
+      driver.filterchain << ResponseFilter.new
 
       if !ENV['ADWORDS4R_DEBUG'].nil? && ENV['ADWORDS4R_DEBUG'].upcase == 'TRUE'
         driver.wiredump_file_base = "SOAP_#{$$}"
@@ -108,7 +132,6 @@ module AdWords
 
     # Raised if a call returns with a SOAP error, gives you easy access to adwords error fields
     class ApiError < Error
-
       attr_accessor :soap_faultcode
       attr_accessor :soap_faultstring
       attr_accessor :top_code
@@ -122,15 +145,28 @@ module AdWords
       attr_accessor :textIndex
       attr_accessor :textLength
       attr_accessor :trigger
+      
+      # These *_ex attributes have been added to correct deficiencies with the initial implementation.
+      # They should expose more useful information (i.e. text of errors instead of a SOAP element)
+      # and proper mapping of a fault's trigger and code.
+      # The old attributes are left behind for backward compatibility; hopefully this isn't too confusing!
+      attr_accessor :trigger_ex
+      attr_accessor :soap_faultcode_ex
+      attr_accessor :soap_faultstring_ex
+      attr_accessor :code_ex
 
       def initialize(soap_fault)
         @soap_faultcode = protect { soap_fault.faultcode }
+        @soap_faultcode_ex = protect { soap_fault.faultcode.text }
         @soap_faultstring = protect { soap_fault.faultstring }
+        @soap_faultstring_ex = protect { soap_fault.faultstring.text }
         if protect { soap_fault.detail and soap_fault.detail.fault }
           fault = soap_fault.detail.fault
           @top_code = protect { fault.code }
           @internal = protect { fault.internal }
           @message = protect { fault.message }
+          @trigger_ex = protect { fault.trigger }
+	  @code_ex = protect { fault.code }
           if protect { fault.errors and fault.errors.size > 0 }
             error = fault.errors.first
             @code = protect { error.code }
@@ -156,6 +192,22 @@ module AdWords
     end
   end
 
+  # SOAP filter to process response messages for API unit usage information.
+  class ResponseFilter < SOAP::Filter::Handler
+    def on_inbound(xml, opt)
+      # Parse the response XML string for the <operations> header value.
+      if xml =~ %r{<units.+?>(\d+)</units>}
+	units = $1.to_i
+	# Since we don't really have an instance of a useful class here,
+	# we're stuck sticking the value in a class variable for AdWords::API.
+	AdWords::API.set_last_units(units)
+	AdWords::API.add_total_units(units)
+      end
+
+      return xml
+    end
+  end
+
   # These class module methods are helper functions
   class <<self 
 

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.9.4
 specification_version: 1
 name: adwords4r
 version: !ruby/object:Gem::Version 
-  version: 11.0.3
-date: 2007-12-12 00:00:00 -05:00
+  version: 11.1.0
+date: 2008-02-29 00:00:00 -05:00
 summary: Client library for the AdWords API.
 require_paths: 
 - lib
@@ -32,7 +32,6 @@ files:
 - Licence.txt
 - setup.rb
 - Authors.txt
-- Todo.txt
 - ChangeLog.txt
 - Copying.txt
 - Readme.txt
@@ -101,12 +100,13 @@ files:
 - lib/adwords4r/v11/SiteSuggestionService.rb
 - lib/adwords4r/v11/SiteSuggestionServiceMappingRegistry.rb
 - lib/adwords4r/v11/SiteSuggestionServiceDriver.rb
-- examples/framework.rb
-- examples/campaign.rb
-- examples/get_free_usage_this_month.rb
-- examples/keyword_tool_demo.rb
-- examples/traffic_estimator.rb
-- examples/get_unit_count.rb
+- examples/reports.rb
+- examples/old/campaign.rb
+- examples/old/framework.rb
+- examples/old/get_free_usage_this_month.rb
+- examples/old/get_unit_count.rb
+- examples/old/keyword_tool_demo.rb
+- examples/old/traffic_estimator.rb
 test_files: []
 
 rdoc_options: []

data/Todo.txt

@@ -1,21 +0,0 @@
-adwords4r todo list
----
-- use XSD::CodeGen::GenSupport.capitalize and unCapitalize instead of my own methods
-- use SOAP::Property.loadproperty
-0% ruby -rpp -rsoap/property -e 'pp
-SOAP::Property.loadproperty("adwords.properties")'
-#<SOAP::Property:0xb7ebd5b8
- @hook={},
- @locked=false,
- @self_hook=[],
- @store=
- {"password"=>"my_very_secret_password",
-  "useragent"=>"P@ playing with the API from ruby",
-  "token"=>"my_token",
-  "email"=>"toto@example.com"}>
-- fix the bug in reports
-- handling quota management in the driver
-- pass in a hash for complex objects
-- comments everywhere, rdoc
-- documentation
-- more samples: traffic_estimator, report,