[ Submitting your first Google Analytics Reporting API Request ]
Your browser will automatically launch a window that look something like this.
Create a new notebook in the page that shows up in your browser, then we are ready to begin coding some Python!
Get familiar with Jupyter Notebook and Import Necessary Packages
Let’s begin by familiarizing ourselves with the interface of Jupyter Notebook.
Most of the commands are quite simple and easy to understand (copy, paste, cut, etc.), but I have highlighted a few functions that are very frequently used and essential for our exercises to come.
Now, let’s begin coding in one of the code block below by adding our import statement for all of the packages that we need to make our request happen.
Importing packages in Python is surprisingly simple — just type “import
” as a line of code.
Python packages are usually structured in a hierarchical way, meaning that a package, such as the google-auth package, may have multiple smaller packages, with multiple even smaller packages in those small packages, and so on.
To only import the packages you need, you may use the syntax “from import . This is usually used to:
Save loading time for large packages, and Make the syntax easier to pull.
You may also “import as ” to make the packages you have imported more accessible, and avoid naming conflicts with variables in the code you write.
I have intentionally displayed multiple different ways of importing in the code below to illustrate, and you can simply copy paste the import statement into your first code block.
After pasting the code into the code block, click the “Run” button illustrated above to run the code block. After you click it, nothing will happen (this is good news), as we did not request any outputs from the code. However, you will see your “Ln” number next to code block increase, illustrating the number of code block executions in this run.
Set up the project in Google Developer Console and get client token and secret
Welcome to the development world! Now that you are a developer, time to tell Google so it can grant you access to API accesses that are exclusive to developers!
To register your Google Analytics project with Google, simply follow the setup tool in the link below to setup your project on Google Developer Console, it is easy as 1, 2, 3, 4, 5.
Step 1: If you have an existing project, you may have a different screen, but choose “create a new project” regardless unless you have a good reason to integrate with a current application you own.
Step 2: Just click the button, nothing much
Step 3: Fill this out as below (since ipython notebook is technically a Cli tool).
Update: If you are running into an error during the OAuth Playground stage, please try to create a “web application (instead of Other UI)” client token instead, and in the “Authorized Redirect URIs” field, enter “https://developers.google.com/oauthplayground” as one of the options. Use that token for the following steps.
Step 4: There is another screen that ask you to name the app, nothing there so we are going to skip. Then you will see this screen, and you can name it to your liking.
Step 5: Click download credential and open the downloaded file with a text editing software, you will find your client id and client secret in there — keep this file open as we will need both in our code.
Following all of the steps above, you will have access to your client id and client secret, along with Google Analytics reporting API permission to your project.
Keep those two pieces of information handy, as we will need it to construct authorization credential — now let’s go ahead and get credential for our Google Analytics account.
Getting authentication tokens and authenticate
Alright, now let’s talk about oauth2, the authentication method used by Google to make sure you are an authorized user for your Google Analytics account.
OAuth2 is the most popular protocol right now for authorization for all sorts of applications/apis, including but not limited to Facebook, Google, Youtube, and so on.
Let’s explain why we need OAuth2 in plain language.
When running our script, we would need a way to tell the Google API client that we are indeed an authorized user to access a selected Google Analytics account.
The most direct way of authorizing is via username and password, which can be accomplished by sending our username and password for Google to the google api service.
However, this practice is a huge security risk for multiple reasons:
First, if we are using the Google password directly, it would mean that we have to store Google credential somewhere that is NOT Google’s database.
If I am making an application that services 100 users, I would store the username and password of those 100 users in my database, and there is no way to tell whether I stored a user’s information securely, or if I am selling the user’s information to a third party.
This is a huge security risk for user information, as a simple breach on any of the application that uses Google services will result in a massive loss in user credentials, essentially paralyzing all Google-related services.
Secondly, sending usernames and passwords to the Google API service would mean that real passwords and usernames will be transferred over the internet, which can be intercepted by the hacker and decrypted to steal your personal information.
OAuth solves those problems above by offering a slightly more convoluted, but secure way for the user to authorize in a third-party app or script for Google services.
Essentially, instead of sending usernames or passwords to Google directly, the app/script requests a link from Google, where users can sign into their Google Account via this link (it is native to Google) — the third party app/script will not touch the username or password of the user.
Then, if authentication is completed, Google will send the app/script an access token and a refresh token, which will serve as the access code for authorized Google services.
The access token and refresh token can only be used by that specific app, for access restricted information only agreed upon by the users when they sign in, and may expire or be revoked at the user’s leisure.
The differences between the access code and refresh code is that the access code is designed to be short-lived, only usually last few hours.
However, if the app wants continued access the user’s information, it can refresh the access token by passing the refresh token to Google again, getting a new access token to use — this protects users from unauthorized, permanent access from apps they do not wish to grant permission to it anymore.
Here’s a quick flowchart explaining how that works:
So first we get our access token from Google via the Google OAuth 2 Playground link below:
We need to make sure the access token is authorized for our app specifically. You can do that by typing in your own application information (the client id and client secret I told you to keep) in the “Setting” section:
Each access token is only granted for a restricted purpose called “Scope” by Google, and we only need view permission for Google Analytics here, so please select that specific scope and click continue:
Then, you will be direct to your usual Google login screen, enter the account you use for your Google Analytics account, and then follow the instruction below to get your refresh and access token.
As explained in the graphic, keep your access token and refresh token on a separate notepad or word document, as we will use it in the next step.
Now let’s go back to our Jupyter Notebook and start coding the authentication engine
The title of this section might be misleading — we are not going to code our own authentication engine, we are merely going to use the existing ones we have imported from google-auth library previously.
Recall that in the import statement, we imported the “client” object in the google-auth library, now we just need to create a client per instruction of the library and type in the required information.
