Get referrers for a gauge.

README.md

@@ -100,6 +100,24 @@ Get the second page for a specific date:
 
     bfg.gauges('abcd1234').content('2011-12-9', :page => 2)
 
+### Referrers
+
+Get today's referrers for a gauge:
+
+    bfg.gauges('abcd1234').referrers
+
+Get the second page of referrers for a gauge:
+
+    bfg.gauges('abcd1234').referrers(:page => 2)
+
+Get referrers for a specific date of a gauge:
+
+    bfg.gauges('abcd1234').referrers('2011-12-9')
+
+Get the second page for a specific date:
+
+    bfg.gauges('abcd1234').referrers('2011-12-9', :page => 2)
+
 Testing
 -------
 

lib/twelve.rb

@@ -4,8 +4,9 @@
 require 'twelve/resource_proxy'
 require 'twelve/api/me'
 require 'twelve/api/clients'
-require 'twelve/api/gauges/content'
 require 'twelve/api/gauges/shares'
+require 'twelve/api/gauges/content'
+require 'twelve/api/gauges/referrers'
 require 'twelve/api/gauges'
 
 class Twelve

lib/twelve/api/gauges.rb

@@ -12,8 +12,9 @@ module Gauges
       # enables defining methods on the proxy object
       #
       class Proxy < ::Twelve::ResourceProxy
-        include Twelve::API::Gauges::Content
         include Twelve::API::Gauges::Shares
+        include Twelve::API::Gauges::Content
+        include Twelve::API::Gauges::Referrers
 
         # Creates a gauge
         #

lib/twelve/api/gauges/referrers.rb

@@ -0,0 +1,36 @@
+class Twelve
+
+  # API module encapsulates all of the API endpoints
+  #
+  module API
+
+    # The Gauges module handles Gauges on Gauges
+    #
+    module Gauges
+
+      # The Referrers module handles referrers
+      #
+      module Referrers
+
+        # Returns top content for a gauge
+        #
+        # *args - Date string & options hash
+        #
+        # Returns json
+        #
+        def referrers(*args)
+          attributes = {}
+
+          connection.get do |request|
+            request.url "#{path_prefix}/referrers"
+
+            args.each do |arg|
+              request.params['page'] = arg[:page].to_s if arg.is_a?(Hash) && arg.has_key?(:page)
+              request.params['date'] = arg if arg.is_a?(String)
+            end
+          end.body
+        end
+      end
+    end
+  end
+end

spec/twelve/api/gauges/referrers_spec.rb

@@ -0,0 +1,54 @@
+require 'spec_helper'
+
+describe Twelve::API::Gauges::Referrers do
+  subject { Twelve.new(ACCESS_TOKEN) }
+
+  describe "#referrers" do
+    context "with no args" do
+      it "should return todays referrers" do
+        VCR.use_cassette('referrers') do
+          response = subject.gauges(GAUGE_ID).referrers
+          response['date'].should_not be_nil
+          response['page'].should == 1
+          response['per_page'].should == 50
+          response.should have_key('urls')
+
+          referrers = response['referrers']
+          referrers.size.should > 0
+          referrers.first['url'].should_not be_nil
+          referrers.first['views'].should be_instance_of(Fixnum)
+          referrers.first['path'].should_not be_nil
+          referrers.first['host'].should_not be_nil
+        end
+      end
+    end
+
+    context "with page number" do
+      it "should return content for page" do
+        VCR.use_cassette('referrers(:page => 2)') do
+          response = subject.gauges(GAUGE_ID).referrers(:page => 2)
+          response['page'].should == 2
+        end
+      end
+    end
+
+    context "with a date" do
+      it "should return content for that date" do
+        VCR.use_cassette('referrers("2011-12-8")') do
+          response = subject.gauges(GAUGE_ID).referrers('2011-12-8')
+          response['date'].should == '2011-12-08'
+        end
+      end
+    end
+
+    context "with a date and page" do
+      it "should return content for that date" do
+        VCR.use_cassette('referrers("2011-12-8", :page => 2)') do
+          response = subject.gauges(GAUGE_ID).referrers('2011-12-8', :page => 2)
+          response['date'].should == '2011-12-08'
+          response['page'].should == 2
+        end
+      end
+    end
+  end
+end