googl 0.2.0 → 0.3.0

data/Gemfile

@@ -1,6 +1,6 @@
 source "http://rubygems.org"
 
-gem "httparty", "0.6.1"
+gem "httparty", ">= 0.6.1"
 
 group :development do
   gem "rspec", "~> 2.3.0"

data/Gemfile.lock

@@ -30,7 +30,7 @@ PLATFORMS
 
 DEPENDENCIES
   bundler (~> 1.0.0)
-  httparty (= 0.6.1)
+  httparty (>= 0.6.1)
   jeweler (~> 1.5.2)
   rcov
   rspec (~> 2.3.0)

data/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

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.3.0

data/googl.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{googl}
-  s.version = "0.2.0"
+  s.version = "0.3.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Jesus Lopes"]
-  s.date = %q{2011-01-13}
+  s.date = %q{2011-01-17}
   s.description = %q{Small library for Google URL Shortener API}
   s.email = %q{jlopes@zigotto.com.br}
   s.extra_rdoc_files = [
@@ -28,14 +28,22 @@ Gem::Specification.new do |s|
     "lib/googl/client_login.rb",
     "lib/googl/expand.rb",
     "lib/googl/request.rb",
+    "lib/googl/ruby_extensions.rb",
     "lib/googl/shorten.rb",
     "spec/client_spec.rb",
     "spec/expand_spec.rb",
     "spec/fixtures/client_login_invalid.json",
     "spec/fixtures/client_login_valid.json",
     "spec/fixtures/expand.json",
+    "spec/fixtures/expand_404.json",
+    "spec/fixtures/expand_projection_clicks.json",
+    "spec/fixtures/expand_projection_full.json",
+    "spec/fixtures/expand_projection_strings.json",
+    "spec/fixtures/expand_removed.json",
     "spec/fixtures/shorten.json",
     "spec/fixtures/shorten_authenticated.json",
+    "spec/fixtures/shorten_invalid_content_type.json",
+    "spec/shared_examples.rb",
     "spec/shorten_spec.rb",
     "spec/spec_helper.rb"
   ]
@@ -47,6 +55,7 @@ Gem::Specification.new do |s|
   s.test_files = [
     "spec/client_spec.rb",
     "spec/expand_spec.rb",
+    "spec/shared_examples.rb",
     "spec/shorten_spec.rb",
     "spec/spec_helper.rb"
   ]
@@ -55,7 +64,7 @@ Gem::Specification.new do |s|
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<httparty>, ["= 0.6.1"])
+      s.add_runtime_dependency(%q<httparty>, [">= 0.6.1"])
       s.add_development_dependency(%q<rspec>, ["~> 2.3.0"])
       s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
       s.add_development_dependency(%q<jeweler>, ["~> 1.5.2"])
@@ -63,7 +72,7 @@ Gem::Specification.new do |s|
       s.add_development_dependency(%q<webmock>, ["~> 1.6.2"])
       s.add_runtime_dependency(%q<httparty>, [">= 0.6.1"])
     else
-      s.add_dependency(%q<httparty>, ["= 0.6.1"])
+      s.add_dependency(%q<httparty>, [">= 0.6.1"])
       s.add_dependency(%q<rspec>, ["~> 2.3.0"])
       s.add_dependency(%q<bundler>, ["~> 1.0.0"])
       s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
@@ -72,7 +81,7 @@ Gem::Specification.new do |s|
       s.add_dependency(%q<httparty>, [">= 0.6.1"])
     end
   else
-    s.add_dependency(%q<httparty>, ["= 0.6.1"])
+    s.add_dependency(%q<httparty>, [">= 0.6.1"])
     s.add_dependency(%q<rspec>, ["~> 2.3.0"])
     s.add_dependency(%q<bundler>, ["~> 1.0.0"])
     s.add_dependency(%q<jeweler>, ["~> 1.5.2"])

data/lib/googl.rb

@@ -1,21 +1,99 @@
 require 'httparty'
+require 'ostruct'
 
 require 'googl/base'
 require 'googl/request'
 require 'googl/shorten'
 require 'googl/expand'
 require 'googl/client_login'
+require 'googl/ruby_extensions'
 
 module Googl
 
-  def self.shorten(url)
+  # 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
 
-  def self.expand(url)
-    Googl::Expand.new(url)
+  # 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

data/lib/googl/base.rb

@@ -1,6 +1,6 @@
 module Googl
 
-  class Base
+  class Base # :nodoc:
 
     private
 

data/lib/googl/client_login.rb

@@ -8,6 +8,8 @@ module Googl
 
     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))
@@ -16,10 +18,14 @@ module Googl
         token = resp.split('=').last.gsub(/\n/, '')
         modify_headers("Authorization" => "GoogleLogin auth=#{token}")
       else
-        resp.response
+        raise Exception.new("#{resp.code} #{resp.parsed_response}")
       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

data/lib/googl/expand.rb

@@ -2,16 +2,23 @@ module Googl
 
   class Expand
 
-    API_URL = "https://www.googleapis.com/urlshortener/v1/url?shortUrl="
+    API_URL = "https://www.googleapis.com/urlshortener/v1/url"
 
-    attr_accessor :long_url
+    attr_accessor :long_url, :analytics, :status
 
-    def initialize(short_url)
-      resp = Request.get(API_URL + short_url)
+    # Expands a short URL or gets creation time and analytics. See Googl.expand
+    #
+    def initialize(options={})
+
+      options.delete_if {|key, value| value.nil?}
+
+      resp = Request.get(API_URL, :query => options)
       if resp.code == 200
         @long_url   = resp['longUrl']
+        @analytics  = resp['analytics'].to_openstruct if resp.has_key?('analytics')
+        @status     = resp['status']
       else
-        resp.response
+        raise Exception.new("#{resp.code} #{resp.message}")
       end
     end
 

data/lib/googl/request.rb

@@ -1,3 +1,3 @@
-class Request
+class Request # :nodoc:
   include HTTParty
 end

data/lib/googl/ruby_extensions.rb

@@ -0,0 +1,38 @@
+# Rails
+class String # :nodoc:
+  def underscore
+    self.gsub(/::/, '/').
+      gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+      gsub(/([a-z\d])([A-Z])/,'\1_\2').
+      tr("-", "_").
+      downcase
+  end
+end
+
+# Hash to OpenStruct
+# http://www.rubyquiz.com/quiz81.html
+class Object # :nodoc:
+  def to_openstruct
+    self
+  end
+end
+
+class Array # :nodoc:
+  def to_openstruct
+    map{ |el| el.to_openstruct }
+  end
+end
+
+class Hash #:nodoc:
+  def move(from, to)
+    self[to] = delete(from) if has_key?(from)
+    self
+  end  
+  def to_openstruct
+    map = inject({}) do |mapped, (key, value)| 
+      mapped[key.underscore] = value.to_openstruct
+      mapped.move('id', 'label')
+    end
+    OpenStruct.new(map)
+  end
+end

data/lib/googl/shorten.rb

@@ -6,6 +6,8 @@ module Googl
 
     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
@@ -14,12 +16,22 @@ module Googl
         @short_url  = resp['id']
         @long_url   = resp['longUrl']
       else
-        resp.response
+        raise Exception.new(resp.parsed_response)
       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?
+      "#{short_url}.qr" if !short_url.blank?
     end
 
   end

data/spec/client_spec.rb

@@ -26,10 +26,8 @@ describe Googl::ClientLogin do
 
       subject { Googl.client('my_invalid_gmail', 'my_invalid_passwod') }
 
-      describe "#code" do
-        it "should return 403" do
-          subject.code.should == 403
-        end
+      it "should return BadAuthentication" do
+        lambda { Googl.client('my_invalid_gmail', 'my_invalid_passwod') }.should raise_error(Exception, /403 Error=BadAuthentication/)
       end
       
     end

data/spec/expand_spec.rb

@@ -5,20 +5,159 @@ describe Googl::Expand do
   before :each do
     fake_urls
   end
-  
+
   context "when expand any goo.gl short URL" do
 
     it { Googl.should respond_to(:expand) }
 
-    subject { Googl.expand('http://goo.gl/7lob') }
+    context "wirh invalid url" do
+
+      it "should return error 404" do
+        lambda { Googl.expand('http://goo.gl/blajjddkksijj') }.should raise_error(Exception, /404 Not Found/)
+      end
 
-    describe "#long_url" do
-      it "should return a long url" do
-        subject.long_url.should == 'http://jlopes.zigotto.com.br/'
+      it "should return error for required url" do
+        lambda { Googl.expand }.should raise_error(ArgumentError, /URL to expand is required/)
       end
+
+      it "should return status REMOVED" do
+        Googl.expand('http://goo.gl/R7f68').status.should == 'REMOVED'
+      end
+
     end
 
-  end
+    context "with valid url" do
+
+      subject { Googl.expand('http://goo.gl/7lob') }
+
+      describe "#long_url" do
+        it "should return a long url" do
+          subject.long_url.should == 'http://jlopes.zigotto.com.br/'
+        end
+      end
+
+      describe "#status" do
+        it "should return a status of url" do
+          subject.status.should == 'OK'
+        end
+      end
+
+      context "with projection" do
+
+        context "full" do
+
+          subject { Googl.expand('http://goo.gl/DWDfi', :projection => :full) }
+
+          describe "#all_time" do
+            let(:element) { subject.analytics.all_time }
+
+            it_should_behave_like 'a clicks'
+            it_should_behave_like 'a period'
+
+            it "should rename id to label" do
+              element.countries.first.label.should == "BR" 
+            end
+          end
+
+          describe "#month" do
+            let(:element) { subject.analytics.month }
+
+            it_should_behave_like 'a clicks'
+            it_should_behave_like 'a period'
+          end
+
+          describe "#week" do
+            let(:element) { subject.analytics.week }
+
+            it_should_behave_like 'a clicks'
+            it_should_behave_like 'a period'
+          end
+
+          describe "#day" do
+            let(:element) { subject.analytics.day }
+
+            it_should_behave_like 'a clicks'
+            it_should_behave_like 'a period'
+          end
+
+          describe "#two_hours" do
+            let(:element) { subject.analytics.two_hours }
+
+            it_should_behave_like 'a clicks'
+          end
+
+        end
+
+        context "analytics_clicks" do
 
+          subject { Googl.expand('http://goo.gl/DWDfi', :projection => :analytics_clicks) }
+
+          describe "#all_time" do
+            let(:element) { subject.analytics.all_time }
+
+            it_should_behave_like 'a clicks'
+          end
+
+          describe "#month" do
+            let(:element) { subject.analytics.month }
+
+            it_should_behave_like 'a clicks'
+          end
+
+          describe "#week" do
+            let(:element) { subject.analytics.week }
+
+            it_should_behave_like 'a clicks'
+          end
+
+          describe "#day" do
+            let(:element) { subject.analytics.day }
+
+            it_should_behave_like 'a clicks'
+          end
+
+          describe "#two_hours" do
+            let(:element) { subject.analytics.two_hours }
+
+            it_should_behave_like 'a clicks'
+          end
+
+        end
+
+        context "analytics_top_strings" do
+
+          subject { Googl.expand('http://goo.gl/DWDfi', :projection => :analytics_top_strings) }
+
+          describe "#all_time" do
+            let(:element) { subject.analytics.all_time }
+
+            it_should_behave_like 'a period'
+          end
+
+          describe "#month" do
+            let(:element) { subject.analytics.month }
+
+            it_should_behave_like 'a period'
+          end
+
+          describe "#week" do
+            let(:element) { subject.analytics.week }
+
+            it_should_behave_like 'a period'
+          end
+
+          describe "#day" do
+            let(:element) { subject.analytics.day }
+
+            it_should_behave_like 'a period'
+          end
+
+        end
+
+      end
+
+    end
+
+  end
 
 end