rugalytics 0.0.1

data/CHANGELOG

@@ -0,0 +1,3 @@
+v0.1.0. initial release
+
+v0.0.0. forked from Statwhore http://github.com/jnunemaker/statwhore

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Rob McKinnon
+Copyright (c) 2007 John Nunemaker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/Manifest

@@ -0,0 +1,24 @@
+CHANGELOG
+lib/rugalytics/account.rb
+lib/rugalytics/analytics.rb
+lib/rugalytics/connection.rb
+lib/rugalytics/graph.rb
+lib/rugalytics/item.rb
+lib/rugalytics/profile.rb
+lib/rugalytics/report.rb
+lib/rugalytics.rb
+LICENSE
+Manifest
+README
+README.rdoc
+spec/fixtures/analytics_account_find_all.html
+spec/fixtures/analytics_profile_find_all.html
+spec/fixtures/dashboard_report_webgroup.xml
+spec/lib/rugalytics/account_spec.rb
+spec/lib/rugalytics/graph_spec.rb
+spec/lib/rugalytics/item_spec.rb
+spec/lib/rugalytics/profile_spec.rb
+spec/lib/rugalytics/report_spec.rb
+spec/lib/rugalytics_spec.rb
+spec/spec.opts
+spec/spec_helper.rb

data/README

@@ -0,0 +1,128 @@
+Rugalytics is a Ruby API for Google Analytics.
+
+= Warning - API under development
+
+The Rugalytics API is in early development so it may change slightly over time.
+It should be in working order, so please give it a test spin!
+
+The source code is hosted at github. Feel free to fork the code if you have
+something to contribute:
+
+ http://github.com/robmckinnon/rugalytics
+
+
+== Install as a Gem
+
+Should be up at rubyforge, so to install:
+
+ sudo gem install rugalytics
+
+
+== Authenticate
+
+Login with your Google Analytics user name and password:
+
+ require 'rugalytics'
+
+ Rugalytics.login 'username', 'password'
+
+
+== Obtain Profile
+
+Get profile using account name and profile name:
+
+ profile = Rugalytics.find_profile('your_site.com', 'blog.your_site.com')
+
+
+If account name and profile name are the same:
+
+ profile = Rugalytics.find_profile('your_site.com')
+
+
+== Get Profile Summary Statistics
+
+Obtaining page views:
+
+ profile.pageviews # default period is one month ending today
+ => 160600
+
+ profile.pageviews :from=>'2007-01-01'
+ => 2267550
+
+ profile.pageviews :from=>'2007-01-01', :to=>'2007-01-02'
+ => 24980
+
+The +pageviews+ method is doing this under the hood:
+
+ report = profile.load_report('Pageviews', :from=>'2007-01-01', :to=>'2007-01-02')
+
+ report.page_views_total
+ => 24980
+
+And under the hood, the +page_views_total+ method is actually calling:
+
+ report.page_views_graph.sum_of_points
+ => 24980
+
+== Load a Report
+
+The report name, e.g. 'Pageviews' or 'TrafficSources', is the rpt parameter from
+the Google Analytics URL for a CSV report export, e.g.:
+
+ https://www.google.com/analytics/reporting/export?fmt=2&...&&rpt=TrafficSourcesReport&...
+
+From a page on the Analytics website, you can find the CSV URL by clicking on
+the Export tab, and then mousing over the CSV option.
+
+Let's load the TrafficSources report:
+
+ report = profile.load_report 'TrafficSources'
+
+ report.report_name
+ => "Traffic Sources Overview"
+
+ report.start_date
+ => "28 May 2008"
+
+ report.end_date
+ => "4 June 2008"
+
+ report.source_items.collect{|s| "#{s.sources}: #{s.visits}"}.first
+ => "google (organic): 15210"
+
+ report.keyword_items.collect{|k| "#{k.keywords}: #{k.visits}"}[1]
+ => "oecd nz report summary 2007: 14"
+
+Let's try another report, VisitorsOverview:
+
+ report = profile.load_report 'VisitorsOverview'
+
+ report.browser_items[1]
+ => #<Rugalytics::Item @percentage_visits="0.18", @visits="3140", @browser="Firefox">
+
+ report.connection_speed_items[3]
+ => #<Rugalytics::Item @connection_speed="Dialup", @percentage_visits="0.06340057402849197", @visits="1100">
+
+Let's now grab 100 lines of the Networks report:
+
+ report = profile.load_report 'Networks', :rows=>100
+
+ report.items.size
+ => 100
+
+ report.items.first.network_location
+ => "telecom xtra"
+
+
+==Acknowledgements
+
+Rugalytics started life as a fork of jnunemaker's Statwhore. As the code and
+project scope began to diverge significantly from Statwhore, a new project was
+initiated.
+
+Rugalytics makes use of the Morph gem to emerge Ruby class definitions at
+runtime based on the contents of the CSV reports from Google Analytics.
+
+==License
+
+See LICENSE for the terms of this software.

data/README.rdoc

@@ -0,0 +1,128 @@
+Rugalytics is a Ruby API for Google Analytics.
+
+= Warning - API under development
+
+The Rugalytics API is in early development so it may change slightly over time.
+It should be in working order, so please give it a test spin!
+
+The source code is hosted at github. Feel free to fork the code if you have
+something to contribute:
+
+ http://github.com/robmckinnon/rugalytics
+
+
+== Install as a Gem
+
+Should be up at rubyforge, so to install:
+
+ sudo gem install rugalytics
+
+
+== Authenticate
+
+Login with your Google Analytics user name and password:
+
+ require 'rugalytics'
+
+ Rugalytics.login 'username', 'password'
+
+
+== Obtain Profile
+
+Get profile using account name and profile name:
+
+ profile = Rugalytics.find_profile('your_site.com', 'blog.your_site.com')
+
+
+If account name and profile name are the same:
+
+ profile = Rugalytics.find_profile('your_site.com')
+
+
+== Get Profile Summary Statistics
+
+Obtaining page views:
+
+ profile.pageviews # default period is one month ending today
+ => 160600
+
+ profile.pageviews :from=>'2007-01-01'
+ => 2267550
+
+ profile.pageviews :from=>'2007-01-01', :to=>'2007-01-02'
+ => 24980
+
+The +pageviews+ method is doing this under the hood:
+
+ report = profile.load_report('Pageviews', :from=>'2007-01-01', :to=>'2007-01-02')
+
+ report.page_views_total
+ => 24980
+
+And under the hood, the +page_views_total+ method is actually calling:
+
+ report.page_views_graph.sum_of_points
+ => 24980
+
+== Load a Report
+
+The report name, e.g. 'Pageviews' or 'TrafficSources', is the rpt parameter from
+the Google Analytics URL for a CSV report export, e.g.:
+
+ https://www.google.com/analytics/reporting/export?fmt=2&...&&rpt=TrafficSourcesReport&...
+
+From a page on the Analytics website, you can find the CSV URL by clicking on
+the Export tab, and then mousing over the CSV option.
+
+Let's load the TrafficSources report:
+
+ report = profile.load_report 'TrafficSources'
+
+ report.report_name
+ => "Traffic Sources Overview"
+
+ report.start_date
+ => "28 May 2008"
+
+ report.end_date
+ => "4 June 2008"
+
+ report.source_items.collect{|s| "#{s.sources}: #{s.visits}"}.first
+ => "google (organic): 15210"
+
+ report.keyword_items.collect{|k| "#{k.keywords}: #{k.visits}"}[1]
+ => "oecd nz report summary 2007: 14"
+
+Let's try another report, VisitorsOverview:
+
+ report = profile.load_report 'VisitorsOverview'
+
+ report.browser_items[1]
+ => #<Rugalytics::Item @percentage_visits="0.18", @visits="3140", @browser="Firefox">
+
+ report.connection_speed_items[3]
+ => #<Rugalytics::Item @connection_speed="Dialup", @percentage_visits="0.06340057402849197", @visits="1100">
+
+Let's now grab 100 lines of the Networks report:
+
+ report = profile.load_report 'Networks', :rows=>100
+
+ report.items.size
+ => 100
+
+ report.items.first.network_location
+ => "telecom xtra"
+
+
+==Acknowledgements
+
+Rugalytics started life as a fork of jnunemaker's Statwhore. As the code and
+project scope began to diverge significantly from Statwhore, a new project was
+initiated.
+
+Rugalytics makes use of the Morph gem to emerge Ruby class definitions at
+runtime based on the contents of the CSV reports from Google Analytics.
+
+==License
+
+See LICENSE for the terms of this software.

data/lib/rugalytics/account.rb

@@ -0,0 +1,42 @@
+module Rugalytics
+  class Account < ::Google::Base
+
+    class << self
+      def find_all
+        doc = Hpricot::XML get('https://www.google.com:443/analytics/home/')
+        (doc/'select[@name=account_list] option').inject([]) do |accounts, option|
+          account_id = option['value'].to_i
+          accounts << new(:account_id => account_id, :name => option.inner_html) if account_id > 0
+          accounts
+        end
+      end
+
+      def find account_id_or_name
+        matchs = find_all.select{|a| a.name == account_id_or_name || a.account_id.to_s == account_id_or_name.to_s }
+        matchs.empty? ? nil : matchs.first
+      end
+    end
+
+    attr_accessor :name, :account_id
+
+    def initialize(attrs)
+      @name = attrs[:name]
+      @account_id = attrs[:account_id]
+    end
+
+    def profiles(force=false)
+      if force || @profiles.nil?
+        @profiles = Profile.find_all(account_id)
+      end
+      @profiles
+    end
+
+    def find_profile profile_id_or_name
+      profiles.detect { |p| p.profile_id.to_s == profile_id_or_name.to_s || p.name == profile_id_or_name }
+    end
+
+    def to_s
+      "#{name} (#{account_id})"
+    end
+  end
+end

data/lib/rugalytics/connection.rb

@@ -0,0 +1,39 @@
+require 'net/https'
+
+module Rugalytics
+  class Connection
+    def initialize(base_url, args = {})
+      @base_url = base_url
+      @username = args[:username]
+      @password = args[:password]
+    end
+
+    def get(resource, args = nil)
+      request(resource, "get", args)
+    end
+
+    def post(resource, args = nil)
+      request(resource, "post", args)
+    end
+
+    def request(resource, method = "get", args = nil)
+      url = URI.join(@base_url, resource)
+      url.query = args.map { |k,v| "%s=%s" % [URI.encode(k.to_s), URI.encode(v.to_s)] }.join("&") if args
+
+      case method
+      when "get"
+        req = Net::HTTP::Get.new(url.request_uri)
+      when "post"
+        req = Net::HTTP::Post.new(url.request_uri)
+      end
+
+      req.basic_auth(@username, @password) if @username && @password
+
+      http = Net::HTTP.new(url.host, url.port)
+      http.use_ssl = (url.port == 443)
+
+      res = http.start() { |conn| conn.request(req) }
+      res.body
+    end
+  end
+end

data/lib/rugalytics/graph.rb

@@ -0,0 +1,31 @@
+module Rugalytics
+  class Graph
+
+    attr_reader :name, :points, :from, :to
+
+    def initialize name, period, points
+      @name = name
+      @period = period
+      dates = @period.split('-')
+      unless dates.empty?
+        @from = Date.parse(dates[0].strip)
+        @to = Date.parse(dates[1].strip)
+      end
+      @points = points
+    end
+
+    def sum_of_points
+      points.sum
+    end
+
+    def points_by_day
+      by_day = []
+      index = 0
+      from.upto(to) do |date|
+        by_day << [date, points[index] ]
+        index = index.next
+      end
+      by_day
+    end
+  end
+end

data/lib/rugalytics/item.rb

@@ -0,0 +1,19 @@
+module Rugalytics
+
+  class Item
+    include Morph
+
+    def initialize attributes, values, base_url
+      attributes.each_with_index do |attribute, index|
+        attribute.sub!('$','dollar')
+        attribute.sub!('/',' per ')
+        attribute.sub!('.',' ')
+        value = values[index]
+        morph(attribute, value)
+      end
+
+      self.url = "http://#{base_url}#{url}" if respond_to?(:url)
+    end
+  end
+
+end

data/lib/rugalytics/profile.rb

@@ -0,0 +1,116 @@
+module Rugalytics
+  class Profile < ::Google::Base
+
+    class << self
+      def find_all(account_id)
+        doc = Hpricot::XML get("https://www.google.com:443/analytics/home/admin?scid=#{account_id}")
+        (doc/'select[@name=profile_list] option').inject([]) do |profiles, option|
+          profile_id = option['value'].to_i
+          profiles << Profile.new(:account_id => account_id, :profile_id => profile_id, :name => option.inner_html) if profile_id > 0
+          profiles
+        end
+      end
+
+      def find(account_id_or_name, profile_id_or_name=nil)
+        profile_id_or_name = account_id_or_name unless profile_id_or_name
+        account = Account.find(account_id_or_name)
+        account ? account.find_profile(profile_id_or_name) : nil
+      end
+    end
+
+    attr_accessor :account_id, :name, :profile_id
+
+    def initialize(attrs)
+      raise ArgumentError, ":profile_id is required" unless attrs.has_key?(:profile_id)
+      @account_id = attrs[:account_id]  if attrs.has_key?(:account_id)
+      @name       = attrs[:name]        if attrs.has_key?(:name)
+      @profile_id = attrs[:profile_id]  if attrs.has_key?(:profile_id)
+    end
+
+    def load_report(name, options={})
+      report = Rugalytics::Report.new report(options.merge({:report=>name}))
+      puts report.attribute_names
+      report
+    end
+
+    def report(options={})
+      options.reverse_merge!({
+        :report  => 'Dashboard',
+        :from    => Time.now.utc - 7.days,
+        :to      => Time.now.utc,
+        :tab     => 0,
+        :format  => FORMAT_CSV,
+        :rows    => 50,
+        :compute => 'average',
+        :gdfmt   => 'nth_day',
+        :view    => 0
+      })
+      options[:from] = ensure_datetime_in_google_format(options[:from])
+      options[:to]   = ensure_datetime_in_google_format(options[:to])
+
+      params = {
+        :pdr  => "#{options[:from]}-#{options[:to]}",
+        :rpt  => "#{options[:report]}Report",
+        :cmp  => options[:compute],
+        :fmt  => options[:format],
+        :view => options[:view],
+        :tab  => options[:tab],
+        :trows=> options[:rows],
+        :gdfmt=> options[:gdfmt],
+        :id   => profile_id,
+      }
+      puts params.inspect
+      # https://www.google.com/analytics/reporting/export?fmt=2&id=1712313&pdr=20080504-20080603&cmp=average&&rpt=PageviewsReport
+      self.class.get("https://google.com/analytics/reporting/export", :query_hash => params)
+    end
+
+    def pageviews(options={})
+      load_report('Pageviews',options).page_views_total
+    end
+
+    def pageviews_by_day(options={})
+      load_report('Pageviews',options).page_views_by_day
+    end
+
+    def visits(options={})
+      load_report('Visits',options).visits_total
+    end
+
+    def visits_by_day(options={})
+      load_report('Visits',options).visits_by_day
+    end
+
+    # takes a Date, Time or String
+    def ensure_datetime_in_google_format(time)
+      time = Date.parse(time) if time.is_a?(String)
+      time.is_a?(Time) || time.is_a?(Date) ? time.strftime('%Y%m%d') : time
+    end
+
+    def to_s
+      "#{name} (#{profile_id})"
+    end
+
+    private
+      def get_item_summary_by_message(options={})
+        raise ArgumentError unless options.has_key?(:message)
+        message = options.delete(:message).to_s.capitalize
+        response = report(options.merge({:report => 'Dashboard'}))
+        doc = Hpricot::XML(response)
+        pageviews = (doc/:ItemSummary).detect { |summary| summary.at('Message').inner_html == message }
+        pageviews && pageviews.at('SummaryValue') ? pageviews.at('SummaryValue').inner_html.gsub(/\D/, '').to_i : 0
+      end
+
+      def get_serie_by_label(options={})
+        raise ArgumentError unless options.has_key?(:label)
+        label = options.delete(:label).to_s.capitalize
+        response = report(options.merge({:report => 'Dashboard'}))
+        doc = Hpricot::XML(response)
+        serie = (doc/:Serie).detect { |serie| serie.at('Label').inner_html == label }
+        if serie
+          (serie/:Point).inject([]) { |collection, point| collection << [Date.parse(point.at('Label').inner_html), point.at('Value').inner_html.to_i] }
+        else
+          []
+        end
+      end
+  end
+end

data/lib/rugalytics/report.rb

@@ -0,0 +1,97 @@
+module Rugalytics
+
+  class Report
+
+    include MorphLessMethodMissing
+
+    attr_reader :base_url, :report_name, :start_date, :end_date
+
+    def initialize csv=''
+      return if csv.empty?
+      lines = csv.split("\n")
+      set_attributes lines
+      handle_graphs lines
+      handle_tables lines
+    end
+
+    def attribute_names
+      Report.morph_methods.select {|m| m[/[a-z]$/]}.select {|m| send(m.to_sym)}
+    end
+
+    def method_missing symbol, *args
+
+      if is_writer = symbol.to_s[/=$/]
+        morph_method_missing(symbol, *args)
+
+      elsif symbol.to_s.match /(.*)_(total|by_day)/
+        graph = "#{$1}_graph".to_sym
+
+        if respond_to?(graph)
+          $2 == 'total' ? send(graph).sum_of_points : send(graph).points_by_day
+        else
+          super
+        end
+
+      else
+        super
+      end
+    end
+
+    private
+
+    def set_attributes lines
+      @base_url = lines[1]
+      @report_name = lines[2].chomp(',')
+      dates = lines[3].split(',')
+      @start_date = dates[0]
+      @end_date = dates[1]
+    end
+
+    def handle_graphs lines
+      index = 5
+      while index < lines.size
+        while (lines[index][/^# Graph/].nil? || lines[index].strip.size == 0)
+          index = index.next
+          return if index == lines.size
+        end
+        index = index + 2
+        period = lines[index]
+        index = index.next
+        name = lines[index]
+        index = index.next
+
+        points = []
+        while (point = lines[index]) && point.strip.size > 0
+          points << point.tr('",','').to_i
+          index = index.next
+        end
+
+        graph = Graph.new name, period, points
+        morph("#{name} graph", graph)
+      end
+    end
+
+    def handle_tables lines
+      index = 5
+      while index < lines.size
+        while (lines[index][/^# .*Table/].nil? || lines[index].strip.size == 0)
+          index = index.next
+          return if index == lines.size
+        end
+        type = lines[index][/^# (.*)MiniTable/,1]
+        index = index + 2
+        attributes = lines[index].split(',')
+        index = index.next
+
+        items = []
+        items_attribute = (type && type.size > 0) ? "#{type.gsub(/([a-z])([A-Z])/, '\1_\2').downcase}_items" : 'items'
+        morph(items_attribute, items)
+
+        while (values = lines[index]) && values[/^# -/].nil? && values.strip.size > 0
+          items << Item.new(attributes, values.split(','), base_url)
+          index = index.next
+        end
+      end
+    end
+  end
+end