Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Updating the documentation mostly

  • Loading branch information...
commit aee9adf9cbb494890626ba2fa22827747e0b1231 1 parent c872594
authored April 26, 2009
11  AUTHORS
... ...
@@ -0,0 +1,11 @@
  1
+Pinax was started by Clint Ecker in April 2009.
  2
+ 
  3
+The PRIMARY AUTHORS are:
  4
+
  5
+  * Clint Ecker <me@clintecker.com>
  6
+
  7
+ADDITIONAL CONTRIBUTORS include:
  8
+
  9
+  * Robera Kosara
  10
+  * Michael Greene
  11
+  * Patrick Collison
15  CHANGES
... ...
@@ -0,0 +1,15 @@
  1
+April 26: 1.0.2 Released
  2
+
  3
+  * Merged in changes from Robera Kosara, Michael Greene, and Patrick Collison which add multiple dimension and multiple metric support, pagination in data results, various style fixed, and bug fixes.
  4
+  * Updated documentation and split out information into INSTALL/USAGE/README/AUTHORS so people can find information more easily.
  5
+
  6
+April 25: 1.0.1 Released
  7
+
  8
+  * Fixed a small issue with the setup.py that was causing easy_install to break.
  9
+
  10
+April 24: 1.0 Released
  11
+
  12
+  * Basic client with almost all functionality exposed as outlined in my blog post: 
  13
+     http://blog.clintecker.com/post/100021441/python-google-analytics-client-how-to-use-it-and-how
  14
+
  15
+April 22: Started Development
89  INSTALL.md
Source Rendered
... ...
@@ -0,0 +1,89 @@
  1
+Installation
  2
+============
  3
+
  4
+Theoretically you should be able to type the following after checking out the source:
  5
+
  6
+`sudo python setup.py install`
  7
+
  8
+You can also just install using `easy_install` like so:
  9
+
  10
+`sudo easy_install python-googleanalytics`
  11
+
  12
+Alternatively you may choose to use python-googleanalytics in a large project (most likely).  You can pass "python-googleanalytics" to any dependency manager (pip, buildout) to pull it into your development, production, or virtual environment for whatever reason you like.
  13
+
  14
+## Development ##
  15
+
  16
+I'm trying to use Buildout, so you can start helping out with development by checking out the source and typing the following:
  17
+
  18
+<pre>
  19
+git clone git://github.com/clintecker/python-googleanalytics.git
  20
+python bootstrap.py && ./bin/buildout
  21
+</pre>
  22
+
  23
+Once you've done these steps, you should be able to run a Python interpreter that has access to our module with the following command:
  24
+
  25
+`./bin/python`
  26
+
  27
+It should work like so:
  28
+
  29
+<pre>
  30
+(python-googleanalytics)[master][~/src/python-googleanalytics] ./bin/python
  31
+
  32
+>>> import googleanalytics
  33
+>>> 
  34
+</pre>
  35
+
  36
+The system Python interpreter would not be able to pick up the module unless installed systemwide:
  37
+
  38
+<pre>
  39
+[~] python
  40
+Python 2.5.1 (r251:54863, Jul 23 2008, 11:00:16) 
  41
+[GCC 4.0.1 (Apple Inc. build 5465)] on darwin
  42
+Type "help", "copyright", "credits" or "license" for more information.
  43
+>>> import googleanalytics
  44
+Traceback (most recent call last):
  45
+  File "<stdin>", line 1, in <module>
  46
+ImportError: No module named googleanalytics
  47
+>>>
  48
+</pre>
  49
+
  50
+### Environments ###
  51
+
  52
+I strongly suggest developing in a virtual environment using [virtualenv](http://pypi.python.org/pypi/virtualenv) with its own Python interpreter.  You don't have to, but you might find your python development experience is a little nicer.
  53
+
  54
+If you plan on using virtualenv, I then highly reccomend you get Doug Hellmann's `virtualenvwrapper` running which simplified the process of creating and managing virtual environment like so:
  55
+
  56
+*Switching to a new environment:*
  57
+
  58
+<pre>
  59
+[~] workon python-googleanalytics
  60
+(python-googleanalytics)[~]
  61
+</pre>
  62
+
  63
+*Listing environments:*
  64
+
  65
+<pre>
  66
+(python-googleanalytics)[~] workon
  67
+ars-django-project
  68
+ars_shortner
  69
+google_traffic
  70
+python-googleanalytics
  71
+test
  72
+writer_tracker
  73
+(python-googleanalytics)[~]
  74
+</pre>
  75
+
  76
+*Creating new environments:*
  77
+
  78
+<pre>
  79
+(python-googleanalytics)[~] mkvirtualenv test2
  80
+New python executable in test2/bin/python
  81
+Installing setuptools............done.
  82
+(test2)[~]
  83
+</pre>
  84
+
  85
+## Testing ##
  86
+
  87
+Run tests as follows (once you've bootstrapped buildout or installed the module globally):
  88
+
  89
+`./bin/test`
49  README.md
Source Rendered
... ...
@@ -1,47 +1,14 @@
1 1
 A Python client for accessing Google Analytics data
2 2
 ===================================================
3 3
 
4  
-Not much info here but I'm working off the documentation [here](http://code.google.com/apis/analytics/docs/gdata/gdataDeveloperGuide.html)
  4
+  * [The Google Analyics API Protocol]](http://code.google.com/apis/analytics/docs/gdata/gdataDeveloperGuide.html)
  5
+  * For information on how to use the model, please read the ./USAGE.md file.
  6
+  * Information on how to install the module and tips on efficient development methodologies, please read ./INSTALL.md
  7
+  * The license for this project, the BSD License, can be found in ./LICENSE
  8
+  * A list of authors and contributors is found in ./AUTHORS
5 9
 
6  
-### Credentials ###
  10
+The URL for this project is here: 
7 11
 
8  
-You should put your Google Credentials in a file in your home directory called `.pythongoogleanalytics`. This is a ini style config file and should look like this:
  12
+http://github.com/clintecker/python-googleanalytics
9 13
 
10  
-<pre>
11  
-[Credentials]
12  
-google_account_email = youraccount@gmail.com
13  
-google_account_password = yourpassword
14  
-</pre>
15  
-
16  
-If you want to take full advantage of the test suite, you'll need to add another section with a few valid profile IDs from the account you're testing.  Add these as follows:
17  
-
18  
-<pre>
19  
-[Accounts]
20  
-test_profile_ids = 28192 1928329 1029
21  
-</pre>
22  
-
23  
-If you don't add these, we can't really test any future data pulling, and some of the account stuff.  In the future perhaps we can build a list of accounts from get_all_accounts and proceed that way.
24  
-
25  
-### Installation ###
26  
-
27  
-Theoretically you should be able to type the following after checking out the source:
28  
-
29  
-`sudo python setup.py install`
30  
-
31  
-### Development ###
32  
-
33  
-I'm trying to use Buildout, so you can start helping out with development by checking out the source and typing the following:
34  
-
35  
-`python bootstrap.py && ./bin/buildout`
36  
-
37  
-Run tests as follows:
38  
-
39  
-`./bin/test`
40  
-
41  
-Most of the action is in `googleanalytics.connection` for the moment.
42  
-
43  
-### Usage ###
44  
-
45  
-Check out the `tests.py` file for details on how to use the library.  There's not much here at the moment.
46  
-
47  
-If it's not obvious I've modeled a lot of of what I've done so far off the [Boto Amazon Web Services client](http://code.google.com/p/boto/).
  14
+You can reach the primary developer of this module, Clint Ecker, at me@clintecker.com
156  USAGE.md
Source Rendered
... ...
@@ -0,0 +1,156 @@
  1
+Usage
  2
+=====
  3
+
  4
+### Getting started ###
  5
+
  6
+You initiate the process by importing the `googleanalytics.Connection` class.  This object is used to authorize against GA and contains the machinery to make requests to GA, and maintains your authorization token.  Speaking of your Google Credentials, you can specify these in two ways.  The first, which I like, is to create a configuration file in your home directory named `.pythongoogleanalytics`.  Populate it like this:
  7
+
  8
+<pre>
  9
+[Credentials]
  10
+google_account_email = youraccount@gmail.com
  11
+google_account_password = yourpassword
  12
+</pre>
  13
+
  14
+The second method is to supply the credentials directly to the Connection object in your code like so:
  15
+
  16
+<pre>
  17
+>>> from googleanalytics import Connection
  18
+>>> connection = Connection('clintecker@gmail.com', 'fakefake')
  19
+</pre>
  20
+
  21
+If you are using the former (~/.pythongoogleanalytics) method, you can just make naked `Connection()` calls to set up your connection object.
  22
+
  23
+### Listing/getting accounts ###
  24
+
  25
+You can retrieve a list of profiles associated with your account like so:
  26
+
  27
+<pre>
  28
+>>> from googleanalytics import Connection
  29
+>>> connection = Connection('clintecker@gmail.com', 'fakefake')
  30
+>>> accounts = connection.get_accounts()
  31
+</pre>
  32
+
  33
+This will return a list of account objects which you could use to retrieve data.  The `Connection.get_accounts` method also accepts pagination parameters:
  34
+
  35
+`>>> accounts = connection.get_accounts(start_index=10, max_results=5)`
  36
+
  37
+Both are optional. `start_index` defaults to 1 (the listing is 1-indexed), and `max_results` defaults to `None` which means a naked call just returns all your accounts.
  38
+
  39
+*Alternatively*: If you know the profile ID you want to use, you can use the `Connection.get_account` method.  This currently does no validation, so if you provide an invalid profile ID you can expect things to break. It works like you might expect:
  40
+
  41
+`>>> account = connection.get_account('1234')`
  42
+
  43
+### Retrieving Data ###
  44
+
  45
+Once you have an `Account` object you can start pulling data from it.  Reports are built by specifying a combinations of _dimensions_ and _metrics_.  Dimensions are things like Browsers, Platforms, PagePath. Metrics are generally numerical data like pageviews, visits, percentages, elapsed time, and so forth.  Google has a [long reference to these here](http://code.google.com/apis/analytics/docs/gdata/gdataReferenceDimensionsMetrics.html).
  46
+
  47
+Google specifies all these with `ga:` prepended to each dimension or metric.  Right now I require you don't specify the `ga:` part.  What I mean is that when you want `ga:pagePath` you pass in `pagePath`.  Leave off the `ga:` for now.
  48
+
  49
+In addition to dimensions and metrics you can specify sorting and filtering parameters, both optional.  *Definitely required* though are lower and upper bounds to the time frame you wish to gather data from.  These can be `datetime.datetime` or `datetime.date` objects.  Here's a really basic call:
  50
+
  51
+<pre>
  52
+>>> from googleanalytics import Connection
  53
+>>> import datetime
  54
+>>> connection = Connection('clintecker@gmail.com', 'fakefake')
  55
+>>> account = connection.get_account('1234')
  56
+>>> start_date = datetime.date(2009, 04, 10)
  57
+>>> end_date = datetime.date(2009, 04, 10)
  58
+>>> account.get_data(start_date=start_date, end_date=end_date)
  59
+[]
  60
+</pre>
  61
+
  62
+This will, of course, return no data (no dimensions or metrics specified), but is valid.
  63
+
  64
+Here's one that would give you some good data, a list of browsers that accessed your site in your timeframe and how many page views each of those browsers generated.
  65
+
  66
+<pre>
  67
+>>> from googleanalytics import Connection
  68
+>>> import datetime
  69
+>>> connection = Connection('clintecker@gmail.com', 'fakefake')
  70
+>>> account = connection.get_account('1234')
  71
+>>> start_date = datetime.date(2009, 04, 10)
  72
+>>> end_date = datetime.date(2009, 04, 10)
  73
+>>> account.get_data(start_date=start_date, end_date=end_date, dimensions=['browser',], metrics=['pageviews',])
  74
+[&lt;DataPoint: ga:6367750 / ga:browser=Chrome&gt;, &lt;DataPoint: ga:6367750 / ga:browser=Firefox&gt;, &lt;DataPoint: ga:6367750 / ga:browser=Internet Explorer&gt;, &lt;DataPoint: ga:6367750 / ga:browser=Mozilla Compatible Agent&gt;, &lt;DataPoint: ga:6367750 / ga:browser=Safari&gt;]
  75
+</pre>
  76
+
  77
+You could get Google to sort that for you (note FireFox is first now):
  78
+
  79
+<pre>
  80
+>>> from googleanalytics import Connection
  81
+>>> import datetime
  82
+>>> connection = Connection('clintecker@gmail.com', 'fakefake')
  83
+>>> account = connection.get_account('1234')
  84
+>>> start_date = datetime.date(2009, 04, 10)
  85
+>>> end_date = datetime.date(2009, 04, 10)
  86
+>>> account.get_data(start_date=start_date, end_date=end_date, dimensions=['browser',], metrics=['pageviews',], sort=['-pageviews',])
  87
+[&lt;DataPoint: ga:6367750 / ga:browser=Firefox&gt;, &lt;DataPoint: ga:6367750 / ga:browser=Internet Explorer&gt;, &lt;DataPoint: ga:6367750 / ga:browser=Safari&gt;, &lt;DataPoint: ga:6367750 / ga:browser=Chrome&gt;, &lt;DataPoint: ga:6367750 / ga:browser=Mozilla Compatible Agent&gt;]
  88
+</pre>
  89
+
  90
+And you could do some fun filtering, get a list of browsers, sorted descending by page views, and filtered to only contain browser strings which match the three regexs below (starting with Fire OR Internet OR Saf):
  91
+
  92
+<pre>
  93
+>>> from googleanalytics import Connection
  94
+>>> import datetime
  95
+>>> connection = Connection('clintecker@gmail.com', 'fakefake')
  96
+>>> account = connection.get_account('1234')
  97
+>>> start_date = datetime.date(2009, 04, 10)
  98
+>>> end_date = datetime.date(2009, 04, 10)
  99
+>>> filters = [
  100
+...   ['browser', '=~', '^Fire', 'OR'],
  101
+...   ['browser', '=~', '^Internet', 'OR'],
  102
+...   ['browser', '=~', '^Saf'],
  103
+... ]
  104
+>>> account.get_data(start_date=start_date, end_date=end_date, dimensions=['browser',], metrics=['pageviews',], sort=['-pageviews',], filters=filters)
  105
+[&lt;DataPoint: ga:6367750 / ga:browser=Firefox&gt;, &lt;DataPoint: ga:6367750 / ga:browser=Internet Explorer&gt;, &lt;DataPoint: ga:6367750 / ga:browser=Safari&gt;]
  106
+</pre>
  107
+
  108
+### Data ###
  109
+
  110
+At this point you should be asking me how this data is returned to you.  In the above examples, the data is returned as a `googleanalytics.data.DataSet` object which is essentially a Python list with three "properties" (`list`/`tuple`/`dict`) added to it.  This list is populated with `googleanalytics.data.DataPoint` objects.  Each of these has an associated dimension and metric (i.e. "Firefox" and "30293") and a little more data.
  111
+
  112
+So how do you get useful data?  You _could_ iterate over the `DataSet` and access each `DataPoint`'s metric and dimension properties directly, or you could output the whole dataset as a list of lists, tuple or tuples, or dictionary.  Example:
  113
+
  114
+<pre>
  115
+>>> from googleanalytics import Connection
  116
+>>> import datetime
  117
+>>> connection = Connection('clintecker@gmail.com', 'fakefake')
  118
+>>> account = connection.get_account('1234')
  119
+>>> start_date = datetime.date(2009, 04, 10)
  120
+>>> end_date = datetime.date(2009, 04, 10)
  121
+>>> data = account.get_data(start_date=start_date, end_date=end_date, dimensions=['browser',], metrics=['pageviews',], sort=['-pageviews',])
  122
+>>> data.list
  123
+[['Firefox', 21], ['Internet Explorer', 17], ['Safari', 17], ['Chrome', 6], ['Mozilla Compatible Agent', 5]]
  124
+>>> data.tuple
  125
+(('Firefox', 21), ('Internet Explorer', 17), ('Safari', 17), ('Chrome', 6), ('Mozilla Compatible Agent', 5))
  126
+>>> data.dict
  127
+{'Chrome': 6, 'Internet Explorer': 17, 'Firefox': 21, 'Safari': 17, 'Mozilla Compatible Agent': 5}
  128
+</pre>
  129
+
  130
+If you're concerned with the sort-order, you shouldn't really use the `dict` output as order isn't guaranteed.  `list` and `tuple` will retain the sorting order that Google Analytics output the data in.
  131
+
  132
+If you don't add these, we can't really test any future data pulling, and some of the account stuff.  In the future perhaps we can build a list of accounts from get_all_accounts and proceed that way.
  133
+
  134
+#### Pulling multiple dimensions/metrics ####
  135
+
  136
+Patrick Collison has graciously implemented pulling multiple metrics and data in a single request.  Instead of simple passing in a list with one metric or dimension, pass in as many as you like<sup>1</sup>
  137
+
  138
+<pre>
  139
+>>> from googleanalytics import Connection
  140
+>>> import datetime
  141
+>>> connection = Connection('clintecker@gmail.com', 'fakefake')
  142
+>>> account = connection.get_account('1234')
  143
+>>> end_date = datetime.datetime.today()
  144
+>>> start_date = end_date-datetime.timedelta(days=2)
  145
+>>> data = account.get_data(start_date=start_date, end_date=end_date, dimensions=['pageTitle', 'pagePath'], metrics=['pageviews','timeOnPage','entrances'], max_results=10)
  146
+>>> data
  147
+[<DataPoint: ga:7337113 / ga:pageTitle=How to find out more about Clint Ecker - Django Developer | ga:pagePath=/>]
  148
+>>> data.tuple
  149
+((['How to find out more about Clint Ecker - Django Developer', '/'], [5, '0.0', 5]),)
  150
+</pre>
  151
+
  152
+1: The Google Analytics generally caps you out around 7 or 10 as a maximum, so don't go too crazy ;)
  153
+
  154
+#### Pagination in data results ####
  155
+
  156
+Robert Kosera has added `max_results` and `start_index` to `account.get_data` and they work just like you might expect.  There are examples in tests.py
3  setup.py
@@ -9,7 +9,7 @@
9 9
 
10 10
 setup(
11 11
   name = "python-googleanalytics",
12  
-  version = "1.0",
  12
+  version = "1.0.2",
13 13
   url = 'http://github.com/clintecker/python-googleanalytics',
14 14
   license = 'BSD',
15 15
   description = "A python library for talking to the Google Analytics API",
@@ -28,6 +28,7 @@
28 28
     'License :: OSI Approved :: BSD License',
29 29
     'Operating System :: OS Independent',
30 30
     'Programming Language :: Python',
  31
+    'Programming Language :: Python :: 2.5',
31 32
     'Topic :: Internet',
32 33
   ]
33 34
 )

0 notes on commit aee9adf

Please sign in to comment.
Something went wrong with that request. Please try again.