diff --git a/doc/source/remote_data.rst b/doc/source/remote_data.rst index f4c9d6a24cea2..ac9b6c9aecc4a 100644 --- a/doc/source/remote_data.rst +++ b/doc/source/remote_data.rst @@ -27,14 +27,14 @@ Remote Data Access .. _remote_data.data_reader: -Functions from :mod:`pandas.io.data` extract data from various Internet -sources into a DataFrame. Currently the following sources are supported: +Functions from :mod:`pandas.io.data` and :mod:`pandas.io.ga` extract data from various Internet sources into a DataFrame. Currently the following sources are supported: - - Yahoo! Finance - - Google Finance - - St. Louis FED (FRED) - - Kenneth French's data library - - World Bank + - :ref:`Yahoo! Finance` + - :ref:`Google Finance` + - :ref:`St.Louis FED (FRED)` + - :ref:`Kenneth French's data library` + - :ref:`World Bank` + - :ref:`Google Analytics` It should be noted, that various sources support different kinds of data, so not all sources implement the same methods and the data elements returned might also differ. @@ -330,7 +330,62 @@ indicators, or a single "bad" (#4 above) country code). See docstrings for more info. +.. _remote_data.ga: +Google Analytics +---------------- +The :mod:`~pandas.io.ga` module provides a wrapper for +`Google Analytics API `__ +to simplify retrieving traffic data. +Result sets are parsed into a pandas DataFrame with a shape and data types +derived from the source table. +Configuring Access to Google Analytics +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The first thing you need to do is to setup accesses to Google Analytics API. Follow the steps below: + +#. In the `Google Developers Console `__ + #. enable the Analytics API + #. create a new project + #. create a new Client ID for an "Installed Application" (in the "APIs & auth / Credentials section" of the newly created project) + #. download it (JSON file) +#. On your machine + #. rename it to ``client_secrets.json`` + #. move it to the ``pandas/io`` module directory + +The first time you use the :func:`read_ga` funtion, a browser window will open to ask you to authentify to the Google API. Do proceed. + +Using the Google Analytics API +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following will fetch users and pageviews (metrics) data per day of the week, for the first semester of 2014, from a particular property. + +.. code-block:: python + + import pandas.io.ga as ga + ga.read_ga( + account_id = "2360420", + profile_id = "19462946", + property_id = "UA-2360420-5", + metrics = ['users', 'pageviews'], + dimensions = ['dayOfWeek'], + start_date = "2014-01-01", + end_date = "2014-08-01", + index_col = 0, + filters = "pagePath=~aboutus;ga:country==France", + ) + +The only mandatory arguments are ``metrics,`` ``dimensions`` and ``start_date``. We can only strongly recommend you to always specify the ``account_id``, ``profile_id`` and ``property_id`` to avoid accessing the wrong data bucket in Google Analytics. + +The ``index_col`` argument indicates which dimension(s) has to be taken as index. + +The ``filters`` argument indicates the filtering to apply to the query. In the above example, the page has URL has to contain ``aboutus`` AND the visitors country has to be France. + +Detailed informations in the followings: + +* `pandas & google analytics, by yhat `__ +* `Google Analytics integration in pandas, by Chang She `__ +* `Google Analytics Dimensions and Metrics Reference `_ diff --git a/doc/source/whatsnew/v0.15.2.txt b/doc/source/whatsnew/v0.15.2.txt index a4d7c3969f056..84610716bd91f 100644 --- a/doc/source/whatsnew/v0.15.2.txt +++ b/doc/source/whatsnew/v0.15.2.txt @@ -43,6 +43,7 @@ Enhancements - Added ability to export Categorical data to Stata (:issue:`8633`). - Added ability to export Categorical data to to/from HDF5 (:issue:`7621`). Queries work the same as if it was an object array. However, the ``category`` dtyped data is stored in a more efficient manner. See :ref:`here ` for an example and caveats w.r.t. prior versions of pandas. +- Added Google Analytics (`pandas.io.ga`) basic documentation (:issue:`8835`). See :ref:`here`. .. _whatsnew_0152.performance: