comscore_ruby 0.0.20 → 0.0.21

data/README.markdown

@@ -0,0 +1,81 @@
+# comscore_ruby
+
+## what is it
+comscore_ruby is a minimal Ruby wrapper to [comScore's SOAP API](https://api.comscore.com).  It follows a design policy similar to that of [sucker](https://rubygems.org/gems/sucker) built for Amazon's API.
+
+comScore's API is closed, you have to be a paying customer in order to access the data.
+
+## installation
+    [sudo] gem install comscore_ruby
+
+## initialization and authentication
+comScore uses basic HTTP authentication so just provide your regular login details.
+
+    client = ComScore::Client.new(
+      username,
+      password,
+      :log => false,
+      :wait_time => 1
+    )
+    
+## usage
+There are only two core methods for the client which doesn't try to "over architect a spaghetti API":
+
+* `get_report` - used to...while get reports and
+* `request` - more generic used to make any kind of request
+
+For reference, I'd recommend keeping [comScore's SOAP API](https://api.comscore.com) open as you code to understand what services you have available to you.  Also ask them for their initial documentation which is absolutely horrible but at least their engineering staff is pretty helpful.
+
+The response returned by either of these requests is actually a [savon](http://savonrb.com/) [request object](http://rubydoc.info/gems/savon/0.9.7/Savon/Client#request-instance_method) to allow for maximum flexibility.  You can do things with this that are particularly nice:
+
+* `response.to_hash` which works well in most cases but has been known to be buggy with XML attributes (at least in Ruby 1.8.x)
+* `response.doc` the Nokogiri XML document to allow for some pretty advanced XPATH
+
+9x out of 10 you'll be able to use to_hash on a response but you will sometimes have need to query with XPATH due to how `to_hash` parses certain XML attributes in comScore's results.
+
+## examples
+    # Find all media within the Canadian dictionary (from 2 months ago) that match "The Globe And Mail"
+    client.request(:key_measures, :fetch_media) do |xml|
+      xml.parameterId("media")
+      xml.fetchMediaQuery("xmlns" => "http://comscore.com/FetchMedia") {
+        xml.SearchCritera(:ExactMatch => "false", :Critera => "The Globe And Mail")
+      }
+      xml.reportQuery("xmlns" => "http://comscore.com/ReportQuery") {
+        xml.Parameter(:KeyId => "geo", :Value => ComScore::GEOGRAPHIES["Canada"])
+        xml.Parameter(:KeyId => "loc", :Value => ComScore::LOCATIONS["Home and Work"])
+        xml.Parameter(:KeyId => "timeType", :Value => ComScore::TIME_TYPES["Months"])
+        xml.Parameter(:KeyId => "timePeriod", :Value => DateTime.now.to_date.to_comscore_time_period - 2)
+        xml.Parameter(:KeyId => "mediaSetType", :Value => ComScore::MEDIA_SET_TYPES["Ranked Categories"])
+      }
+    end
+    
+    # Find all the categories (or media sets) within the Canadian dictionary (from 2 months ago)
+    client.request(:key_measures, :discover_parameter_values) do |xml|
+      xml.parameterId("mediaSet")
+      xml.query(:xmlns => "http://comscore.com/ReportQuery") {
+        xml.Parameter(:KeyId => "geo", :Value => ComScore::GEOGRAPHIES["Canada"])
+        xml.Parameter(:KeyId => "timeType", :Value => ComScore::TIME_TYPES["Months"])
+        xml.Parameter(:KeyId => "timePeriod", :Value => DateTime.now.to_date.to_comscore_time_period - 2)
+        xml.Parameter(:KeyId => "mediaSetType", :Value => ComScore::MEDIA_SET_TYPES["Ranked Categories"])
+      }
+    end
+    
+    # Get a key measures report for the Community - Lifestyles category (778226) for August, 2011
+    client.get_report(:key_measures,
+      :geo => ComScore::GEOGRAPHIES["Canada"],
+      :loc => ComScore::LOCATIONS["Home and Work"],
+      :timeType => ComScore::TIME_TYPES["Months"],
+      :timePeriod => Date.new(2011, 8),
+      :mediaSet => 778226,
+      :mediaSetType => ComScore::MEDIA_SET_TYPES["Ranked Categories"],
+      :targetType => ComScore::TARGET_TYPES["Simple"],
+      :targetGroup => ComScore::TARGET_GROUPS["Total Audience"],
+      :measure => [ComScore::MEASURES["Total Unique Visitors (000)"]]
+    )
+
+## todo
+* More support for other parameters: geographies, locations etc.  I'm Canadian, so I really only built it for the parameters I use and know of.
+* Passing of a hash to the initializer for config options including username and password so you don't have to awkwardly set logging off after initialization.
+
+## see also
+My other client library [romniture](https://github.com/msukmanowsky/ROmniture) for those of you looking to pull data from Omniture as well.

data/lib/comscore_ruby/client.rb

@@ -18,8 +18,13 @@ module ComScore
       :mobilens_trend       => {:wsdl => "#{BASE_URI}MobiLens/Trend.asmx?WSDL"}
     }
     
-    def initialize(uname, pw)
-      @username, @password = [uname, pw]
+    def initialize(username, password, options={})
+      @username   = username
+      @password   = password
+      @wait_time  = options[:wait_time] ? options[:wait_time] : DEFAULT_REPORT_WAIT_TIME
+      self.log    = options[:log] ? options[:log] : false
+      
+      
       @client = Savon::Client.new
       @client.http.auth.basic(@username, @password)
     end

data/lib/comscore_ruby/version.rb

@@ -1,3 +1,3 @@
 module ComScore
-  VERSION = "0.0.20"
+  VERSION = "0.0.21"
 end

data/test/client_test.rb

@@ -9,8 +9,7 @@ class ClientTest < Test::Unit::TestCase
   def setup
     @config = YAML::load(File.open("test/config.yml"))["comscore"]
     
-    @client = ComScore::Client.new(@config["username"], @config["password"])
-    @client.log = false
+    @client = ComScore::Client.new(@config["username"], @config["password"], :log => false, :wait_time => 1)
   end
   
   def test_fetch_media

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: comscore_ruby
 version: !ruby/object:Gem::Version 
-  hash: 55
+  hash: 53
   prerelease: 
   segments: 
   - 0
   - 0
-  - 20
-  version: 0.0.20
+  - 21
+  version: 0.0.21
 platform: ruby
 authors: 
 - Mike Sukmanowsky
@@ -15,7 +15,8 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-09-16 00:00:00 Z
+date: 2011-09-18 00:00:00 -04:00
+default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: savon
@@ -59,6 +60,7 @@ extra_rdoc_files: []
 files: 
 - .gitignore
 - Gemfile
+- README.markdown
 - Rakefile
 - comscore_ruby.gemspec
 - lib/comscore_ruby.rb
@@ -67,6 +69,7 @@ files:
 - lib/comscore_ruby/core_ext/date.rb
 - lib/comscore_ruby/version.rb
 - test/client_test.rb
+has_rdoc: true
 homepage: https://github.com/msukmanowsky/comscore_ruby/wiki
 licenses: []
 
@@ -96,7 +99,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: comscore_ruby
-rubygems_version: 1.8.4
+rubygems_version: 1.5.0
 signing_key: 
 specification_version: 3
 summary: Use comScore's SOAP API in a manner that does not require you to bang your head against a wall.