Skip to content
Newer
Older
100644 191 lines (132 sloc) 8.12 KB
89de82b @cannikin First commit, 0.1.1
cannikin authored
1 Gattica is a Ruby library for talking to the Google Analytics API.
2
e6500d0 @cannikin Updated with instructions for installing the gem from github
cannikin authored
3 = Installation
4 Install the gattica gem using github as the source:
5
6 gem install cannikin-gattica -s http://gems.github.com
7
8 When you want to require, you just use 'gattica' as the gem name:
9
10 require 'rubygems'
11 require 'gattica'
12
dfbe026 @cannikin Moved installation instructions to the top
cannikin authored
13 = Introduction
5d91143 @cannikin Added tests, using Jeweler for gem management, bumped to 0.2.0
cannikin authored
14 It's a good idea to familiarize yourself with the Google API docs: http://code.google.com/apis/analytics/docs/gdata/gdataDeveloperGuide.html
15
16 In particular there are some very specific combinations of Metrics and Dimensions that
17 you are restricted to and those are explained in this document: http://code.google.com/apis/analytics/docs/gdata/gdataReferenceDimensionsMetrics.html
18
19 See examples/example.rb for some code that should work automatically if you replace the email/password with your own
20
dfbe026 @cannikin Moved installation instructions to the top
cannikin authored
21 There are generally three steps to getting info from the GA API:
22
23 1. Authenticate
24 2. Get a profile id
25 3. Get the data you really want
26
89de82b @cannikin First commit, 0.1.1
cannikin authored
27 = Usage
28 This library does all three. A typical transaction will look like this:
29
6fb9665 * er1c added start_index and max_results * er1c added paging for all…
Eric Peters authored
30 gs = Gattica.new({:email => 'johndoe@google.com', :password => 'password', :profile_id => 123456})
89de82b @cannikin First commit, 0.1.1
cannikin authored
31 results = gs.get({ :start_date => '2008-01-01',
32 :end_date => '2008-02-01',
33 :dimensions => 'browser',
34 :metrics => 'pageviews',
d0519d5 @cannikin More readme updates
cannikin authored
35 :sort => '-pageviews'})
89de82b @cannikin First commit, 0.1.1
cannikin authored
36
37 So we instantiate a copy of Gattica and pass it a Google Account email address and password.
38 The third parameter is the profile_id that we want to access data for.
39
40 Then we call +get+ with the parameters we want to shape our data with. In this case we want
d0519d5 @cannikin More readme updates
cannikin authored
41 total page views, broken down by browser, from Jan 1 2008 to Feb 1 2008, sorted by descending
b94633d @cannikin Updated docs with filter examples
cannikin authored
42 page views. If you wanted to sort pageviews ascending, just leave off the minus.
89de82b @cannikin First commit, 0.1.1
cannikin authored
43
44 If you don't know the profile_id you want to get data for, call +accounts+
45
5d91143 @cannikin Added tests, using Jeweler for gem management, bumped to 0.2.0
cannikin authored
46 gs = Gattica.new({:email => 'johndoe@google.com', :password => 'password'})
89de82b @cannikin First commit, 0.1.1
cannikin authored
47 accounts = gs.accounts
48
49 This returns all of the accounts and profiles that the user has access to. Note that if you
50 use this method to get profiles, you need to manually set the profile before you can call +get+
51
52 gs.profile_id = 123456
53 results = gs.get({ :start_date => '2008-01-01',
54 :end_date => '2008-02-01',
55 :dimensions => 'browser',
56 :metrics => 'pageviews',
d0519d5 @cannikin More readme updates
cannikin authored
57 :sort => '-pageviews'})
2b1c18e @cannikin Updated docs with output examples and limitations
cannikin authored
58
d0519d5 @cannikin More readme updates
cannikin authored
59 When you put in the names for the dimensions and metrics you want, refer to this doc for the
3c0a4c2 @cannikin Updates to readme
cannikin authored
60 available names: http://code.google.com/apis/analytics/docs/gdata/gdataReferenceDimensionsMetrics.html
d0519d5 @cannikin More readme updates
cannikin authored
61
62 Note that you do *not* use the 'ga:' prefix when you tell Gattica which ones you want. Gattica
63 adds that for you automatically.
64
65 If you want to search on more than one dimension or metric, pass them in as an array (you can
66 also pass in single values as arrays too, if you wish):
67
68 results = gs.get({ :start_date => '2008-01-01',
69 :end_date => '2008-02-01',
70 :dimensions => ['browser','browserVersion'],
71 :metrics => ['pageviews','visits'],
72 :sort => ['-pageviews']})
5d91143 @cannikin Added tests, using Jeweler for gem management, bumped to 0.2.0
cannikin authored
73
b5e95f9 @cannikin Added basic filtering (all filters are ANDed together, no OR)
cannikin authored
74 == Filters
75 Filters can be pretty complex as far as GA is concerned. You can filter on either dimensions or metrics
76 or both. And then your filters can be ANDed together or they can ORed together. There are also rules,
77 which are not immediately apparent, about what you can filter and how.
78
79 By default filters passed to a +get+ are ANDed together. This means that all filters need to match for
80 the result to be returned.
81
b94633d @cannikin Updated docs with filter examples
cannikin authored
82 results = gs.get({:start_date => '2008-01-01',
83 :end_date => '2008-02-01',
84 :dimensions => ['browser','browserVersion'],
85 :metrics => ['pageviews','visits'],
86 :sort => ['-pageviews'],
a63e7c7 @cannikin Changed the filter example from :filter to :filters
cannikin authored
87 :filters => ['browser == Firefox','pageviews >= 10000']})
b5e95f9 @cannikin Added basic filtering (all filters are ANDed together, no OR)
cannikin authored
88
89 This says "return only results where the 'browser' dimension contains the word 'Firefox' and the
90 'pageviews' metric is greater than or equal to 10,000.
44b1e8f @cannikin New branch from er1c
cannikin authored
91
92 Filters can contain spaces around the operators, or not. These two lines are equivalent (I think
93 the spaces make the filter more readable):
94
a63e7c7 @cannikin Changed the filter example from :filter to :filters
cannikin authored
95 :filters => ['browser == Firefox','pageviews >= 10000']
44b1e8f @cannikin New branch from er1c
cannikin authored
96
a63e7c7 @cannikin Changed the filter example from :filter to :filters
cannikin authored
97 :filters => ['browser==Firefox','pageviews>=10000']
44b1e8f @cannikin New branch from er1c
cannikin authored
98
99 Once again, do _not_ include the +ga:+ prefix before the dimension/metric you're filtering against.
100 Gattica will add this automatically.
101
102 You will probably find that as you try different filters, GA will report that some of them aren't
103 valid. I haven't found any documentation that says which filter combinations are valid in what
104 circumstances, so I suppose it's just trial and error at this point.
105
106 For more on filtering syntax, see the Analytics API docs: http://code.google.com/apis/analytics/docs/gdata/gdataReference.html#filtering
5d91143 @cannikin Added tests, using Jeweler for gem management, bumped to 0.2.0
cannikin authored
107
2b1c18e @cannikin Updated docs with output examples and limitations
cannikin authored
108 = Output
109 When Gattica was originally created it was intended to take the data returned and put it into
110 Excel for someone else to crunch through the numbers. Thus, Gattica has great built-in support
111 for CSV output. Once you have your data simply:
112
113 results.to_csv
114
115 A couple example rows of what that looks like:
116
117 "id","updated","title","browser","pageviews"
118 "http://www.google.com/analytics/feeds/data?ids=ga:12345&ga:browser=Internet%20Explorer&start-date=2009-01-01&end-date=2009-01-31","2009-01-30T16:00:00-08:00","ga:browser=Internet Explorer","Internet Explorer","53303"
119 "http://www.google.com/analytics/feeds/data?ids=ga:12345&ga:browser=Firefox&start-date=2009-01-01&end-date=2009-01-31","2009-01-30T16:00:00-08:00","ga:browser=Firefox","Firefox","20323"
120
d0519d5 @cannikin More readme updates
cannikin authored
121 Data is comma-separated and double-quote delimited. In most cases, people don't care
122 about the id, updated, or title attributes of this data. They just want the dimensions and
123 metrics. In that case, pass the symbol +:short+ to +to_csv+ and receive get back only the
124 the good stuff:
125
126 results.to_csv(:short)
127
128 Which returns:
129
130 "browser","pageviews"
131 "Internet Explorer","53303"
132 "Firefox","20323"
2b1c18e @cannikin Updated docs with output examples and limitations
cannikin authored
133
134 You can also just output the results as a string and you'll get the standard inspect syntax:
135
d0519d5 @cannikin More readme updates
cannikin authored
136 results.to_s
137
138 Gives you:
139
2b1c18e @cannikin Updated docs with output examples and limitations
cannikin authored
140 { "end_date"=>#<Date: 4909725/2,0,2299161>,
141 "start_date"=>#<Date: 4909665/2,0,2299161>,
142 "points"=>[
143 { "title"=>"ga:browser=Internet Explorer",
144 "dimensions"=>[{:browser=>"Internet Explorer"}],
28ec1b4 @cannikin Updated to readme
cannikin authored
145 "id"=>"http://www.google.com/analytics/feeds/data?ids=ga:12345&amp;ga:browser=Internet%20Explorer&amp;start-date=2009-01-01&amp;end-date=2009-01-31",
2b1c18e @cannikin Updated docs with output examples and limitations
cannikin authored
146 "metrics"=>[{:pageviews=>53303}],
147 "updated"=>#<DateTime: 212100120000001/86400000,-1/3,2299161>}]}
b94633d @cannikin Updated docs with filter examples
cannikin authored
148
149 == Notes on Authentication
150 === Authentication Token
151 Google recommends not re-authenticating each time you do a request against the API. To accomplish
152 this you should save the authorization token you receive from Google and use that for future
153 requests:
154
155 ga.token => 'DSasdf94...' (some huge long string)
156
157 You can now initialize Gattica with this token for future requests:
158
159 ga = Gattica.new({:token => 'DSasdf94...'})
160
161 (You enter the full token, of course). I'm not sure how long a token from the Google's ClientLogin
162 system remains active, but if/when I do I'll add that to the docs here.
163
164 === Headers
165 Google expects a special header in all HTTP requests called 'Authorization'. This contains your
166 token:
167
168 Authorization = GoogleLogin auth=DSasdf94...
169
170 This header is generated automatically. If you have your own headers you'd like to add, you can
171 pass them in when you initialize:
172
173 ga = Gattica.new({:token => 'DSasdf94...', :headers => {'My-Special-Header':'my_custom_value'}})
174
175 And they'll be sent with every request you make.
2b1c18e @cannikin Updated docs with output examples and limitations
cannikin authored
176
177 = Limitations
178 The GA API limits each call to 1000 results per "page." If you want more, you need to tell
179 the API what number to begin at and it will return the next 1000. Gattica does not currently
180 support this, but it's in the plan for the very next version.
181
b94633d @cannikin Updated docs with filter examples
cannikin authored
182 Currently all filters you supply are ANDed together before being sent to GA. Support for ORing
183 is coming soon.
2b1c18e @cannikin Updated docs with output examples and limitations
cannikin authored
184
185 = The Future
186 A couple of things I have planned:
187
3a703b7 @cannikin Updated readme
cannikin authored
188 1. Tests!
189 2. The option to use a custom delimiter for output
6fb9665 * er1c added start_index and max_results * er1c added paging for all…
Eric Peters authored
190
Something went wrong with that request. Please try again.