Added documentation and update README with info of analytics.

zigotto · Jan 18, 2011 · fa168ec · fa168ec
1 parent 7cd86b5
commit fa168ec
Show file tree

Hide file tree

Showing 8 changed files with 156 additions and 6 deletions.
diff --git a/README.rdoc b/README.rdoc
@@ -44,6 +44,63 @@ Go to http://goo.gl to see URL statistics.
 
   TODO
 
+== Analytics
+
+Expands a short URL or gets creation time and analytics
+
+For analytics and additional information to return (using the :projection parameter)
+
+  :full                    returns the creation timestamp and all available analytics
+  :analytics_clicks        returns only click counts
+  :analytics_top_strings   returns only top string counts (e.g. referrers, countries, etc)
+
+=== Get Analytics
+
+  url = Googl.expand('http://goo.gl/DWDfi', :projection => :full)
+
+  url.analytics.all_time.browsers.first.label
+  => "Chrome"
+  url.analytics.all_time.browsers.first.count
+  => "11"
+
+A summary of the click analytics for the short and long URL
+
+  url.analytics
+
+Analytics details for a particular window of time; counts in this object are of clicks that occurred within the most recent window of this length.
+
+  url.analytics.all_time
+  url.analytics.month
+  url.analytics.week
+  url.analytics.day
+  url.analytics.two_hours
+
+Number of clicks on this short URL. Replace (*) for all_time, month, week, day or two_hours
+
+  url.analytics.*.short_url_clicks
+
+Number of clicks on all goo.gl short URLs pointing to this long URL.
+
+  url.analytics.*.long_url_clicks
+
+Top referring hosts, e.g. "www.google.com"; sorted by (descending) click counts. Only present if this data is available.
+
+  url.analytics.*.referrers
+
+Top countries (expressed as country codes), e.g. "US" or "DE"; sorted by (descending) click counts.
+
+  url.analytics.*.countries
+
+Top browsers, e.g. "Chrome"; sorted by (descending) click counts.
+
+  url.analytics.*.browsers
+
+Top platforms or OSes, e.g. "Windows"; sorted by (descending) click counts.
+
+  url.analytics.*.platforms
+
+For details, see http://code.google.com/intl/pt-BR/apis/urlshortener/v1/reference.html#resource_url
+
 == Installation
 
   gem install googl

diff --git a/lib/googl.rb b/lib/googl.rb
@@ -10,17 +10,90 @@
 
 module Googl
 
+  # Creates a new short URL
+  #
+  #   url = Googl.shorten('http://www.zigotto.com')
+  #   url.short_url
+  #   => "http://goo.gl/ump4S"
+  #
   def self.shorten(url=nil)
     raise ArgumentError.new("URL to shorten is required") if url.blank?
     Googl::Shorten.new(url)
   end
 
+  # Expands a short URL or gets creation time and analytics
+  #
+  #   url = Googl.expand('http://goo.gl/ump4S')
+  #   url.long_url
+  #   => "http://www.zigotto.com/"
+  #
+  # For analytics and additional information to return (using the :projection parameter)
+  #
+  #   * :full => returns the creation timestamp and all available analytics
+  #   * :analytics_clicks => returns only click counts
+  #   * :analytics_top_strings => returns only top string counts (e.g. referrers, countries, etc)
+  #
+  #   url = Googl.expand('http://goo.gl/DWDfi', :projection => :full)
+  #
+  #   url.analytics.all_time.browsers.first.label
+  #   => "Chrome"
+  #   url.analytics.all_time.browsers.first.count
+  #   => "11"
+  #
+  # A summary of the click analytics for the short and long URL
+  #
+  #   url.analytics
+  #
+  # Analytics details for a particular window of time; counts in this object are of clicks that occurred within the most recent window of this length.
+  #
+  #   url.analytics.all_time
+  #   url.analytics.month
+  #   url.analytics.week
+  #   url.analytics.day
+  #   url.analytics.two_hours
+  #
+  # Number of clicks on this short URL. Replace (*) for all_time, month, week, day or two_hours
+  #
+  #   url.analytics.*.short_url_clicks
+  #
+  # Number of clicks on all goo.gl short URLs pointing to this long URL.
+  #
+  #   url.analytics.*.long_url_clicks
+  #
+  # Top referring hosts, e.g. "www.google.com"; sorted by (descending) click counts. Only present if this data is available.
+  #
+  #   url.analytics.*.referrers
+  #
+  # Top countries (expressed as country codes), e.g. "US" or "DE"; sorted by (descending) click counts.
+  #
+  #   url.analytics.*.countries
+  #
+  # Top browsers, e.g. "Chrome"; sorted by (descending) click counts.
+  #
+  #   url.analytics.*.browsers
+  #
+  # Top platforms or OSes, e.g. "Windows"; sorted by (descending) click counts.
+  #
+  #   url.analytics.*.platforms
+  #
+  # For mor details, see http://code.google.com/intl/pt-BR/apis/urlshortener/v1/reference.html#resource_url
+  #
   def self.expand(url=nil, options={})
     raise ArgumentError.new("URL to expand is required") if url.blank?
     options = {:shortUrl => url, :projection => nil}.merge!(options)
     Googl::Expand.new(options)
   end
 
+  # The Google URL Shortener API ClientLogin authentication.
+  #
+  #   client = Googl.client('user@gmail.com', 'my_valid_password')
+  #
+  #   url = client.shorten('https://github.com/zigotto/googl')
+  #   url.short_url
+  #   => http://goo.gl/DWDfi
+  #
+  # Go to http://goo.gl to see URL statistics.
+  #
   def self.client(email, passwd)
     Googl::ClientLogin.new(email, passwd)
   end

diff --git a/lib/googl/base.rb b/lib/googl/base.rb
@@ -1,6 +1,6 @@
 module Googl
 
-  class Base
+  class Base # :nodoc:
 
     private
 

diff --git a/lib/googl/client_login.rb b/lib/googl/client_login.rb
@@ -8,6 +8,8 @@ class ClientLogin < Base
 
     attr_accessor :code
 
+    # The Google URL Shortener API ClientLogin authentication. See Googl.client
+    #
     def initialize(email, passwd)
       modify_headers('Content-Type' => 'application/x-www-form-urlencoded')
       resp = Request.post(API_URL, :body => PARAMS.merge!('Email' => email, 'Passwd' => passwd))
@@ -20,6 +22,10 @@ def initialize(email, passwd)
       end
     end
 
+    # Creates a new short URL and thus will gather unique click statistics. It shows up on the user’s dashboard at http://goo.gl.
+    #
+    # See Googl.client
+    #
     def shorten(url)
       Googl::Shorten.new(url)
     end

diff --git a/lib/googl/expand.rb b/lib/googl/expand.rb
@@ -6,6 +6,8 @@ class Expand
 
     attr_accessor :long_url, :analytics, :status
 
+    # Expands a short URL or gets creation time and analytics. See Googl.expand
+    #
     def initialize(options={})
 
       options.delete_if {|key, value| value.nil?}

diff --git a/lib/googl/request.rb b/lib/googl/request.rb
@@ -1,3 +1,3 @@
-class Request
+class Request # :nodoc:
   include HTTParty
 end
diff --git a/lib/googl/ruby_extensions.rb b/lib/googl/ruby_extensions.rb
@@ -1,5 +1,5 @@
 # Rails
-class String
+class String # :nodoc:
   def underscore
     self.gsub(/::/, '/').
       gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
@@ -11,19 +11,19 @@ def underscore
 
 # Hash to OpenStruct
 # http://www.rubyquiz.com/quiz81.html
-class Object
+class Object # :nodoc:
   def to_openstruct
     self
   end
 end
 
-class Array
+class Array # :nodoc:
   def to_openstruct
     map{ |el| el.to_openstruct }
   end
 end
 
-class Hash
+class Hash #:nodoc:
   def move(from, to)
     self[to] = delete(from) if has_key?(from)
     self

diff --git a/lib/googl/shorten.rb b/lib/googl/shorten.rb
@@ -6,6 +6,8 @@ class Shorten < Base
 
     attr_accessor :short_url, :long_url
 
+    # Creates a new short URL, see Googl.shorten
+    #
     def initialize(long_url)
       modify_headers('Content-Type' => 'application/json')
       options = {"longUrl" => long_url}.inspect
@@ -18,6 +20,16 @@ def initialize(long_url)
       end
     end
 
+    # URL for QR Code
+    #
+    #   url = Googl.shorten('http://goo.gl/ump4S')
+    #   ur.qr_code
+    #   => http://goo.gl/ump4S.qr
+    #
+    # Usage:
+    #
+    #   <img src="http://goo.gl/ump4S.qr" />
+    #
     def qr_code
       "#{short_url}.qr" if !short_url.blank?
     end