Introducing Garb: Access the Google Analytics Data Export API with Ruby
Since the moment Google announced that they would be releasing an API for their de-facto analytics tools, I was very excited to dive into the wealth of useful information within. Shortly thereafter, Josh and Jen from our Marketing Lab came to us to develop some tools that would help in collecting the data for our reporting.
To accomplish these goals, I first read through all of the documentation that Google provided with access to the analytics data export beta. After, with some brainstorming with Pat, we decided to create a new gem to handle much of the interaction with the new API. Garb is what we've come up with.
Thankfully, the waiting period is over. Google has announced the release of the API to the public, and Josh has written his take on the announcement.
The API and Design of Garb
Documentation
The documentation for the analytics API is pretty solid, though complex. Sections describe the authentication process, retrieving accounts and profiles, the metrics and dimensions available and how they could be combined, and details for sorting and filtering the data. It is very well written, and very concise. I suppose I should have expected nothing less from Google.
A Word on Dimensions and Metrics
The API provides access to all of the same dimensions and metrics (and more) that are familiar to anyone who has ever used Google Analytics and especially the custom reporting tools within. Through the API there is, however, a substantial set of rules surrounding the selection and combination of dimensions and metrics.
Basically, two dimensions and up to 50 metrics can be selected in any one request. Easy enough? Unfortunately, we hit snags trying to make (what seem like) commonplace combinations. For example, while we were developing Garb, you could not get the "visits" metric scoped to the "requested page URI" dimension. It took a good bit of studying to truly understand the boundaries of these combinations.
So, On To Using Garb in Your Project
There are three parts to using Garb. The first is getting a session, which requires your Google Analytics username and password . Second is the profile (or many profiles) that your authenticated account has access to. Last, given the first two parts, you can create reports and retrieve the data from the API.
Session
Sessions are simple enough to create and are currently stored globally. This is simpler, but limits us to one session at a time.
Garb::Session.login('username', 'password')
Profile
profile = Garb::Profile.all.first # or select from the list
Reports
You can create a simple report.
report = Garb::Report.new(profile, {:metrics => [:visits]})
report.all
Or, an advanced one.
class ExitsReport < Garb::Report
def initialize(profile)
super(profile) do |config|
config.start_date = Time.now.at_beginning_of_month
config.end_date = Time.now.at_end_of_month
config.metrics << [:exits, :pageviews, :exit_rate]
config.dimensions << :request_uri
config.sort << :exits.desc
config.max_results = 10
end
end
end
ExitsReport.new(profile).all
Note: the date/time related methods are from ActiveSupport.
The Google Analytics Data Export API has come along very quickly. It's already powerful enough to provide the data to generate reports that we've never before been able to create. Soon, we'll only be limited by our imaginations, which is exactly how Google wants it. There have always been many compelling reasons to use Google Analytics. Now, I struggle to find a reason not to.
I encourage everyone interested in using this library to read the documentation, check the code out on Github at http://github.com/vigetlabs/garb/tree/master and, of course, comment, question, and enjoy. If you'd like to go straight to installing it be sure to vigetlabs-garb sourced from Github until I can get it up on Rubyforge!
Recent Comments
Good job, I’ll use it next time :)