| #!/usr/bin/python |
| # |
| # Copyright (C) 2006 Google Inc. |
| # Refactored in 2009 to work for Google Analytics by Sal Uryasev at Juice Inc. |
| # |
| # Licensed under the Apache License, Version 2.0 (the "License"); |
| # you may not use this file except in compliance with the License. |
| # You may obtain a copy of the License at |
| # |
| # http://www.apache.org/licenses/LICENSE-2.0 |
| # |
| # Unless required by applicable law or agreed to in writing, software |
| # distributed under the License is distributed on an "AS IS" BASIS, |
| # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| # See the License for the specific language governing permissions and |
| # limitations under the License. |
| |
| """ |
| AccountsService extends the GDataService to streamline Google Analytics |
| account information operations. |
| |
| AnalyticsDataService: Provides methods to query google analytics data feeds. |
| Extends GDataService. |
| |
| DataQuery: Queries a Google Analytics Data list feed. |
| |
| AccountQuery: Queries a Google Analytics Account list feed. |
| """ |
| |
| |
| __author__ = 'api.suryasev (Sal Uryasev)' |
| |
| |
| import urllib |
| import atom |
| import gdata.service |
| import gdata.analytics |
| |
| |
| class AccountsService(gdata.service.GDataService): |
| |
| """Client extension for the Google Analytics Account List feed.""" |
| |
| def __init__(self, email="", password=None, source=None, |
| server='www.google.com/analytics', additional_headers=None, |
| **kwargs): |
| """Creates a client for the Google Analytics service. |
| |
| Args: |
| email: string (optional) The user's email address, used for |
| authentication. |
| password: string (optional) The user's password. |
| source: string (optional) The name of the user's application. |
| server: string (optional) The name of the server to which a connection |
| will be opened. |
| **kwargs: The other parameters to pass to gdata.service.GDataService |
| constructor. |
| """ |
| |
| gdata.service.GDataService.__init__( |
| self, email=email, password=password, service='analytics', |
| source=source, server=server, additional_headers=additional_headers, |
| **kwargs) |
| |
| def QueryAccountListFeed(self, uri): |
| """Retrieves an AccountListFeed by retrieving a URI based off the Document |
| List feed, including any query parameters. An AccountListFeed object |
| can be used to construct these parameters. |
| |
| Args: |
| uri: string The URI of the feed being retrieved possibly with query |
| parameters. |
| |
| Returns: |
| An AccountListFeed object representing the feed returned by the server. |
| """ |
| return self.Get(uri, converter=gdata.analytics.AccountListFeedFromString) |
| |
| def GetAccountListEntry(self, uri): |
| """Retrieves a particular AccountListEntry by its unique URI. |
| |
| Args: |
| uri: string The unique URI of an entry in an Account List feed. |
| |
| Returns: |
| An AccountLisFeed object representing the retrieved entry. |
| """ |
| return self.Get(uri, converter=gdata.analytics.AccountListEntryFromString) |
| |
| def GetAccountList(self, max_results=1000, text_query=None, |
| params=None, categories=None): |
| """Retrieves a feed containing all of a user's accounts and profiles.""" |
| q = gdata.analytics.service.AccountQuery(max_results=max_results, |
| text_query=text_query, |
| params=params, |
| categories=categories); |
| return self.QueryAccountListFeed(q.ToUri()) |
| |
| |
| |
| |
| class AnalyticsDataService(gdata.service.GDataService): |
| |
| """Client extension for the Google Analytics service Data List feed.""" |
| |
| def __init__(self, email=None, password=None, source=None, |
| server='www.google.com/analytics', additional_headers=None, |
| **kwargs): |
| """Creates a client for the Google Analytics service. |
| |
| Args: |
| email: string (optional) The user's email address, used for |
| authentication. |
| password: string (optional) The user's password. |
| source: string (optional) The name of the user's application. |
| server: string (optional) The name of the server to which a connection |
| will be opened. Default value: 'docs.google.com'. |
| **kwargs: The other parameters to pass to gdata.service.GDataService |
| constructor. |
| """ |
| |
| gdata.service.GDataService.__init__(self, |
| email=email, password=password, service='analytics', source=source, |
| server=server, additional_headers=additional_headers, **kwargs) |
| |
| def GetData(self, ids='', dimensions='', metrics='', |
| sort='', filters='', start_date='', |
| end_date='', start_index='', |
| max_results=''): |
| """Retrieves a feed containing a user's data |
| |
| ids: comma-separated string of analytics accounts. |
| dimensions: comma-separated string of dimensions. |
| metrics: comma-separated string of metrics. |
| sort: comma-separated string of dimensions and metrics for sorting. |
| This may be previxed with a minus to sort in reverse order. |
| (e.g. '-ga:keyword') |
| If ommited, the first dimension passed in will be used. |
| filters: comma-separated string of filter parameters. |
| (e.g. 'ga:keyword==google') |
| start_date: start date for data pull. |
| end_date: end date for data pull. |
| start_index: used in combination with max_results to pull more than 1000 |
| entries. This defaults to 1. |
| max_results: maximum results that the pull will return. This defaults |
| to, and maxes out at 1000. |
| """ |
| q = gdata.analytics.service.DataQuery(ids=ids, |
| dimensions=dimensions, |
| metrics=metrics, |
| filters=filters, |
| sort=sort, |
| start_date=start_date, |
| end_date=end_date, |
| start_index=start_index, |
| max_results=max_results); |
| return self.AnalyticsDataFeed(q.ToUri()) |
| |
| def AnalyticsDataFeed(self, uri): |
| """Retrieves an AnalyticsListFeed by retrieving a URI based off the |
| Document List feed, including any query parameters. An |
| AnalyticsListFeed object can be used to construct these parameters. |
| |
| Args: |
| uri: string The URI of the feed being retrieved possibly with query |
| parameters. |
| |
| Returns: |
| An AnalyticsListFeed object representing the feed returned by the |
| server. |
| """ |
| return self.Get(uri, |
| converter=gdata.analytics.AnalyticsDataFeedFromString) |
| |
| """ |
| Account Fetching |
| """ |
| |
| def QueryAccountListFeed(self, uri): |
| """Retrieves an Account ListFeed by retrieving a URI based off the Account |
| List feed, including any query parameters. A AccountQuery object can |
| be used to construct these parameters. |
| |
| Args: |
| uri: string The URI of the feed being retrieved possibly with query |
| parameters. |
| |
| Returns: |
| An AccountListFeed object representing the feed returned by the server. |
| """ |
| return self.Get(uri, converter=gdata.analytics.AccountListFeedFromString) |
| |
| def GetAccountListEntry(self, uri): |
| """Retrieves a particular AccountListEntry by its unique URI. |
| |
| Args: |
| uri: string The unique URI of an entry in an Account List feed. |
| |
| Returns: |
| An AccountListEntry object representing the retrieved entry. |
| """ |
| return self.Get(uri, converter=gdata.analytics.AccountListEntryFromString) |
| |
| def GetAccountList(self, username="default", max_results=1000, |
| start_index=1): |
| """Retrieves a feed containing all of a user's accounts and profiles. |
| The username parameter is soon to be deprecated, with 'default' |
| becoming the only allowed parameter. |
| """ |
| if not username: |
| raise Exception("username is a required parameter") |
| q = gdata.analytics.service.AccountQuery(username=username, |
| max_results=max_results, |
| start_index=start_index); |
| return self.QueryAccountListFeed(q.ToUri()) |
| |
| class DataQuery(gdata.service.Query): |
| """Object used to construct a URI to a data feed""" |
| def __init__(self, feed='/feeds/data', text_query=None, |
| params=None, categories=None, ids="", |
| dimensions="", metrics="", sort="", filters="", |
| start_date="", end_date="", start_index="", |
| max_results=""): |
| """Constructor for Analytics List Query |
| |
| Args: |
| feed: string (optional) The path for the feed. (e.g. '/feeds/data') |
| |
| text_query: string (optional) The contents of the q query parameter. |
| This string is URL escaped upon conversion to a URI. |
| params: dict (optional) Parameter value string pairs which become URL |
| params when translated to a URI. These parameters are added to |
| the query's items. |
| categories: list (optional) List of category strings which should be |
| included as query categories. See gdata.service.Query for |
| additional documentation. |
| ids: comma-separated string of analytics accounts. |
| dimensions: comma-separated string of dimensions. |
| metrics: comma-separated string of metrics. |
| sort: comma-separated string of dimensions and metrics. |
| This may be previxed with a minus to sort in reverse order |
| (e.g. '-ga:keyword'). |
| If ommited, the first dimension passed in will be used. |
| filters: comma-separated string of filter parameters |
| (e.g. 'ga:keyword==google'). |
| start_date: start date for data pull. |
| end_date: end date for data pull. |
| start_index: used in combination with max_results to pull more than 1000 |
| entries. This defaults to 1. |
| max_results: maximum results that the pull will return. This defaults |
| to, and maxes out at 1000. |
| |
| Yields: |
| A DocumentQuery object used to construct a URI based on the Document |
| List feed. |
| """ |
| self.elements = {'ids': ids, |
| 'dimensions': dimensions, |
| 'metrics': metrics, |
| 'sort': sort, |
| 'filters': filters, |
| 'start-date': start_date, |
| 'end-date': end_date, |
| 'start-index': start_index, |
| 'max-results': max_results} |
| |
| gdata.service.Query.__init__(self, feed, text_query, params, categories) |
| |
| def ToUri(self): |
| """Generates a URI from the query parameters set in the object. |
| |
| Returns: |
| A string containing the URI used to retrieve entries from the Analytics |
| List feed. |
| """ |
| old_feed = self.feed |
| self.feed = '/'.join([old_feed]) + '?' + \ |
| urllib.urlencode(dict([(key, value) for key, value in \ |
| self.elements.iteritems() if value])) |
| new_feed = gdata.service.Query.ToUri(self) |
| self.feed = old_feed |
| return new_feed |
| |
| |
| class AccountQuery(gdata.service.Query): |
| """Object used to construct a URI to query the Google Account List feed""" |
| def __init__(self, feed='/feeds/accounts', start_index=1, |
| max_results=1000, username='default', text_query=None, |
| params=None, categories=None): |
| """Constructor for Account List Query |
| |
| Args: |
| feed: string (optional) The path for the feed. (e.g. '/feeds/documents') |
| visibility: string (optional) The visibility chosen for the current |
| feed. |
| projection: string (optional) The projection chosen for the current |
| feed. |
| text_query: string (optional) The contents of the q query parameter. |
| This string is URL escaped upon conversion to a URI. |
| params: dict (optional) Parameter value string pairs which become URL |
| params when translated to a URI. These parameters are added to |
| the query's items. |
| categories: list (optional) List of category strings which should be |
| included as query categories. See gdata.service.Query for |
| additional documentation. |
| username: string (deprecated) This value should now always be passed as |
| 'default'. |
| |
| Yields: |
| A DocumentQuery object used to construct a URI based on the Document |
| List feed. |
| """ |
| self.max_results = max_results |
| self.start_index = start_index |
| self.username = username |
| gdata.service.Query.__init__(self, feed, text_query, params, categories) |
| |
| def ToUri(self): |
| """Generates a URI from the query parameters set in the object. |
| |
| Returns: |
| A string containing the URI used to retrieve entries from the Account |
| List feed. |
| """ |
| old_feed = self.feed |
| self.feed = '/'.join([old_feed, self.username]) + '?' + \ |
| '&'.join(['max-results=' + str(self.max_results), |
| 'start-index=' + str(self.start_index)]) |
| new_feed = self.feed |
| self.feed = old_feed |
| return new_feed |
