Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Fetching contributors…
Cannot retrieve contributors at this time
175 lines (123 sloc) 7.52 KB

Gattica is a Ruby library for talking to the Google Analytics API.


Install the gattica gem using github as the source:

gem install cannikin-gattica -s

When you want to require, you just use 'gattica' as the gem name:

require 'rubygems'
require 'gattica'


It's a good idea to familiarize yourself with the Google API docs:

In particular there are some very specific combinations of Metrics and Dimensions that you are restricted to and those are explained in this document:

See examples/example.rb for some code that should work automatically if you replace the email/password with your own

There are generally three steps to getting info from the GA API:

  1. Authenticate

  2. Get a profile id

  3. Get the data you really want


This library does all three. A typical transaction will look like this:

gs ={:email => '', :password => 'password', profile_id => 123456})
results = gs.get({ :start_date => '2008-01-01', 
                   :end_date => '2008-02-01', 
                   :dimensions => 'browser', 
                   :metrics => 'pageviews', 
                   :sort => '-pageviews'})

So we instantiate a copy of Gattica and pass it a Google Account email address and password. 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.

If you don't know the profile_id you want to get data for, call accounts

gs ={:email => '', :password => 'password'})
accounts = gs.accounts

This returns all of the accounts and profiles that the user has access to. Note that if you use this method to get profiles, you need to manually set the profile before you can call get

gs.profile_id = 123456
results = gs.get({ :start_date => '2008-01-01', 
                   :end_date => '2008-02-01', 
                   :dimensions => 'browser', 
                   :metrics => 'pageviews', 
                   :sort => '-pageviews'})

When you put in the names for the dimensions and metrics you want, refer to this doc for the available names:

Note that you do not use the 'ga:' prefix when you tell Gattica which ones you want. Gattica adds that for you automatically.

If you want to search on more than one dimension or metric, pass them in as an array (you can also pass in single values as arrays too, if you wish):

results = gs.get({ :start_date => '2008-01-01', 
                   :end_date => '2008-02-01', 
                   :dimensions => ['browser','browserVersion'], 
                   :metrics => ['pageviews','visits'], 
                   :sort => ['-pageviews']})


Filters can be pretty complex as far as GA is concerned. You can filter on either dimensions or metrics or both. And then your filters can be ANDed together or they can ORed together. There are also rules, 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']

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:

ga.token => 'DSasdf94...' (some huge long string)

You can now initialize Gattica with this token for future requests:

ga ={: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.


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 ={:token => 'DSasdf94...', :headers => {'My-Special-Header':'my_custom_value'}})

And they'll be sent with every request you make.


When Gattica was originally created it was intended to take the data returned and put it into Excel for someone else to crunch through the numbers. Thus, Gattica has great built-in support for CSV output. Once you have your data simply:


A couple example rows of what that looks like:

"","2009-01-30T16:00:00-08:00","ga:browser=Internet Explorer","Internet Explorer","53303"

Data is comma-separated and double-quote delimited. In most cases, people don't care about the id, updated, or title attributes of this data. They just want the dimensions and metrics. In that case, pass the symbol :short to to_csv and receive get back only the the good stuff:


Which returns:

"Internet Explorer","53303"

You can also just output the results as a string and you'll get the standard inspect syntax:


Gives you:

{ "end_date"=>#<Date: 4909725/2,0,2299161>, 
  "start_date"=>#<Date: 4909665/2,0,2299161>, 
    { "title"=>"ga:browser=Internet Explorer", 
      "dimensions"=>[{:browser=>"Internet Explorer"}],
      "updated"=>#<DateTime: 212100120000001/86400000,-1/3,2299161>}]}


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.

The Future

A couple of things I have planned:

  1. Tests!

  2. The option to use a custom delimiter for output

  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

Jump to Line
Something went wrong with that request. Please try again.