This guide will walk you through the steps required to properly set up googleAnalyticsR in terms of installation and authentication.
It assumes you have R installed on your machine and access rights to one or more Google Analytics accounts. In this case it will only take a few lines of R code to make a first test call to the GA API following the examples below.
The rest of this guide will give you an overview of the available set up options and cover some good practices to follow under different scenarios of use.
The latest stable version of
googleAnalyticsR is available on CRAN.
install.packages("googleAnalyticsR", dependencies = TRUE)
You may prefer to use the latest development version on GitHub which you can install via the below.
Check out the NEWS to see whats currently available in each version.
googleAnalyticsR requires the packages described in the
Imports field of the
DESCRIPTION file to be installed first, which it will do via
install.packages("googleAnalyticsR", dependencies = TRUE)
Once you have installed the package you can make a first call to the GA API to test the connection.
## setup library(googleAnalyticsR) ## This should send you to your browser to authenticate your email. Authenticate with an email that has access to the Google Analytics View you want to use. ga_auth() ## get your accounts account_list <- ga_account_list() ## account_list will have a column called "viewId" account_list$viewId ## View account_list and pick the viewId you want to extract data from. ga_id <- 123456 ## simple query to test connection google_analytics(ga_id, date_range = c("2017-01-01", "2017-03-01"), metrics = "sessions", dimensions = "date")
To access the GA API authentication is required.
The example in the previous section used the simplest among the three available ways to authenticate to the API. If you are planning to make systematic use of the API however, it’s worth to know all the available options in order to choose the most suitable.
Note that no matter which method you use, the authentication is actually done via the
googleAuthR package. In its documentation pages you can read more about advanced use cases.
The fast authentication way of the previous section worked via the default Google Project for googleAnalyticsR which is shared with all googleAnalyticsR users. Even though it is a shared project other package users are not able to see and access your GA data.
You will not need any credentials and you can directly authenticate using the
ga_auth() function and your browser. You will not have to go through the browser verification every time though. When you authenticate a
ga.oauth file will be created in your working directory. If that file is present, then you will not need to go via Google login when you next use
With the amount of API calls possible with this library via batching and walking, its more likely the default shared Google API project will hit the 50,000 calls per day limit.
To mitigate that, use your own Google Developer Console Project key, so it is not shared across all users of this library.
Once you obtain the credentials for your project set these options before any call to
ga_auth() or other data fetching calls.
If you want to use with Shiny, then set the webapp clientId/secrets.
Note: With either shared or personal project using the
ga_auth() function, you can specify the name and location of your cache file if you pass that to the
ga_auth() function e.g.
ga_auth("auth/my.oauth"). This will create your authentication file at the location you specify (relative to your working directory). This can be useful when authenticating within an Rmarkdown document in which case it is recommended to specify your cache file (an Rmarkdown document can change the working directory during knitting).
You can alternatively authenticate by downloading a JSON file attached to a Google Cloud service account. More details on how to do that are on the
A service authentication file then needs to be created that has edit access to the GA account. It is recommended to make a dedicated service account if you don’t need it for anything else.
You should now be able to use the JSON auth file to authenticate with Google Analytics API via:
library(googleAnalyticsR) googleAuthR::gar_auth_service("your_auth_file.json") # test authentication al <- ga_account_list()
Note: A service account is a special type of account that belongs to an application rather than an individual user. If you should use this option, chances are you are already familiar with how they work. If however you wish to find out more about when and how to use service accounts, follow the link to the Google Cloud documentation page on Understanding Service Accounts
This section covers some other aspects of authentication under various scenarios of use. This information is useful especially if you work systematically with Google Analytics and possibly other Google products too.
If you often use the library to access the same accounts from one machine, then it is helpful to setup auto-authentication. This is also the most reliable way for scheduled scripts. It means you do not need to use
A short video on how to do this is available here: googleAnalyticsR - how to do auto-authentication
You choose to auto-authenticate by moving your authentication cache file to a global location on your computer, that all future R sessions will use, then telling
googleAnalyticsR where that file is when it is loaded into your R session.
This is done by creating an environment variable called
GA_AUTH_FILE that points at your valid cache file.
ga_auth()or your own Google Project’s service account JSON ending with file extension
.Renvironand place it in your user’s home directory (
~on OSX/linux or
C:\\on Windows). If using RStudio, you can find your the correct location directory by clicking on the
Homebreadcrumb link in your File Explorer panel or with the
GA_AUTH_FILE = "/Users/mark/dev/auth/ga.oauth".
If all goes well you should see something similar to this when you load
If you are using more than one API for authentication (such as Search Console), then authenticate using
googleAuthR::gar_auth() instead, to ensure you authenticate with the correct scopes. See the multiple authentication section on the
googleAuthR website for details.
If you have set up a personal project then you can use the
options() function as shown in the previous section
If you ever need to authenticate with a new user, use
If you systematically need to fetch from several different Google analytics accounts, the easiest way to handle authentication is to have the websites all available under one email. If that is not possible, then you can run through the authentication steps twice, and name your auth tokens different names. You will need to unset the GA_AUTH_FILE in your .Renviron if you have one by either commenting it out or removing the line. You can then authenticate separately using
library(googleAnalyticsR) googleAuthR::gar_auth("~/auth/client_one.httr-oauth") client_one <- google_analytics(ga_id_one, date_range = my_date_range, metrics = "sessions", dimensions = c("date", "medium")) googleAuthR::gar_auth("~/auth/client_two.httr-oauth") client_two <- google_analytics(ga_id_two, date_range = my_date_range, metrics = "sessions", dimensions = c("date", "medium"))
To see what dimensions and metrics are available via the API as well as their precise definition, you can use this command:
## get a list of what metrics and dimensions you can use meta <- google_analytics_meta()
If offline, this data is also available by typing
meta, although it won’t be quite as up to date.
The meta data does not include multi-channel as they are not available, for those see the online version.
When using the library, you can call metrics and dimensions with or without the
ga: prefix (
mcf: for multi-channel metrics/dimensions.)
Once the set up is complete you are ready to start using the package to access your GA data. To give you some ideas the v4 API page of this site provides several examples of key functionalities provided by the package.