| ckanext-ga-report | ckanext-ga-report |
| ================= | ================= |
| **Status:** Development | **Status:** Development |
| **CKAN Version:** 1.7.1+ | **CKAN Version:** 1.7.1+ |
| Overview | Overview |
| -------- | -------- |
| For creating detailed reports of CKAN analytics, including totals per group. | For creating detailed reports of CKAN analytics, including totals per group. |
| Whereas ckanext-googleanalytics focusses on providing page view stats a recent period and for all time (aimed at end users), ckanext-ga-report is more interested in building regular periodic reports (more for site managers to monitor). | Whereas ckanext-googleanalytics focusses on providing page view stats a recent period and for all time (aimed at end users), ckanext-ga-report is more interested in building regular periodic reports (more for site managers to monitor). |
| Contents of this extension: | Contents of this extension: |
| * Use the CLI tool to download Google Analytics data for each time period into this extension's database tables | * Use the CLI tool to download Google Analytics data for each time period into this extension's database tables |
| * Users can view the data as web page reports | * Users can view the data as web page reports |
| Installation | Installation |
| ------------ | ------------ |
| 1. Activate you CKAN python environment and install this extension's software:: | 1. Activate you CKAN python environment and install this extension's software:: |
| $ pyenv/bin/activate | $ pyenv/bin/activate |
| $ pip install -e git+https://github.com/okfn/ckanext-ga-report.git#egg=ckanext-ga-report | $ pip install -e git+https://github.com/okfn/ckanext-ga-report.git#egg=ckanext-ga-report |
| 2. Ensure you development.ini (or similar) contains the info about your Google Analytics account and configuration:: | 2. Ensure you development.ini (or similar) contains the info about your Google Analytics account and configuration:: |
| googleanalytics.id = UA-1010101-1 | googleanalytics.id = UA-1010101-1 |
| googleanalytics.account = Account name (i.e. data.gov.uk, see top level item at https://www.google.com/analytics) | googleanalytics.account = Account name (i.e. data.gov.uk, see top level item at https://www.google.com/analytics) |
| googleanalytics.username = googleaccount@gmail.com | |
| googleanalytics.password = googlepassword | |
| ga-report.period = monthly | ga-report.period = monthly |
| Note that your password will be readable by system administrators on your server. Rather than use sensitive account details, it is suggested you give access to the GA account to a new Google account that you create just for this purpose. | Note that your credentials will be readable by system administrators on your server. Rather than use sensitive account details, it is suggested you give access to the GA account to a new Google account that you create just for this purpose. |
| 3. Set up this extension's database tables using a paster command. (Ensure your CKAN pyenv is still activated, run the command from ``src/ckanext-ga-report``, alter the ``--config`` option to point to your site config file):: | 3. Set up this extension's database tables using a paster command. (Ensure your CKAN pyenv is still activated, run the command from ``src/ckanext-ga-report``, alter the ``--config`` option to point to your site config file):: |
| $ paster initdb --config=../ckan/development.ini | $ paster initdb --config=../ckan/development.ini |
| 4. Enable the extension in your CKAN config file by adding it to ``ckan.plugins``:: | 4. Enable the extension in your CKAN config file by adding it to ``ckan.plugins``:: |
| ckan.plugins = ga-report | ckan.plugins = ga-report |
| Authorization | Authorization |
| -------------- | -------------- |
| Before you can access the data, you need to set up the OAUTH details which you can do by following the `instructions <https://developers.google.com/analytics/resources/tutorials/hello-analytics-api>`_ the outcome of which will be a file called credentials.json which should look like credentials.json.template with the relevant fields completed. These steps are below for convenience: | Before you can access the data, you need to set up the OAUTH details which you can do by following the `instructions <https://developers.google.com/analytics/resources/tutorials/hello-analytics-api>`_ the outcome of which will be a file called credentials.json which should look like credentials.json.template with the relevant fields completed. These steps are below for convenience: |
| 1. Visit the `Google APIs Console <https://code.google.com/apis/console>`_ | 1. Visit the `Google APIs Console <https://code.google.com/apis/console>`_ |
| 2. Sign-in and create a project or use an existing project. | 2. Sign-in and create a project or use an existing project. |
| 3. In the `Services pane <https://code.google.com/apis/console#:services>`_ , activate Analytics API for your project. If prompted, read and accept the terms of service. | 3. In the `Services pane <https://code.google.com/apis/console#:services>`_ , activate Analytics API for your project. If prompted, read and accept the terms of service. |
| 4. Go to the `API Access pane <https://code.google.com/apis/console/#:access>`_ | 4. Go to the `API Access pane <https://code.google.com/apis/console/#:access>`_ |
| 5. Click Create an OAuth 2.0 client ID.... | 5. Click Create an OAuth 2.0 client ID.... |
| 6. Fill out the Branding Information fields and click Next. | 6. Fill out the Branding Information fields and click Next. |
| 7. In Client ID Settings, set Application type to Installed application. | 7. In Client ID Settings, set Application type to Installed application. |
| 8. Click Create client ID | 8. Click Create client ID |
| 9. The details you need below are Client ID, Client secret, and Redirect URIs | 9. The details you need below are Client ID, Client secret, and Redirect URIs |
| Once you have set up your credentials.json file you can generate an oauth token file by using the | Once you have set up your credentials.json file you can generate an oauth token file by using the |
| following command, which will store your oauth token in a file called token.dat once you have finished | following command, which will store your oauth token in a file called token.dat once you have finished |
| giving permission in the browser:: | giving permission in the browser:: |
| $ paster getauthtoken --config=../ckan/development.ini | $ paster getauthtoken --config=../ckan/development.ini |
| Tutorial | Tutorial |
| -------- | -------- |
| Download some GA data and store it in CKAN's db. (Ensure your CKAN pyenv is still activated, run the command from ``src/ckanext-ga-report``, alter the ``--config`` option to point to your site config file) and specifying the name of your auth file (token.dat by default) from the previous step:: | Download some GA data and store it in CKAN's db. (Ensure your CKAN pyenv is still activated, run the command from ``src/ckanext-ga-report``, alter the ``--config`` option to point to your site config file) and specifying the name of your auth file (token.dat by default) from the previous step:: |
| $ paster loadanalytics token.dat latest --config=../ckan/development.ini | $ paster loadanalytics token.dat latest --config=../ckan/development.ini |
| The value after the token file is how much data you want to retrieve, this can be | The value after the token file is how much data you want to retrieve, this can be |
| * **all** - data for all time (since 2010) | * **all** - data for all time (since 2010) |
| * **latest** - (default) just the 'latest' data | * **latest** - (default) just the 'latest' data |
| * **YYYY-MM-DD** - just data for all time periods going back to (and including) this date | * **YYYY-MM-DD** - just data for all time periods going back to (and including) this date |
| Software Licence | Software Licence |
| ================ | ================ |
| This software is developed by Cabinet Office. It is Crown Copyright and opened up under the Open Government Licence (OGL) (which is compatible with Creative Commons Attibution License). | This software is developed by Cabinet Office. It is Crown Copyright and opened up under the Open Government Licence (OGL) (which is compatible with Creative Commons Attibution License). |
| OGL terms: http://www.nationalarchives.gov.uk/doc/open-government-licence/ | OGL terms: http://www.nationalarchives.gov.uk/doc/open-government-licence/ |
| import logging | import logging |
| import datetime | import datetime |
| from pylons import config | from pylons import config |
| import ga_model | import ga_model |
| #from ga_client import GA | #from ga_client import GA |
| log = logging.getLogger('ckanext.ga-report') | log = logging.getLogger('ckanext.ga-report') |
| FORMAT_MONTH = '%Y-%m' | FORMAT_MONTH = '%Y-%m' |
| class DownloadAnalytics(object): | class DownloadAnalytics(object): |
| '''Downloads and stores analytics info''' | '''Downloads and stores analytics info''' |
| def __init__(self, service=None, profile_id=None): | def __init__(self, service=None, profile_id=None): |
| self.period = config['ga-report.period'] | self.period = config['ga-report.period'] |
| self.service = service | self.service = service |
| self.profile_id = profile_id | self.profile_id = profile_id |
| def all_(self): | def all_(self): |
| self.since_date(datetime.datetime(2010, 1, 1)) | self.since_date(datetime.datetime(2010, 1, 1)) |
| def latest(self): | def latest(self): |
| if self.period == 'monthly': | if self.period == 'monthly': |
| # from first of this month to today | # from first of this month to today |
| now = datetime.datetime.now() | now = datetime.datetime.now() |
| first_of_this_month = datetime.datetime(now.year, now.month, 1) | first_of_this_month = datetime.datetime(now.year, now.month, 1) |
| periods = ((now.strftime(FORMAT_MONTH), | periods = ((now.strftime(FORMAT_MONTH), |
| now.day, | now.day, |
| first_of_this_month, now),) | first_of_this_month, now),) |
| else: | else: |
| raise NotImplementedError | raise NotImplementedError |
| self.download_and_store(periods) | self.download_and_store(periods) |
| def since_date(self, since_date): | def since_date(self, since_date): |
| assert isinstance(since_date, datetime.datetime) | assert isinstance(since_date, datetime.datetime) |
| periods = [] # (period_name, period_complete_day, start_date, end_date) | periods = [] # (period_name, period_complete_day, start_date, end_date) |
| if self.period == 'monthly': | if self.period == 'monthly': |
| first_of_the_months_until_now = [] | first_of_the_months_until_now = [] |
| year = since_date.year | year = since_date.year |
| month = since_date.month | month = since_date.month |
| now = datetime.datetime.now() | now = datetime.datetime.now() |
| first_of_this_month = datetime.datetime(now.year, now.month, 1) | first_of_this_month = datetime.datetime(now.year, now.month, 1) |
| while True: | while True: |
| first_of_the_month = datetime.datetime(year, month, 1) | first_of_the_month = datetime.datetime(year, month, 1) |
| if first_of_the_month == first_of_this_month: | if first_of_the_month == first_of_this_month: |
| periods.append((now.strftime(FORMAT_MONTH), | periods.append((now.strftime(FORMAT_MONTH), |
| now.day, | now.day, |
| first_of_this_month, now)) | first_of_this_month, now)) |
| break | break |
| elif first_of_the_month < first_of_this_month: | elif first_of_the_month < first_of_this_month: |
| in_the_next_month = first_of_the_month + datetime.timedelta(40) | in_the_next_month = first_of_the_month + datetime.timedelta(40) |
| last_of_the_month = datetime.datetime(in_the_next_month.year, | last_of_the_month = datetime.datetime(in_the_next_month.year, |
| in_the_next_month.month, 1)\ | in_the_next_month.month, 1)\ |
| - datetime.timedelta(1) | - datetime.timedelta(1) |
| periods.append((now.strftime(FORMAT_MONTH), 0, | periods.append((now.strftime(FORMAT_MONTH), 0, |
| first_of_the_month, last_of_the_month)) | first_of_the_month, last_of_the_month)) |
| else: | else: |
| # first_of_the_month has got to the future somehow | # first_of_the_month has got to the future somehow |
| break | break |
| month += 1 | month += 1 |
| if month > 12: | if month > 12: |
| year += 1 | year += 1 |
| month = 1 | month = 1 |
| else: | else: |
| raise NotImplementedError | raise NotImplementedError |
| self.download_and_store(periods) | self.download_and_store(periods) |
| @staticmethod | @staticmethod |
| def get_full_period_name(period_name, period_complete_day): | def get_full_period_name(period_name, period_complete_day): |
| if period_complete_day: | if period_complete_day: |
| return period_name + ' (up to %ith)' % period_complete_day | return period_name + ' (up to %ith)' % period_complete_day |
| else: | else: |
| return period_name | return period_name |
| def download_and_store(self, periods): | def download_and_store(self, periods): |
| for period_name, period_complete_day, start_date, end_date in periods: | for period_name, period_complete_day, start_date, end_date in periods: |
| log.info('Downloading Analytics for period "%s" (%s - %s)', | log.info('Downloading Analytics for period "%s" (%s - %s)', |
| self.get_full_period_name(period_name, period_complete_day), | self.get_full_period_name(period_name, period_complete_day), |
| start_date.strftime('%Y %m %d'), | start_date.strftime('%Y %m %d'), |
| end_date.strftime('%Y %m %d')) | end_date.strftime('%Y %m %d')) |
| data = self.download(start_date, end_date) | data = self.download(start_date, end_date) |
| log.info('Storing Analytics for period "%s"', | log.info('Storing Analytics for period "%s"', |
| self.get_full_period_name(period_name, period_complete_day)) | self.get_full_period_name(period_name, period_complete_day)) |
| self.store(period_name, period_complete_day, data) | self.store(period_name, period_complete_day, data) |
| def download(self, start_date, end_date): | def download(self, start_date, end_date): |
| '''Get data from GA for a given time period''' | '''Get data from GA for a given time period''' |
| start_date = start_date.strftime('%Y-%m-%d') | start_date = start_date.strftime('%Y-%m-%d') |
| end_date = end_date.strftime('%Y-%m-%d') | end_date = end_date.strftime('%Y-%m-%d') |
| # url | |
| #query = 'ga:pagePath=~^%s,ga:pagePath=~^%s' % \ | |
| # (PACKAGE_URL, self.resource_url_tag) | |
| query = 'ga:pagePath=~/dataset/[a-z0-9-]+$' | query = 'ga:pagePath=~/dataset/[a-z0-9-]+$' |
| metrics = 'ga:uniquePageviews' | metrics = 'ga:uniquePageviews' |
| sort = '-ga:uniquePageviews' | sort = '-ga:uniquePageviews' |
| # Supported query params at | # Supported query params at |
| # https://developers.google.com/analytics/devguides/reporting/core/v3/reference | # https://developers.google.com/analytics/devguides/reporting/core/v3/reference |
| results = self.service.data().ga().get( | results = self.service.data().ga().get( |
| ids='ga:' + self.profile_id, | ids='ga:' + self.profile_id, |
| filters=query, | filters=query, |
| start_date=start_date, | start_date=start_date, |
| metrics=metrics, | metrics=metrics, |
| sort=sort, | sort=sort, |
| dimensions="ga:pagePath", | dimensions="ga:pagePath", |
| max_results=10000, | |
| end_date=end_date).execute() | end_date=end_date).execute() |
| import pprint | import pprint |
| pprint.pprint(results) | pprint.pprint(results) |
| print 'Total results: %s' % results.get('totalResults') | print 'Total results: %s' % results.get('totalResults') |
| packages = [] | packages = [] |
| for entry in results.get('rows'): | for entry in results.get('rows'): |
| (loc,size,) = entry | (loc,size,) = entry |
| packages.append( ('http:/' + loc,size, '',) ) | packages.append( ('http:/' + loc,size, '',) ) # Temporary hack |
| return dict(url=packages) | return dict(url=packages) |
| def print_results(self, results): | |
| import pprint | |
| pprint.pprint(results) | |
| if results: | |
| print 'Profile: %s' % results.get('profileInfo').get('profileName') | |
| print 'Total Visits: %s' % results.get('rows', [[-1]])[0][0] | |
| else: | |
| print 'No results found' | |
| def store(self, period_name, period_complete_day, data): | def store(self, period_name, period_complete_day, data): |
| if 'url' in data: | if 'url' in data: |
| ga_model.update_url_stats(period_name, period_complete_day, data['url']) | ga_model.update_url_stats(period_name, period_complete_day, data['url']) |
| import re | import re |
| import uuid | import uuid |
| from sqlalchemy import Table, Column, MetaData | from sqlalchemy import Table, Column, MetaData |
| from sqlalchemy import types | from sqlalchemy import types |
| from sqlalchemy.sql import select | from sqlalchemy.sql import select |
| from sqlalchemy.orm import mapper | from sqlalchemy.orm import mapper |
| from sqlalchemy import func | from sqlalchemy import func |
| import ckan.model as model | import ckan.model as model |
| from ckan.lib.base import * | from ckan.lib.base import * |
| def make_uuid(): | def make_uuid(): |
| return unicode(uuid.uuid4()) | return unicode(uuid.uuid4()) |
| class GA_Url(object): | class GA_Url(object): |
| def __init__(self, **kwargs): | def __init__(self, **kwargs): |
| for k,v in kwargs.items(): | for k,v in kwargs.items(): |
| setattr(self, k, v) | setattr(self, k, v) |
| metadata = MetaData() | metadata = MetaData() |
| url_table = Table('ga_url', metadata, | url_table = Table('ga_url', metadata, |
| Column('id', types.UnicodeText, primary_key=True, | Column('id', types.UnicodeText, primary_key=True, |
| default=make_uuid), | default=make_uuid), |
| Column('period_name', types.UnicodeText), | Column('period_name', types.UnicodeText), |
| Column('period_complete_day', types.Integer), | Column('period_complete_day', types.Integer), |
| Column('visits', types.Integer), | Column('metric', types.UnicodeText), |
| Column('value', types.UnicodeText), | |
| Column('url', types.UnicodeText), | Column('url', types.UnicodeText), |
| Column('next_page', types.UnicodeText), | Column('department_id', types.UnicodeText), |
| ) | ) |
| mapper(GA_Url, url_table) | mapper(GA_Url, url_table) |
| def init_tables(): | def init_tables(): |
| metadata.create_all(model.meta.engine) | metadata.create_all(model.meta.engine) |
| cached_tables = {} | cached_tables = {} |
| def get_table(name): | def get_table(name): |
| if name not in cached_tables: | if name not in cached_tables: |
| meta = MetaData() | meta = MetaData() |
| meta.reflect(bind=model.meta.engine) | meta.reflect(bind=model.meta.engine) |
| table = meta.tables[name] | table = meta.tables[name] |
| cached_tables[name] = table | cached_tables[name] = table |
| return cached_tables[name] | return cached_tables[name] |
| def _normalize_url(url): | def _normalize_url(url): |
| '''Strip off the hostname etc. Do this before storing it. | '''Strip off the hostname etc. Do this before storing it. |
| >>> normalize_url('http://data.gov.uk/dataset/weekly_fuel_prices') | >>> normalize_url('http://data.gov.uk/dataset/weekly_fuel_prices') |
| '/dataset/weekly_fuel_prices' | '/dataset/weekly_fuel_prices' |
| ''' | ''' |
| url = re.sub('https?://(www\.)?data.gov.uk', '', url) | url = re.sub('https?://(www\.)?data.gov.uk', '', url) |
| return url | return url |
| def _get_department_id_of_url(url): | def _get_department_id_of_url(url): |
| # e.g. /dataset/fuel_prices | # e.g. /dataset/fuel_prices |
| # e.g. /dataset/fuel_prices/resource/e63380d4 | # e.g. /dataset/fuel_prices/resource/e63380d4 |
| dataset_match = re.match('/dataset/([^/]+)(/.*)?', url) | dataset_match = re.match('/dataset/([^/]+)(/.*)?', url) |
| if dataset_match: | if dataset_match: |
| dataset_ref = dataset_match.groups()[0] | dataset_ref = dataset_match.groups()[0] |
| dataset = model.Package.get(dataset_ref) | dataset = model.Package.get(dataset_ref) |
| if dataset: | if dataset: |
| publisher_groups = dataset.get_groups('publisher') | publisher_groups = dataset.get_groups('publisher') |
| if publisher_groups: | if publisher_groups: |
| return publisher_groups[0].id | return publisher_groups[0].name |
| def update_url_stats(period_name, period_complete_day, url_data): | def update_url_stats(period_name, period_complete_day, url_data): |
| table = get_table('ga_url') | table = get_table('ga_url') |
| for url, views, next_page in url_data: | for url, views, next_page in url_data: |
| url = _normalize_url(url) | url = _normalize_url(url) |
| department_id = _get_department_id_of_url(url) | department_id = _get_department_id_of_url(url) |
| # see if the row for this url & month is in the table already | # see if the row for this url & month is in the table already |
| item = model.Session.query(GA_Url).filter(GA_Url.period_name==period_name).filter(GA_Url.url==url).first() | item = model.Session.query(GA_Url).\ |
| filter(GA_Url.period_name==period_name).\ | |