Metadata-Version: 1.1
Name: googleanalytics
Version: 0.2.0
Summary: A wrapper for the Google Analytics API.
Home-page: http://stdbrouw.github.com/python-google-analytics/
Author: Stijn Debrouwere
Author-email: stijn@stdout.be
License: MIT
Download-URL: http://www.github.com/stdbrouw/python-google-analytics/tarball/master
Description: `python-google-analytics` provides a light wrapper on top of Google's own Google Analytics API client for Python. It also includes a minimalistic command-line interface to explore your account.
        
        * **Authentication.** OAuth2 is a bit of a pain and we've made it easier.
        * **Querying.** Easier to query per week, month or year. Query using metric IDs or using their full names, whichever you think is nicer. Work with both the Core and the Live APIs.
        * **Reporting.** Iterate through the entire report or column-per-column.
        * **Exploration.** Traverse the account hierarchy from account to webproperty to profile to dimensions, both programmatically and with the included command-line interface.
        
        ## Authentication
        
        The newest Google Analytics API, v3, only supports authentication using OAuth2. It won't work with your account username and password. There's a few steps to get started.
        
        1. Go to https://console.developers.google.com/project and create a new project. This registers your application with Google.
        2. Click on your project, go to `APIs & auth` and then `Credentials`.
        3. Find your Client ID and Client secret. Optionally, add these to your environment variables, e.g. by adding `export GOOGLE_ANALYTICS_CLIENT_ID=...` (and so on) to your `~/.bashrc`
        
        Now we're ready to authenticate. If you've put the client secrets in the environment, you can use these environment variables to authenticate:
        
            import os
            import googleanalytics as ga
            accounts = ga.oauth.ask_and_authenticate(os.environ)
        
        `accounts` is a list of user accounts that your credentials have given you access to.
        
        If you didn't add the client secrets to your environment variables, you can also just pass them directly from your code:
        
            import googleanalytics as ga
            client = dict(
                client_id='myproj.apps.googleusercontent.com', 
                client_secret='mysecret'
            )
            accounts = ga.oauth.ask_and_authenticate(**client)
        
        ### Storing credentials
        
        If you'd like to store the OAuth2 tokens so you don't have to ask for permission every time you run your code, you can first request tokens and only later use them to authenticate, allowing you to save those tokens for later use. Here's one way that could work: 
        
            import googleanalytics as ga
            client = dict(
                client_id='myproj.apps.googleusercontent.com', 
                client_secret='mysecret'
            )
        
            if os.path.exists('tokens.json'):
                tokens = json.load(open('tokens.json'))
            else:
                tokens = ga.oauth.ask(**client)
                json.dump(tokens, open('tokens.json', 'w'), indent=4)
        
            accounts = ga.oauth.authenticate(**tokens)
        
        ## Querying
        
        The querying interface currently looks like this.
        
            account = accounts[0]
            webproperty = account.webproperties[0]
            profile = webproperty.profiles[0]
        
            print account.metrics
            print account.dimensions
            print account.metrics['pageviews'] == account.metrics['ga:pageviews']
        
            q = profile.query('pageviews').range('2014-06-01', days=5)
            report = q.execute()
            print report['pageviews']
        
        ## CLI
        
        `python-google-analytics` comes with a small command-line interface through the `gash` command. Use `--help` to find out more about how it works.
        
        The command-line interface currently comes with three subcommands: 
        
        * `auth`: get a Google Analytics OAuth token, given a client id and secret (provided as arguments, or procured from the environment)
        * `revoke`: revoke existing authentication, useful for debugging or when your existing tokens for some reason don't work anymore
        * `ls`: explore your account
        
        ## auth
        
        You may specify the `client_id` and `client_secret` on the 
        commandline, optionally prefaced with a short and more 
        easily-remembered name for this client.
        
        If no `client_id` and `client_secret` are specified, these 
        will be fetched from your environment variables, 
        by default these are in `GOOGLE_ANALYTICS_CLIENT_ID` and 
        `GOOGLE_ANALYTICS_CLIENT_SECRET` but you may specify a 
        suffix as the first argument to this command.
        
            # look in environment variables
            gash auth
        
            # look in `GOOGLE_ANALYTICS_CLIENT_ID_B` 
            # and `GOOGLE_ANALYTICS_CLIENT_SECRET_B`
            # environment variables
            gash auth b
            
            # specify client information on the command line
            gash auth myid mysecret
        
            # optionally specify a more readable client name 
            # for later reference
            gash auth mynick myid mysecret
        
        ## revoke
        
            gash revoke <name>
        
        ## ls
        
            # show all of your accounts
            gash ls myproj
            # show all of the web properties for an account
            gash ls myproj myacc
            # show all of the profiles for a web property
            gash ls myproj myacc myprop
            # show all of the columns (metrics and dimensions) for a profile
            gash ls myproj myacc myprop myprof
            gash ls myproj . . .
            # find all metrics and dimensions that have "queried" in their name
            gash ls myproj myacc . . queried
Keywords: data analytics api wrapper google
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Topic :: Scientific/Engineering :: Information Analysis
