Google Analytics Reporting API Python Tutorial

• Download Python 2
Register your application for the Analytics API in Google Developers Console 
Download the Google Python API Sample Code
Google Analytics Query Explorer
Python Code to Output Google Analytics API Query Data to CSV *save file as .py

Check out this new post on how to pull over 1 million rows of unsampled data using Python & how to pull data from multiple profiles

Check out this new post on how to pull more than 10000 rows of unsampled data using the Google Analytics Sheets Add-on.

R users check out this tutorial on how to pull your first Google Analytics R v4 reporting API query.

This guide will go through step by step instructions on how to setup Python and pull your first query directly from the Google Analytics reporting API. I will show you how to install Python on Windows and add the Google API Python library. We will create a new project in the Google Developers Console and enable the Analytics API. Next we will use a prebuilt sample Python application to get data out of Google Analytics via the API. Then I’ll walk you through how to test your own query using the Google Analytics Query Explorer. Then we will edit the Python application code to create your very own query. And finally we will pull Google Analytics data directly into Excel using Python to write a CSV file containing the Google Analytics data.

1) Download the latest version of Python 2

Download the latest version of Python 2 for Windows by clicking on the yellow download button. At the time of this post the latest version was 2.7.10. Why Python 2 and not Python 3? The code example uses Python 2.

2) Install Python 2.7.10 on Windows

After you run the installer Python should be installed on your C drive in C:\Python27

3) Install the the Google API Python Client Library using pip

We are going to use the command line to install the Google API Python library. To access the command line click Start and then in the Search or Run type cmd then press enter. This will launch the command line.

Copy and paste the line below into the command line and press enter.

Note you will have to right click and paste in the command line because control v will not work. If everything installed properly you should see text saying “Successfully installed google-api-python-client-1.4.1” at the bottom on the screen like the image below.

pip install google analytics python
We are done using the command line so you can breathe a sigh of relief or let out a cheer.

With Python version 2.7.9 and later pip is included by default. What is pip? pip is a package management system used to install and manage software packages for Python.

4) Create a new Google Analytics API Project

Make sure you are logged into the Google Analytics user account that has access to the view (profile) you want to pull your API report from. Use this link to create a new Google Analytics project in the Google Developer console. This link will automatically enable the Google Analytics API for your project.

The video below goes through the steps.

Select Create a new project from the drop down and click continue

The default name will be My Project. Choose “My Project” from the top drop down

In the left nav under APIs & auth click on Credentials

Click on the OAuth consent screen just under the My Projects drop down at the top of the screen

The Product name field is required so add the name “Google Analytics Python Reporting API” then click Save

Click on the Add credentials blue dropdown in the center of the screen and click on OAuth 2.0 client ID in the drop down

Click on the Other radio button and add the name “Python Reporting API” then click create

Your client ID and client secret will be shown in an overlay on the screen click ok

Download the client_secret json file by clicking on the download icon on the far right

5) Download the Google Analytics API Python Client Samples

Download the Zip file for the full Google API Python client. I saved the folder on the desktop. Here is the link to the full code repository on GitHub  There are lots of different samples within the Google API Python client. We are using the Analytics sample files: https://github.com/google/google-api-python-client/tree/master/samples/analytics

Unzip and save the file. I saved the file on the desktop.

6) Add Your Google Analytics API Client Secret Credentials

In the Google API client samples folder you just saved, open the analytics sample folder.

\google-api-python-client-master\samples\analytics

Open the client_secrets.json file in a text editor. I use NotePad++. Right click edit with Notepad++. Delete all the text in this sample client_secret.json file.

Find the client_secret.json file that you created and downloaded from the Google Developer console at the end of Step 4. Open your client_secret.json file in NotePad++ and copy the text in your file (this has your API credentials) and paste the text into the sample client_secrets.json file that was in the analytics sample folder. Make sure to save the file.

7) Run your first Google Analytics Report Query using Python

In the analytics sample folder the path to the folder for me is C:\Users\ryan\Desktop\google-api-python-client-master\samples\analytics Right click hello_analytics_api_v3.py file and choose to Edit with IDLE. Do not double click the hello_analytics_api_v3.py file.

IDLE is the integrated development environment for Python

In the top nav menu go to Run > Run Modulerun hello_analytics_api_v3_module

The Python Shell should open and you should see a message in the Shell that says “Your browser has been opened to visit: https://accounts.google.com/o/oauth2/…”run hello_analytics_api_v3_shell_authenticate

Your browser will open asking you to Allow access to View your Google Analytics data for your Google Analytics Python API application. If you are logged in as multiple Google users and the application asks to authenticate for the wrong user, you can take the URL and copy and paste it in a browser window with the correct user logged in.

give access to python api project to view ga data

After clicking Allow you will see a web page with the message “The authentication flow has completed”

Back in the Python Shell you’ll now see the results of your query. You should see visits (sessions) to the top 25 organic keywords from January 1, 2012 to January 15, 2012 for the first view your Google Analytics user account has access to. If this query has no data for this time period or for these dimensions have no fear, in the next steps I’ll show you how to build your own query.

python_shell_base_query_results

8) Build your Own Google Analytics Query Using the Google Analytics Core Reporting API Query Explorer

We will get back to creating our own query in Python, but first let’s use the Google Analytics Query Explorer to create a query that we know will return data. Choose the Account, Property and View you’d like to get data from. Make sure that this is a view that has sessions data for the last 30 days. When you select a view the ids field will be populated with the unique Google Analytics view (profile) identifier.

You can also find your view (profile) ID in the Admin section of Google Analytics web interface in the View Settings for your specific view.

google_analytics_view_settings_view_id

We will run a very simple query. The default start-date is 30daysAgo and the default end-date is yesterday. Both these fields should be pre populated. In the metrics field type in sessions and choose Sessions from the drop down. This will populate ga:sessions in the metrics field. In the dimensions field type in date and choose Date from the drop down. This will populate ga:date in the dimensions field. Leave all the other fields blank and click the blue Run Query button.

google_analytics_query_explorer

The result of the query will be a report with sessions for the last 30 days shown by day. Leave this page open because we will use these fields in our Python query in the next step.

google_analytics_query_explorer_results

At the bottom of the page you will see the API Query URI. If you click to include the current access_token in the Query URI this is the actual API URL of your query.

google_analytics_query_explorer_api_query_url

You can copy this URL and paste into your browser and click enter to see the results of your query in the raw JSON format.

google_analytics_query_raw_json_result_browser

9) Use the Google Analytics Query Explorer Parameters in the Python Query Code

Now we are going to take the query we built using the query explorer and use this in Python. For those of you who didn’t get data in the previous Python query we know this query will return data because it returned data using query explorer. Make sure you have the query explorer with the results open because we will use the query parameters in the Python query.

In the analytics sample folder C:\Users\ryan\Desktop\google-api-python-client-master\samples\analytics Right click the hello_analytics_api_v3 file and open with NotePad++. Go to line 133 or search for “return service” in the code

The new query that we ran in the query explorer is below. Paste this query over the old query on line 133. Note that the fields are taken directly from the query explorer i.e. metrics=’ga:sessions’ and dimensions=’ga:date’

 

Next rather than choosing the first profile that your Google Analytics account has access to, we are going to use the view (profile) id that we used in the query explorer. Go to line 63 or search for  “first_profile_id = get_first_profile_id(service)”. Take the ids field value excluding the ga: and paste it into line 63 for the value of the first_profile_id variable. Make sure to put quotes around the profile id. See the example below.

first_profile_id = ‘12345789’

Save this file in NotePad++ with a new file name like hello_analytics_api_v3_2.py in the analytics samples folder C:\Users\ryan\Desktop\google-api-python-client-master\samples\analytics

Open this folder C:\Users\ryan\Desktop\google-api-python-client-master\samples\analytics and right click on the hello_analytics_api_v3_2.py file that we just create and choose Edit with IDLE.

In the top nav menu go to Run > Run Module

We already authenticated our Python application when we ran the previous query in Python so the browser won’t open this time.

In the Python Shell you’ll see the results of your new query, a report with sessions for the last 30 days shown by day.shell_sessions_past30days_data_python_query

10) Google Analytics API Python Query Data Output to Excel

You can now build your own queries and pull data directly from the Google Analytics API using Python, but you may be asking how can I get this data into Excel? Luckily, there is a csv module for Python which gives you convenient tools for reading and writing to CSV files.

The original Python file has been updated to include the necessary changes to output the data to a csv file. Open the new file. Save this file in the analytics sample folder (the file is a .txt file type, make sure to change the extension to a .py file type) C:\Users\ryan\Desktop\google-api-python-client-master\samples\analytics

Right click on the hello_analytics_api_v3_csv.py file and open with NotePad++.

Go to line 63 or search for  “first_profile_id =”. Take the ids field value (from the query explorer or your previous Python file) excluding the ga: and paste it into line 63 for the value of the first_profile_id variable.

Go to line 157 or search for “filepath =” and update the variable to your actual file path. I created a folder call Python Google Analytics Data on my desktop with the file path below:

C:\\Users\\ryan\\Desktop\\Python Google Analytics Data

Note you have to escape the \ in the file path thus the \\ you see in the filepath variable.

Go to line 158 or search for “filename =” and update the variable with what you want to call the file. The current name of the file is gapythondata.csv

Save this file in NotePad++ in the analytics samples folder C:\Users\ryan\Desktop\google-api-python-client-master\samples\analytics

Open this folder C:\Users\ryan\Desktop\google-api-python-client-master\samples\analytics and right click on the hello_analytics_api_v3_csv.py file that we just saved and choose Edit with IDLE.

In the top nav menu go to Run > Run Module

In the Python Shell you’ll see the results of your new query, a report with sessions for the last 30 days shown by day, but you’ll also see a new message printed at the bottom of the shell that says:

Success Data Written to CSV File
filepath = C:\Users\ryan\Desktop\Python Google Analytics Data
filename = gapythondata.csv

Go to the folder and open your csv file in Excel. Your data in Excel should look like the screenshot below:
gapythondata_csv_excel

***Make sure you change the filename in the Python code for each new query you run, otherwise Python will overwrite your previous csv file***

Summary

Congratulations, you are now ready to start writing your own queries! You can pull data directly from the Google Analytics Reporting API using Python. Even better, you can pull Google Analytics data directly into Excel using Python to write a CSV with the Google Analytics data. While you are getting the hang of the dimension and metrics names and syntax I urge you to use the Google Analytics Query Explorer to test all  your queries. You can have up to 7 dimensions and 10 metrics in any Google Analytics Reporting API query. You can see valid dimension and metric combinations here.

If you have any questions please let me know in the comments or on Twitter @ryanpraski. Thanks to Nick Mihailovski from Google for originally sharing this Python code and thanks to my teammate Ryan Miller for helping with all my Python questions.

  • Roman Kaye

    In step 7, instead of “Your browser has been opened to visit” in IDLE, I am receiving an error:

    usage: core_reporting_v3_reference.py [-h] [–auth_host_name AUTH_HOST_NAME]
    [–noauth_local_webserver]
    [–auth_host_port [AUTH_HOST_PORT [AUTH_HOST_PORT …]]]
    [–logging_level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]
    table_id
    core_reporting_v3_reference.py: error: the following arguments are required: table_id

    What could be causing this?

    UPD:

    I Shift+right-clicked in the directory with core_reporting_v3_reference.py;
    selected “Open command window here”;
    into the freshly-opened cmd.exe, I pasted “python core_reporting_v3_reference.py ga:(GA View ID)”;
    hit Enter.

    This is when I saw the “Your browser has been opened, etc” and authenticated successfully.

    • Ulises Sotomayor

      @ryanpraski ,

      Thank you this is very helpful!

      I’m having this same issue as @RomanKaye? AM I doing this right?

      https://uploads.disquscdn.com/images/212e3d82dad38540b6dbf3446026e1b94a296aa292e27d439ec537d7f5e3cbc2.png

      • Hi Ulises,

        You don’t need to alter the code at all to run the script in the command line. In the command line you need to put the full path to the script.py on your computer followed bye the GA:ViewID.

        Example:
        >core_reporting_v3_reference.py ga:123456789

        Let me know if this answers your question.

        -Ryan

        • Ulises Sotomayor

          Thank you! This worked! 🙂 Now I need to write the data into a CSV file, do you happen to know any useful sources for this integration?

  • @roman_kaye:disqus the examples uses the hello_analytics_api_v3.py file. Try running hello_analytics_api_v3.py file in IDLE instead the core_reporting_v3_reference.py file.

  • In case any else is curious you can authenticate and run queries in the command line using the method @roman_kaye:disqus describes by running the “python core_reporting_v3_reference.py ga:(GA View ID)” application in the command line. See this screen shot for how the successful authentication looks.

  • Roman Kaye

    Thank you for an enormously helpful guide.

    • That is awesome @roman_kaye:disqus! Would you be willing to share how you accomplished steps 2, 3, 4?

      • Roman Kaye

        Here’s the setup on Windows:

        1. Python script based on this tutorial. Will be referred to as Ryans_Tutorial.py in following steps. Produces the file “C:/analytics/GA_data_yesterday.csv”.

        2. Database upload script, referred to as “GAtoDB.py” below — http://pastebin.com/QyKMHWQE

        3. Batch file that runs the above on schedule — http://pastebin.com/4xgZczMY

        • Roman Kaye

          Argh, #3 does not just run the above on schedule — it also creates 2 copies of the CSV.

  • Petr Havlík

    Ryan, is there a way to avoid sampling by separating the query into many sub-queries, that are usually on daily basis?

    • There are a couple things you can do to deal with sampling. The first is to set the Sampling level to higher_precision in the query. This is the same as setting sampling to slower response, greater precision in the GA web interface.
      The next thing you can do is break your sampled query down into smaller pieces by limiting the date range as you have suggested. You can do this manually by changing the date range and rerunning the query or programmatically in the Python script using loops. Are other people interested in a post on dealing with Google Analytics sampling programmatically using Python? A couple people have asked this question so this could be a good topic for a future post.

  • Felix Zumstein

    Great tutorial! Check out my similar tutorial that uses Excel as a frontend rather than just spitting data out as csv: http://blog.zoomeranalytics.com/google-analytics/

  • Boris lazaro izquierdo

    great tutorial to pull data from Google Analytics!! Thanks Ryan!

  • David Linder

    For anyone trying to run the Hello Analytics python script from google’s github, it’s been outdated. Hopefully they update their github page soon. See this link for how to successfully authorize your api service key – https://developers.google.com/analytics/devguides/reporting/core/v3/quickstart/service-py

  • David Schuler

    For me these instructions failed at Step 3. I’ll keep debugging to see if I can figure it out on my own but I thought you’d want to know. I have attached a screen capture that illustrates the message that I received.

    • David Schuler

      I tried installing the client using one of the alternative installation methods on Google’s instruction page (used easy_install). That SEEMS to have worked. I’ll know more when I get farther along.

      • @davidschuler:disqus glad to hear easy_install worked for you. I was able to us pip to just install the Google API client on another machine so not sure what the specific issue was for you. Once you got setup were you able to run a query?
        1C:Python27Scriptseasy_install –upgrade google-api-python-client

  • Crack’d Actor

    Thanks a lot for a really great tutorial Ryan! Best I’ve seen on the subject.

    I’m using a Mac, but your instructions were so clear that I was able to adapt them very easily. Great job!

  • Hi Deepak,

    Glad you found the Python tutorial useful. To add user level data to your Google Analytics you’ll want to implement Google Analytics User ID feature and capture this User ID in a custom dimension. See more details here:
    https://support.google.com/analytics/answer/3123662?hl=en

    If you don’t have a user id for your visitors you can capture Google Analytics’ client id in a custom dimension and use that. See more details here:
    https://developers.google.com/analytics/devguides/collection/analyticsjs/cookies-user-id#getting_the_client_id_from_the_cookie

    You can then run a report with the user or visitor id custom dimension and the events.

    -Ryan

  • laura

    hey ryan! loved the tutorial, finally got it to authenticate.
    having an issue though i tried setting my first_profile_id to the profile i want, but it’s giving me an error message “There was an error in constructing your query : Parameter “ids” value “ga:profile_id” does not match the pattern “ga:[0-9]+”” any tips?

    • Hi Laura,

      Glad you found the tutorial useful.
      A couple troubleshooting idea:
      1) Make sure the profile id is correct
      2) Try starting with the original version of the code in the post.
      3) If that doesn’t work send me a screenshot with the error and a copy of the code you are using and I’ll take a look.

      -Ryan

  • Gabriel Kirst da Rocha

    Hey Ryan!

    I have an issue getting customized dimensions, like dimension1, dimension2 and so on. If I try getting these dimensions, I got no results. Any idea of what would cause this?

    Another question… Does this api gets more than the 10K rows limit?

    Thanks in advance!

    Gabriel

    • Hi Gabriel,

      Are you sure these dimensions have data for the date range of your query? Can you share a screen shot of the query you are trying to run either here or via email: ryan@ryanpraski.com

      The Google Analytics Reporting API has a 10,000 row limit. That said there are a number of ways to deal with this limit. I’ve written about how to get around the limit here: http://www.ryanpraski.com/python-google-analytics-api-unsampled-data-multiple-profiles/

      -Ryan

      • Gabriel Kirst da Rocha

        Hi Ryan!

        Thanks for the quick reply!
        About the customized dimensions, I’ve found out that the user that I was using doesn’t have access to the full content of the data. Probably this is the problem.

        About the 10K rows limit, I’ll try out this solution.

        Thanks a lot!

        Regards,
        Gabriel

  • Rajat

    Ryan Praskievicz

    Thank you for detailed steps… really appreciate your efforts for making this
    keep it and
    i would be very happy if you can share your other posts links also so i can read them too..

    Thanks
    Rajat

  • Saif s n

    ModuleNotFoundError: No module named ‘googleapiclient’ Is the error I got. Please help

    • Hi Saif,

      Try repeating step #3 to install the google analytics api client using pip. Also, make sure that you have downloaded the Google API client samples in step #5. If this doesn’t solve your problem let me know.

      -Ryan

      • Saif s n

        line 50, in from googleapiclient.errors import HttpError. ModuleNotFoundError: No module named ‘googleapiclient’. Is the error I am still getting

        • Sure there is info on how to write data to a MySQL database with Python here: https://www.fullstackpython.com/databases.html

          • Saif s n

            Thank you so much Ryan. I did not find filename and filepath anywhere in the program but I fixed that in my program. Thanks for the help and article.

          • Saif s n

            Hey Ryan is there any way I can track the clicks or from where can I collect information about all the clicks made in the website? I have used Python to push the data to MySQL tracked by GA.

  • Janie Ji
  • Hi Janie,

    The analytics.dat file will be created after you successfully authenticate. In your screen shot I don’t see “Autherication Sucessful” logged to the console. Go back through step 7 above on running your first Google Analytics API query and pay close attention to the authentication process. Let me know if you still have questions after trying again.

    Best,
    Ryan

    • Janie Ji

      Hi Ryan
      Thanks for your reply. Bad. This issue is still here. _(:зゝ∠)_

  • Vijay Pal

    Can someone please help me to write a filter condition for metric where it is not equal to zero, I am trying this:
    goal5Completions!=0

    but help section of query explorer is confusing with the given syntax, so i am not sure whether it is correct or not ?