cannikin-gattica 0.2.0 → 0.3.1

data/History.txt

@@ -1,3 +1,10 @@
+== 0.3.0
+  * Support for filters (filters are all AND'ed together, no OR yet)
+
+== 0.2.1 
+  * More robust error checking on HTTP calls
+  * Added to_xml to get raw XML output from Google
+  
 == 0.2.0 / 2009-04-27
   * Changed initialization format: pass a hash of options rather than individual email, password and profile_id
   * Can initialize with a valid token and use that instead of requiring email/password each time

data/README.rdoc

@@ -71,6 +71,19 @@ also pass in single values as arrays too, if you wish):
                      :metrics => ['pageviews','visits'], 
                      :sort => ['-pageviews']})
                      
+== Filters
+Filters can be pretty complex as far as GA is concerned. You can filter on either dimensions or metrics
+or both. And then your filters can be ANDed together or they can ORed together. There are also rules,
+which are not immediately apparent, about what you can filter and how.
+
+By default filters passed to a +get+ are ANDed together. This means that all filters need to match for
+the result to be returned.
+
+  :filter => ['browser == Firefox','pageviews >= 10000']
+  
+This says "return only results where the 'browser' dimension contains the word 'Firefox' and the
+'pageviews' metric is greater than or equal to 10,000.
+
 == Notes on Authentication
 === Authentication Token
 Google recommends not re-authenticating each time you do a request against the API. To accomplish

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
 :major: 0
-:minor: 2
-:patch: 0
+:minor: 3
+:patch: 1

data/examples/example.rb

@@ -3,7 +3,8 @@ require '../lib/gattica'
 # authenticate with the API via email/password
 ga = Gattica.new({:email => 'username@gmail.com', :password => 'password'})
 
-# or, initialize via a pre-existing token (does not authenticate, but will throw an error on subsequent calls [like ga.accounts] if the token is invalid)
+# or, initialize via a pre-existing token. This initialization does not authenticate immediately, 
+# but will throw an error on subsequent calls (like ga.accounts) if the token is invalid
 # ga = Gattica.new({:token => 'DQAAAJYAAACN-JMelka5I0Fs-T6lF53eUSfUooeHgcKc1iEdc0wkDS3w8GaXY7LjuUB_4vmzDB94HpScrULiweW_xQsU8yyUgdInDIX7ZnHm8_o0knf6FWSR90IoAZGsphpqteOjZ3O0NlNt603GgG7ylvGWRSeHl1ybD38nysMsKJR-dj0LYgIyPMvtgXLrqr_20oTTEExYbrDSg5_q84PkoLHUcODZ' })
 
 # get the list of accounts you have access to with that username and password
@@ -14,15 +15,28 @@ accounts = ga.accounts
 # property you're most used to seeing in GA, looks like UA123456-1)
 ga.profile_id = accounts.first.profile_id
 
-# puts ga.token
+# If you're using Gattica with a web app you'll want to save the authorization token
+# and use that on subsequent requests (Google recommends not re-authenticating each time)
+# ga.token
 
 # now get the number of page views by browser for Janurary 2009
-# note that as of right now, Gattica does not support filtering
 data = ga.get({ :start_date => '2009-01-01', 
                 :end_date => '2009-01-31',
                 :dimensions => ['browser'],
                 :metrics => ['pageviews'],
                 :sort => ['-pageviews'] })
-
-# write the data out as CSV
+           
+# output the data as CSV     
 puts data.to_csv
+
+# a little more complex example with filtering. Show all pageviews by Firefox browsers
+# (any version) where the number of page views is greater than 100
+data = ga.get({ :start_date => '2009-01-01', 
+                :end_date => '2009-01-31',
+                :dimensions => ['browser','browserVersion'],
+                :metrics => ['pageviews'],
+                :sort => ['-pageviews'],
+                :filters => ['browser == Firefox', 'pageviews > 100'] })
+
+# write the data out as CSV in "short" format (doesn't include id, updated or title parameters)
+puts data.to_csv(:short)

data/lib/gattica.rb

@@ -4,9 +4,11 @@ $:.unshift File.dirname(__FILE__) # for use/testing when no gem is installed
 require 'net/http'
 require 'net/https'
 require 'uri'
+require 'cgi'
 require 'logger'
 require 'rubygems'
 require 'hpricot'
+require 'yaml'
 
 # internal
 require 'gattica/core_extensions'
@@ -24,7 +26,7 @@ require 'gattica/data_point'
 
 module Gattica
   
-  VERSION = '0.2.0'
+  VERSION = '0.3.1'
   
   # Creates a new instance of Gattica::Engine and gets us going. Please see the README for usage docs.
   #
@@ -34,8 +36,8 @@ module Gattica
     Engine.new(*args)
   end
   
-  # The real meat of Gattica, deals with talking to GA, returning and parsing results. You automatically
-  # get an instance of this when you go Gattica.new()
+  # The real meat of Gattica, deals with talking to GA, returning and parsing results. You actually get 
+  # an instance of this when you go Gattica.new()
   
   class Engine
     
@@ -44,6 +46,8 @@ module Gattica
     SECURE = true
     DEFAULT_ARGS = { :start_date => nil, :end_date => nil, :dimensions => [], :metrics => [], :filters => [], :sort => [] }
     DEFAULT_OPTIONS = { :email => nil, :password => nil, :token => nil, :profile_id => nil, :debug => false, :headers => {}, :logger => Logger.new(STDOUT) }
+    FILTER_METRIC_OPERATORS = %w{ == != > < >= <= }
+    FILTER_DIMENSION_OPERATORS = %w{ == != =~ !~ =@ ~@ }
     
     attr_reader :user
     attr_accessor :profile_id, :token
@@ -65,7 +69,7 @@ module Gattica
       
       @profile_id = @options[:profile_id]     # if you don't include the profile_id now, you'll have to set it manually later via Gattica::Engine#profile_id=
       @user_accounts = nil                    # filled in later if the user ever calls Gattica::Engine#accounts
-      @headers = {}                           # headers used for any HTTP requests (Google requires a special 'Authorization' header)
+      @headers = {}.merge(@options[:headers]) # headers used for any HTTP requests (Google requires a special 'Authorization' header which is set any time @token is set)
       
       # save an http connection for everyone to use
       @http = Net::HTTP.new(SERVER, PORT)
@@ -73,18 +77,15 @@ module Gattica
       @http.set_debug_output $stdout if @options[:debug]
       
       # authenticate
-      if @options[:email] && @options[:password]      # email and password: authenticate and get a token from Google's ClientLogin
+      if @options[:email] && @options[:password]      # email and password: authenticate, get a token from Google's ClientLogin, save it for later
         @user = User.new(@options[:email], @options[:password])
-        @auth = Auth.new(@http, user, { :source => 'gattica-'+VERSION }, { 'User-Agent' => 'Ruby Net::HTTP' })
+        @auth = Auth.new(@http, user)
         self.token = @auth.tokens[:auth]
-      elsif @options[:token]                          # use an existing token (this also sets the headers for any HTTP requests we make)
+      elsif @options[:token]                          # use an existing token
         self.token = @options[:token]
       else                                            # no login or token, you can't do anything
         raise GatticaError::NoLoginOrToken, 'You must provide an email and password, or authentication token'
       end
-
-      # the user can provide their own additional headers - merge them into the ones that Gattica requires
-      @headers = @headers.merge(@options[:headers])
       
       # TODO: check that the user has access to the specified profile and show an error here rather than wait for Google to respond with a message
     end
@@ -108,12 +109,8 @@ module Gattica
     
     def accounts
       # if we haven't retrieved the user's accounts yet, get them now and save them
-      if @accts.nil?
-        # TODO: move these calls into their own method so we can encapsulate all the errors in one place
-        response, data = @http.get('/analytics/feeds/accounts/default', @headers)
-        if response.code == '401'
-          raise GatticaError::InvalidToken, 'The token you have provided is invalid or has expired'
-        end
+      if @user_accounts.nil?
+        data = do_http_get('/analytics/feeds/accounts/default')
         xml = Hpricot(data)
         @user_accounts = xml.search(:entry).collect { |entry| Account.new(entry) }
       end
@@ -158,23 +155,15 @@ module Gattica
     def get(args={})
       args = validate_and_clean(DEFAULT_ARGS.merge(args))
       query_string = build_query_string(args,@profile_id)
-        @logger.debug(query_string)
-      # TODO: move these calls into their own method so we can encapsulate all the errors in one place
-      response, data = @http.get("/analytics/feeds/data?#{query_string}", @headers)
-      if response.code == '401'
-        raise GatticaError::InvalidToken, 'The token you have provided is invalid or has expired'
-      end
-      begin
-        response.value
-      rescue Net::HTTPServerException => e
-        raise GatticaError::AnalyticsError, data.to_s + " (status code: #{e.message})"
-      end
+        @logger.debug(query_string) if @debug
+      data = do_http_get("/analytics/feeds/data?#{query_string}")
       return DataSet.new(Hpricot.XML(data))
     end
     
     
     # Since google wants the token to appear in any HTTP call's header, we have to set that header
-    # again any time @token is changed
+    # again any time @token is changed so we override the default writer (note that you need to set
+    # @token with self.token= instead of @token=)
     
     def token=(token)
       @token = token
@@ -184,6 +173,29 @@ module Gattica
     
     private
     
+    
+    # Does the work of making HTTP calls and then going through a suite of tests on the response to make
+    # sure it's valid and not an error
+    
+    def do_http_get(query_string)
+      response, data = @http.get(query_string, @headers)
+      
+      # error checking
+      if response.code != '200'
+        case response.code
+        when '400'
+          raise GatticaError::AnalyticsError, response.body + " (status code: #{response.code})"
+        when '401'
+          raise GatticaError::InvalidToken, "Your authorization token is invalid or has expired (status code: #{response.code})"
+        else  # some other unknown error
+          raise GatticaError::UnknownAnalyticsError, response.body + " (status code: #{response.code})"
+        end
+      end
+      
+      return data
+    end
+    
+    
     # Sets up the HTTP headers that Google expects (this is called any time @token is set either by Gattica
     # or manually by the user since the header must include the token)
     def set_http_headers
@@ -209,8 +221,17 @@ module Gattica
           sort[0..0] == '-' ? "-ga:#{sort[1..-1]}" : "ga:#{sort}"  # if the first character is a dash, move it before the ga:
         end.join(',')
       end
+      
+      # TODO: update so that in regular expression filters (=~ and !~), any initial special characters in the regular expression aren't also picked up as part of the operator (doesn't cause a problem, but just feels dirty)
       unless args[:filters].empty?    # filters are a little more complicated because they can have all kinds of modifiers
-        
+        output += '&filters=' + args[:filters].collect do |filter|
+          match, name, operator, expression = *filter.match(/^(\w*)(\W*)(.*)$/)           # splat the resulting Match object to pull out the parts automatically
+          unless name.empty? || operator.empty? || expression.empty?                      # make sure they all contain something
+            "ga:#{name}#{CGI::escape(operator.gsub(/ /,''))}#{CGI::escape(expression)}"   # remove any whitespace from the operator before output
+          else
+            raise GatticaError::InvalidFilter, "The filter '#{filter}' is invalid. Filters should look like 'browser == Firefox' or 'browser==Firefox'"
+          end
+        end.join(';')
       end
       return output
     end
@@ -224,13 +245,26 @@ module Gattica
       raise GatticaError::TooManyDimensions, 'You can only have a maximum of 7 dimensions' if args[:dimensions] && (args[:dimensions].is_a?(Array) && args[:dimensions].length > 7)
       raise GatticaError::TooManyMetrics, 'You can only have a maximum of 10 metrics' if args[:metrics] && (args[:metrics].is_a?(Array) && args[:metrics].length > 10)
       
+      possible = args[:dimensions] + args[:metrics]
+      
       # make sure that the user is only trying to sort fields that they've previously included with dimensions and metrics
       if args[:sort]
-        possible = args[:dimensions] + args[:metrics]
         missing = args[:sort].find_all do |arg|
           !possible.include? arg.gsub(/^-/,'')    # remove possible minuses from any sort params
         end
-        raise GatticaError::InvalidSort, "You are trying to sort by fields that are not in the available dimensions or metrics: #{missing.join(', ')}" unless missing.empty?
+        unless missing.empty?
+          raise GatticaError::InvalidSort, "You are trying to sort by fields that are not in the available dimensions or metrics: #{missing.join(', ')}"
+        end
+      end
+      
+      # make sure that the user is only trying to filter fields that are in dimensions or metrics
+      if args[:filters]
+        missing = args[:filters].find_all do |arg|
+          !possible.include? arg.match(/^\w*/).to_s    # get the name of the filter and compare
+        end
+        unless missing.empty?
+          raise GatticaError::InvalidSort, "You are trying to filter by fields that are not in the available dimensions or metrics: #{missing.join(', ')}"
+        end
       end
       
       return args

data/lib/gattica/auth.rb

@@ -10,23 +10,36 @@ module Gattica
     include Convertible
 
     SCRIPT_NAME = '/accounts/ClientLogin'
-    HEADERS = { 'Content-Type' => 'application/x-www-form-urlencoded' }
-    OPTIONS = { :source => '', :service => 'analytics' }
-  
-    attr_reader :response, :data, :tokens, :token
+    HEADERS = { 'Content-Type' => 'application/x-www-form-urlencoded', 'User-Agent' => 'Ruby Net::HTTP' }   # Google asks that you be nice and provide a user-agent string
+    OPTIONS = { :source => 'gattica-'+VERSION, :service => 'analytics' }                                    # Google asks that you provide the name of your app as a 'source' parameter in your POST
+
+    attr_reader :tokens
   
-    # Prepare the user info along with options and header
-    def initialize(http, user, options={}, headers={})
-      data = OPTIONS.merge(options)
-      data = data.merge(user.to_h)
-      headers = HEADERS.merge(headers)
-    
-      @response, @data = http.post(SCRIPT_NAME, data.to_query, headers)
-      @tokens = parse_tokens(@data)
+    # Try to authenticate the user
+    def initialize(http, user)
+      options = OPTIONS.merge(user.to_h)
+      
+      response, data = http.post(SCRIPT_NAME, options.to_query, HEADERS)
+      if response.code != '200'
+        case response.code
+        when '403'
+          raise GatticaError::CouldNotAuthenticate, 'Your email and/or password is not recognized by the Google ClientLogin system (status code: 403)'
+        else
+          raise GatticaError::UnknownAnalyticsError, response.body + " (status code: #{response.code})"
+        end
+      end
+      @tokens = parse_tokens(data)
     end
   
+  
     private
-    # Parse the authentication tokens out of the response
+    
+    # Parse the authentication tokens out of the response and makes them available as a hash
+    #
+    # tokens[:auth] => Google requires this for every request (added to HTTP headers on GET requests)
+    # tokens[:sid]  => Not used
+    # tokens[:lsid] => Not used
+    
     def parse_tokens(data)
       tokens = {}
       data.split("\n").each do |t|

data/lib/gattica/convertible.rb

@@ -24,5 +24,16 @@ module Gattica
       to_h.to_query
     end
     
+    # Return the raw XML (if the object has a @xml instance variable, otherwise convert the object itself to xml)
+    def to_xml
+      if @xml
+        @xml
+      else
+        self.to_xml
+      end
+    end
+    
+    alias to_yml to_yaml
+    
   end
 end

data/lib/gattica/core_extensions.rb

@@ -14,5 +14,12 @@ class Hash
   def value
     self.values.first if self.length == 1
   end
+  
+  def stringify_keys
+    inject({}) do |options, (key, value)|
+      options[key.to_s] = value
+      options
+    end
+  end
 
 end

data/lib/gattica/data_point.rb

@@ -47,6 +47,15 @@ module Gattica
       return output
     end
     
+    
+    def to_yaml
+      { 'id' => @id,
+        'updated' => @updated,
+        'title' => @title,
+        'dimensions' => @dimensions,
+        'metrics' => @metrics }.to_yaml
+    end
+    
   end
   
 end

data/lib/gattica/data_set.rb

@@ -32,14 +32,16 @@ module Gattica
         output = '"id","updated","title",'
       end
       
-      output += @points.first.dimensions.collect do |dimension|
-        "\"#{dimension.key.to_s}\""
-      end.join(',')
-      output += ','
-      output += @points.first.metrics.collect do |metric|
-        "\"#{metric.key.to_s}\""
-      end.join(',') 
-      output += "\n"
+      unless @points.empty?   # if there was at least one result
+        output += @points.first.dimensions.collect do |dimension|
+          "\"#{dimension.key.to_s}\""
+        end.join(',')
+        output += ','
+        output += @points.first.metrics.collect do |metric|
+          "\"#{metric.key.to_s}\""
+        end.join(',') 
+        output += "\n"
+      end
       
       # get the data from each point
       @points.each do |point|
@@ -49,6 +51,16 @@ module Gattica
       return output
     end
     
+    
+    def to_yaml
+      { 'total_results' => @total_results,
+        'start_index' => @start_index,
+        'items_per_page' => @items_per_page,
+        'start_date' => @start_date,
+        'end_date' => @end_date,
+        'points' => @points}.to_yaml
+    end
+    
   end
   
 end

data/lib/gattica/exceptions.rb

@@ -17,4 +17,5 @@ module GatticaError
   class MissingEndDate < StandardError; end;
   # errors from Analytics
   class AnalyticsError < StandardError; end;
+  class UnknownAnalyticsError < StandardError; end;
 end

data/lib/gattica/user.rb

@@ -6,10 +6,9 @@ module Gattica
   
     include Convertible
   
-    SERVICE = 'analytics'
     attr_accessor :email, :password
   
-    def initialize(email,password,source='')
+    def initialize(email,password)
       @email = email
       @password = password
       validate

data/test/test_engine.rb

@@ -6,7 +6,7 @@ class TestEngine < Test::Unit::TestCase
   end
   
   def test_initialization
-    assert Gattica.new({:email => 'anonymous@anon.com', :password => 'none'}) # you can initialize with a potentially invalid email and password
+    # assert Gattica.new({:email => 'anonymous@anon.com', :password => 'none'}) # you can initialize with a potentially invalid email and password
     assert Gattica.new({:token => 'test'})                                    # you can initialize with a potentially invalid token
     assert_raise GatticaError::NoLoginOrToken do Gattica.new() end            # but, you must initialize with one or the other
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: cannikin-gattica
 version: !ruby/object:Gem::Version 
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors: 
 - Rob Cameron
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-04-27 00:00:00 -07:00
+date: 2009-05-01 00:00:00 -07:00
 default_executable: 
 dependencies: []