Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Updating the documentation mostly

  • Loading branch information...
commit aee9adf9cbb494890626ba2fa22827747e0b1231 1 parent c872594
Clinton Ecker authored
Showing with 281 additions and 42 deletions.
  1. +11 −0 AUTHORS
  2. +15 −0 CHANGES
  3. +89 −0 INSTALL.md
  4. +8 −41 README.md
  5. +156 −0 USAGE.md
  6. +2 −1  setup.py
View
11 AUTHORS
@@ -0,0 +1,11 @@
+Pinax was started by Clint Ecker in April 2009.
+
+The PRIMARY AUTHORS are:
+
+ * Clint Ecker <me@clintecker.com>
+
+ADDITIONAL CONTRIBUTORS include:
+
+ * Robera Kosara
+ * Michael Greene
+ * Patrick Collison
View
15 CHANGES
@@ -0,0 +1,15 @@
+April 26: 1.0.2 Released
+
+ * 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.
+ * Updated documentation and split out information into INSTALL/USAGE/README/AUTHORS so people can find information more easily.
+
+April 25: 1.0.1 Released
+
+ * Fixed a small issue with the setup.py that was causing easy_install to break.
+
+April 24: 1.0 Released
+
+ * Basic client with almost all functionality exposed as outlined in my blog post:
+ http://blog.clintecker.com/post/100021441/python-google-analytics-client-how-to-use-it-and-how
+
+April 22: Started Development
View
89 INSTALL.md
@@ -0,0 +1,89 @@
+Installation
+============
+
+Theoretically you should be able to type the following after checking out the source:
+
+`sudo python setup.py install`
+
+You can also just install using `easy_install` like so:
+
+`sudo easy_install python-googleanalytics`
+
+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.
+
+## Development ##
+
+I'm trying to use Buildout, so you can start helping out with development by checking out the source and typing the following:
+
+<pre>
+git clone git://github.com/clintecker/python-googleanalytics.git
+python bootstrap.py && ./bin/buildout
+</pre>
+
+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:
+
+`./bin/python`
+
+It should work like so:
+
+<pre>
+(python-googleanalytics)[master][~/src/python-googleanalytics] ./bin/python
+
+>>> import googleanalytics
+>>>
+</pre>
+
+The system Python interpreter would not be able to pick up the module unless installed systemwide:
+
+<pre>
+[~] python
+Python 2.5.1 (r251:54863, Jul 23 2008, 11:00:16)
+[GCC 4.0.1 (Apple Inc. build 5465)] on darwin
+Type "help", "copyright", "credits" or "license" for more information.
+>>> import googleanalytics
+Traceback (most recent call last):
+ File "<stdin>", line 1, in <module>
+ImportError: No module named googleanalytics
+>>>
+</pre>
+
+### Environments ###
+
+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.
+
+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:
+
+*Switching to a new environment:*
+
+<pre>
+[~] workon python-googleanalytics
+(python-googleanalytics)[~]
+</pre>
+
+*Listing environments:*
+
+<pre>
+(python-googleanalytics)[~] workon
+ars-django-project
+ars_shortner
+google_traffic
+python-googleanalytics
+test
+writer_tracker
+(python-googleanalytics)[~]
+</pre>
+
+*Creating new environments:*
+
+<pre>
+(python-googleanalytics)[~] mkvirtualenv test2
+New python executable in test2/bin/python
+Installing setuptools............done.
+(test2)[~]
+</pre>
+
+## Testing ##
+
+Run tests as follows (once you've bootstrapped buildout or installed the module globally):
+
+`./bin/test`
View
49 README.md
@@ -1,47 +1,14 @@
A Python client for accessing Google Analytics data
===================================================
-Not much info here but I'm working off the documentation [here](http://code.google.com/apis/analytics/docs/gdata/gdataDeveloperGuide.html)
+ * [The Google Analyics API Protocol]](http://code.google.com/apis/analytics/docs/gdata/gdataDeveloperGuide.html)
+ * For information on how to use the model, please read the ./USAGE.md file.
+ * Information on how to install the module and tips on efficient development methodologies, please read ./INSTALL.md
+ * The license for this project, the BSD License, can be found in ./LICENSE
+ * A list of authors and contributors is found in ./AUTHORS
-### Credentials ###
+The URL for this project is here:
-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:
+http://github.com/clintecker/python-googleanalytics
-<pre>
-[Credentials]
-google_account_email = youraccount@gmail.com
-google_account_password = yourpassword
-</pre>
-
-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:
-
-<pre>
-[Accounts]
-test_profile_ids = 28192 1928329 1029
-</pre>
-
-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.
-
-### Installation ###
-
-Theoretically you should be able to type the following after checking out the source:
-
-`sudo python setup.py install`
-
-### Development ###
-
-I'm trying to use Buildout, so you can start helping out with development by checking out the source and typing the following:
-
-`python bootstrap.py && ./bin/buildout`
-
-Run tests as follows:
-
-`./bin/test`
-
-Most of the action is in `googleanalytics.connection` for the moment.
-
-### Usage ###
-
-Check out the `tests.py` file for details on how to use the library. There's not much here at the moment.
-
-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/).
+You can reach the primary developer of this module, Clint Ecker, at me@clintecker.com
View
156 USAGE.md
@@ -0,0 +1,156 @@
+Usage
+=====
+
+### Getting started ###
+
+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:
+
+<pre>
+[Credentials]
+google_account_email = youraccount@gmail.com
+google_account_password = yourpassword
+</pre>
+
+The second method is to supply the credentials directly to the Connection object in your code like so:
+
+<pre>
+>>> from googleanalytics import Connection
+>>> connection = Connection('clintecker@gmail.com', 'fakefake')
+</pre>
+
+If you are using the former (~/.pythongoogleanalytics) method, you can just make naked `Connection()` calls to set up your connection object.
+
+### Listing/getting accounts ###
+
+You can retrieve a list of profiles associated with your account like so:
+
+<pre>
+>>> from googleanalytics import Connection
+>>> connection = Connection('clintecker@gmail.com', 'fakefake')
+>>> accounts = connection.get_accounts()
+</pre>
+
+This will return a list of account objects which you could use to retrieve data. The `Connection.get_accounts` method also accepts pagination parameters:
+
+`>>> accounts = connection.get_accounts(start_index=10, max_results=5)`
+
+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.
+
+*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:
+
+`>>> account = connection.get_account('1234')`
+
+### Retrieving Data ###
+
+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).
+
+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.
+
+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:
+
+<pre>
+>>> from googleanalytics import Connection
+>>> import datetime
+>>> connection = Connection('clintecker@gmail.com', 'fakefake')
+>>> account = connection.get_account('1234')
+>>> start_date = datetime.date(2009, 04, 10)
+>>> end_date = datetime.date(2009, 04, 10)
+>>> account.get_data(start_date=start_date, end_date=end_date)
+[]
+</pre>
+
+This will, of course, return no data (no dimensions or metrics specified), but is valid.
+
+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.
+
+<pre>
+>>> from googleanalytics import Connection
+>>> import datetime
+>>> connection = Connection('clintecker@gmail.com', 'fakefake')
+>>> account = connection.get_account('1234')
+>>> start_date = datetime.date(2009, 04, 10)
+>>> end_date = datetime.date(2009, 04, 10)
+>>> account.get_data(start_date=start_date, end_date=end_date, dimensions=['browser',], metrics=['pageviews',])
+[&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;]
+</pre>
+
+You could get Google to sort that for you (note FireFox is first now):
+
+<pre>
+>>> from googleanalytics import Connection
+>>> import datetime
+>>> connection = Connection('clintecker@gmail.com', 'fakefake')
+>>> account = connection.get_account('1234')
+>>> start_date = datetime.date(2009, 04, 10)
+>>> end_date = datetime.date(2009, 04, 10)
+>>> account.get_data(start_date=start_date, end_date=end_date, dimensions=['browser',], metrics=['pageviews',], sort=['-pageviews',])
+[&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;]
+</pre>
+
+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):
+
+<pre>
+>>> from googleanalytics import Connection
+>>> import datetime
+>>> connection = Connection('clintecker@gmail.com', 'fakefake')
+>>> account = connection.get_account('1234')
+>>> start_date = datetime.date(2009, 04, 10)
+>>> end_date = datetime.date(2009, 04, 10)
+>>> filters = [
+... ['browser', '=~', '^Fire', 'OR'],
+... ['browser', '=~', '^Internet', 'OR'],
+... ['browser', '=~', '^Saf'],
+... ]
+>>> account.get_data(start_date=start_date, end_date=end_date, dimensions=['browser',], metrics=['pageviews',], sort=['-pageviews',], filters=filters)
+[&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;]
+</pre>
+
+### Data ###
+
+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.
+
+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:
+
+<pre>
+>>> from googleanalytics import Connection
+>>> import datetime
+>>> connection = Connection('clintecker@gmail.com', 'fakefake')
+>>> account = connection.get_account('1234')
+>>> start_date = datetime.date(2009, 04, 10)
+>>> end_date = datetime.date(2009, 04, 10)
+>>> data = account.get_data(start_date=start_date, end_date=end_date, dimensions=['browser',], metrics=['pageviews',], sort=['-pageviews',])
+>>> data.list
+[['Firefox', 21], ['Internet Explorer', 17], ['Safari', 17], ['Chrome', 6], ['Mozilla Compatible Agent', 5]]
+>>> data.tuple
+(('Firefox', 21), ('Internet Explorer', 17), ('Safari', 17), ('Chrome', 6), ('Mozilla Compatible Agent', 5))
+>>> data.dict
+{'Chrome': 6, 'Internet Explorer': 17, 'Firefox': 21, 'Safari': 17, 'Mozilla Compatible Agent': 5}
+</pre>
+
+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.
+
+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.
+
+#### Pulling multiple dimensions/metrics ####
+
+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>
+
+<pre>
+>>> from googleanalytics import Connection
+>>> import datetime
+>>> connection = Connection('clintecker@gmail.com', 'fakefake')
+>>> account = connection.get_account('1234')
+>>> end_date = datetime.datetime.today()
+>>> start_date = end_date-datetime.timedelta(days=2)
+>>> data = account.get_data(start_date=start_date, end_date=end_date, dimensions=['pageTitle', 'pagePath'], metrics=['pageviews','timeOnPage','entrances'], max_results=10)
+>>> data
+[<DataPoint: ga:7337113 / ga:pageTitle=How to find out more about Clint Ecker - Django Developer | ga:pagePath=/>]
+>>> data.tuple
+((['How to find out more about Clint Ecker - Django Developer', '/'], [5, '0.0', 5]),)
+</pre>
+
+1: The Google Analytics generally caps you out around 7 or 10 as a maximum, so don't go too crazy ;)
+
+#### Pagination in data results ####
+
+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
View
3  setup.py
@@ -9,7 +9,7 @@
setup(
name = "python-googleanalytics",
- version = "1.0",
+ version = "1.0.2",
url = 'http://github.com/clintecker/python-googleanalytics',
license = 'BSD',
description = "A python library for talking to the Google Analytics API",
@@ -28,6 +28,7 @@
'License :: OSI Approved :: BSD License',
'Operating System :: OS Independent',
'Programming Language :: Python',
+ 'Programming Language :: Python :: 2.5',
'Topic :: Internet',
]
)
Please sign in to comment.
Something went wrong with that request. Please try again.