clan 0.1.1 (alpha)

About

clan (Command Line ANalytics)

A command line utility for generating Google Analytics reports that are straightforward to compare across domains, projects or pages.

Important links:

Installation

Users

If you only want to use clan, install it this way:

pip install clan

Note

clan is intended for researchers and analysts. You will need to understand the Google Analytics API in order to use it effectively. It is not intended to generate reports for your boss.

Developers

If you are a developer that also wants to hack on clan, install it this way:

git clone git://github.com/onyxfish/clan.git
cd clan
mkvirtualenv --no-site-packages clan
pip install -r requirements.txt
python setup.py develop

Note

If you have a recent version of pip, you may need to run pip with the additional arguments --allow-external argparse.

Authentication

Before you use clan, you’re going to need to setup your access to the Google Analytics API. Follow the instructions in Google’s docs to register an application and create the client_secrets.json file.

Once you’ve got a client_secrets.json file, clan will walk you through acquiring an oAuth token:

clan auth

By default this token will be named analytics.dat. I suggest you move this file to ~/.clan_auth.dat. clan will always look for the auth in that location so you will only need one copy no matter what directory you are running clan from.

Basic usage

clan has two basic modes, 1) writing analytics data to a JSON file suitable for further processing and 2) writing data to a text report suitable for reading or emailing.

To configure clan, create a YAML data file describing the analytics you want to run:

# Global configuration, only property-id is required
property-id: "53470309"
start-date: "2014-06-01"
prefix: "/commencement/"

# Metrics to report
queries:
    - name: Totals
      metrics:
          - "ga:pageviews"
          - "ga:uniquePageviews"
          - "ga:users"
          - "ga:sessions"

    - name: Totals by device category
      metrics:
          - "ga:pageviews"
          - "ga:uniquePageviews"
          - "ga:users"
          - "ga:sessions"
      dimensions:
          - "ga:deviceCategory"
      sort:
          - "-ga:pageviews"

To run this report to a JSON file, run the following command. Note that by default clan will look for a YAML file called clan.yml. You can override this with the -c option. For complete documenation of this configuration, see Configuration.

clan report -f json analytics.json

Global configuration can also be specified as command arguments, allowing you to reuse a YAML configuration file for several properties or page sets. When specified, command-line arguments will always take precedence over variables in the YAML configuration.

clan report -f json --start-date 2014-05-1 --prefix /tshirt/ analytics.json

To instead produce a text report (the default), run:

clan report analytics.txt

You can also convert an existing JSON report to text, like so:

clan report -d analytics.json analytics.txt

Here is sample output for the above configuration:

Report run 2014-06-06 with:
    property-id: 53470309
    start-date: 2014-06-01
    prefix: /commencement/

Totals
(using 89.0% of data as sample)

    ga:pageviews
         88,935    100.0%    total

    ga:uniquePageviews
         60,179    100.0%    total

    ga:users
         21,244    100.0%    total

    ga:sessions
         26,817    100.0%    total


Totals by device category
(using 89.0% of data as sample)

    ga:pageviews
         64,542     72.6%    desktop
         15,403     17.3%    mobile
          8,991     10.1%    tablet
         88,936    100.0%    total

    ga:uniquePageviews
         40,966     68.1%    desktop
         12,277     20.4%    mobile
          6,936     11.5%    tablet
         60,179    100.0%    total

    ga:users
         12,838     60.4%    desktop
          6,084     28.6%    mobile
          2,322     10.9%    tablet
         21,244    100.0%    total

    ga:sessions
         16,014     59.7%    desktop
          7,644     28.5%    mobile
          3,159     11.8%    tablet
         26,817    100.0%    total

Authors

  • Christopher Groskopf

License

The MIT License

Copyright (c) 2014 Christopher Groskopf and contributers

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Changelog

0.1.1

  • Refactored to use command structure for CLI.
  • –ndays argument. (#10)
  • Document all configuration options. (#13)
  • Allow global configuration on command line. (#12)
  • Fixed .yaml extension to be .yml.

0.1.0

  • Initial version.

Indices and tables