cannikin-gattica 0.3.1 → 0.3.3

data/History.txt

@@ -1,3 +1,6 @@
+== 0.3.2
+  * er1c updated to use standard Ruby CSV library
+
 == 0.3.0
   * Support for filters (filters are all AND'ed together, no OR yet)
 

data/README.rdoc

@@ -39,7 +39,7 @@ The third parameter is the profile_id that we want to access data for.
 
 Then we call +get+ with the parameters we want to shape our data with. In this case we want
 total page views, broken down by browser, from Jan 1 2008 to Feb 1 2008, sorted by descending
-page views.
+page views. If you wanted to sort pageviews ascending, just leave off the minus.
 
 If you don't know the profile_id you want to get data for, call +accounts+
 
@@ -79,38 +79,31 @@ 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']
+  results = gs.get({:start_date => '2008-01-01', 
+                    :end_date => '2008-02-01', 
+                    :dimensions => ['browser','browserVersion'], 
+                    :metrics => ['pageviews','visits'], 
+                    :sort => ['-pageviews'],
+                    :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
-this you should save the authorization token you receive from Google and use that for future 
-requests:
+Filters can contain spaces around the operators, or not. These two lines are equivalent (I think
+the spaces make the filter more readable):
 
-  ga.token => 'DSasdf94...' (some huge long string)
+  :filter => ['browser == Firefox','pageviews >= 10000']
   
-You can now initialize Gattica with this token for future requests:
-
-  ga = Gattica.new({:token => 'DSasdf94...'})
+  :filter => ['browser==Firefox','pageviews>=10000']
   
-(You enter the full token, of course). I'm not sure how long a token from the Google's ClientLogin
-system remains active, but if/when I do I'll add that to the docs here.
+Once again, do _not_ include the +ga:+ prefix before the dimension/metric you're filtering against.
+Gattica will add this automatically.
 
-=== Headers
-Google expects a special header in all HTTP requests called 'Authorization'. This contains your
-token:
+You will probably find that as you try different filters, GA will report that some of them aren't
+valid. I haven't found any documentation that says which filter combinations are valid in what 
+circumstances, so I suppose it's just trial and error at this point.
 
-  Authorization = GoogleLogin auth=DSasdf94...
-
-This header is generated automatically. If you have your own headers you'd like to add, you can 
-pass them in when you initialize:
-
-  ga = Gattica.new({:token => 'DSasdf94...', :headers => {'My-Special-Header':'my_custom_value'}})
-  
-And they'll be sent with every request you make.
+For more on filtering syntax, see the Analytics API docs: http://code.google.com/apis/analytics/docs/gdata/gdataReference.html#filtering
   
 = Output
 When Gattica was originally created it was intended to take the data returned and put it into
@@ -152,16 +145,42 @@ Gives you:
         "id"=>"http://www.google.com/analytics/feeds/data?ids=ga:12345&ga:browser=Internet%20Explorer&start-date=2009-01-01&end-date=2009-01-31", 
         "metrics"=>[{:pageviews=>53303}], 
         "updated"=>#<DateTime: 212100120000001/86400000,-1/3,2299161>}]}
+
+== Notes on Authentication
+=== Authentication Token
+Google recommends not re-authenticating each time you do a request against the API. To accomplish
+this you should save the authorization token you receive from Google and use that for future 
+requests:
+
+  ga.token => 'DSasdf94...' (some huge long string)
+
+You can now initialize Gattica with this token for future requests:
+
+  ga = Gattica.new({:token => 'DSasdf94...'})
+
+(You enter the full token, of course). I'm not sure how long a token from the Google's ClientLogin
+system remains active, but if/when I do I'll add that to the docs here.
+
+=== Headers
+Google expects a special header in all HTTP requests called 'Authorization'. This contains your
+token:
+
+  Authorization = GoogleLogin auth=DSasdf94...
+
+This header is generated automatically. If you have your own headers you'd like to add, you can 
+pass them in when you initialize:
+
+  ga = Gattica.new({:token => 'DSasdf94...', :headers => {'My-Special-Header':'my_custom_value'}})
+
+And they'll be sent with every request you make.
         
 = Limitations
 The GA API limits each call to 1000 results per "page." If you want more, you need to tell
 the API what number to begin at and it will return the next 1000. Gattica does not currently
 support this, but it's in the plan for the very next version.
 
-The GA API support filtering, so you can say things like "only show me the pageviews for pages
-whose URL meets the regular expression ^/saf.*?/$". Support for filters have begun, but according
-to one report, the DataSet object that returns doesn't parse the results correctly. So for now,
-avoid using filters.
+Currently all filters you supply are ANDed together before being sent to GA. Support for ORing
+is coming soon.
 
 = The Future
 A couple of things I have planned:
@@ -171,4 +190,3 @@ A couple of things I have planned:
 3. Automatically handle paging (the API only returns 1000 results at a time). Gattica will request
    one result set, see how many pages there are, then do several calls until all pages are retrieved
    or it hits the limit of the number of results you want and return all that data as one big block.
-4. Create a nice syntax for filters

data/VERSION.yml

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

data/lib/gattica/data_point.rb

@@ -1,3 +1,5 @@
+require 'csv'
+
 module Gattica
   
   # Represents a single "row" of data containing any number of dimensions, metrics
@@ -26,24 +28,21 @@ module Gattica
     # Outputs in Comma Seperated Values format
     def to_csv(format = :long)
       output = ''
+      columns = []
       
       # only output
       case format
       when :long
-        output = "\"#{@id}\",\"#{@updated.to_s}\",\"#{@title}\","
+        [@id, @updated, @title].each { |c| columns << c }
       end
       
       # output all dimensions
-      output += @dimensions.collect do |dimension|
-        "\"#{dimension.value}\""
-      end.join(',')
-      output += ','
+      @dimensions.map {|d| d.value}.each { |c| columns << c }
       
       # output all metrics
-      output += @metrics.collect do |metric|
-        "\"#{metric.value}\""
-      end.join(',')
-      
+      @metrics.map {|m| m.value}.each { |c| columns << c }
+
+      output = CSV.generate_line(columns)      
       return output
     end
     

data/lib/gattica/data_set.rb

@@ -25,24 +25,21 @@ module Gattica
     def to_csv(format = :long)
       # build the headers
       output = ''
-      
+      columns = []
+
       # only show the nitty gritty details of id, updated_at and title if requested
       case format
       when :long
-        output = '"id","updated","title",'
+        ["id", "updated", "title"].each { |c| columns << c }
       end
       
       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"
+        @points.first.dimensions.map {|d| d.key}.each { |c| columns << c }
+        @points.first.metrics.map {|m| m.key}.each { |c| columns << c }
       end
       
+      output = CSV.generate_line(columns) + "\n"
+
       # get the data from each point
       @points.each do |point|
         output += point.to_csv(format) + "\n"

data/lib/gattica.rb

@@ -127,7 +127,8 @@ module Gattica
     #            :end_date => '2008-02-01', 
     #            :dimensions => 'browser', 
     #            :metrics => 'pageviews', 
-    #            :sort => 'pageviews'})
+    #            :sort => 'pageviews',
+    #            :filters => ['browser == Firefox']})
     #
     # == Input
     #

metadata

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