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.

1. Install

The latest stable version of googleAnalyticsR is available on CRAN. CRAN

install.packages("googleAnalyticsR", dependencies = TRUE)

Development version off GitHub

You may prefer to use the latest development version on GitHub which you can install via the below.

Github check status: Travis-CI Build Status

remotes::install_github("MarkEdmondson1234/googleAnalyticsR")

Check out the NEWS to see whats currently available in each version.

Dependencies

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)

Note that on linux systems, due to its reliance on httr and in turn curl, it may require installation of these dependencies via apt-get or similar: libssl-dev and libcurl4-openssl-dev.

2. Make first API call

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")

You can find more code examples to query the API in v4 API and v3 API sections of the site.

3. Choose authentication method

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.

Authentication method #1: The default googleAnalyticsR project

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 ga_auth()

Authentication method #2: Your own Google Project

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.

Donal Phipps has very kindly created a screencast on how to set this up that you can find embedded below and via this link.

Once you obtain the credentials for your project set these options before any call to ga_auth() or other data fetching calls.

options(googleAuthR.client_id = "uxxxxxxx2fd4kesu6.apps.googleusercontent.com")
options(googleAuthR.client_secret = "3JhLa_GxxxxxCQYLe31c64")
options(googleAuthR.scopes.selected = "https://www.googleapis.com/auth/analytics")

In the next example, the scopes are also set so a user can authenticate with searchConsoleR at the same time, which is possible as they both use googleAuthR as a backend.

options(googleAuthR.client_id = "tuxxxxxxx2fd4kesu6.apps.googleusercontent.com")
options(googleAuthR.client_secret = "3JhLa_GxxxxxCQYLe31c64")
options(googleAuthR.scopes.selected = c("https://www.googleapis.com/auth/analytics",
                                        "https://www.googleapis.com/auth/webmasters"))

If you want to use with Shiny, then set the webapp clientId/secrets.

options(googleAnalyticsR.webapp.client_id = "xxxxx9pcab1u005cv.apps.googleusercontent.com")
options(googleAnalyticsR.webapp.client_secret = "zcofxxxxxxElemXN5sf")

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).

Authentication method #3: Google Cloud service account

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 googleAuthR website.

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.

  1. Create your own Google Cloud Project or use an existing one.
  2. Set your own client.id/secret via googleAuthR::gar_set_client()
  3. Service accounts for your project can be created at this link: https://console.cloud.google.com/iam-admin/serviceaccounts/create
  4. The service account does not need any GCP account permissions (we do that in next step when we add to GA)
  5. After you can see your service account in the list, create a JSON key for that service account and download it somewhere safe
  6. Copy the service email e.g. ga-access@your-project.iam.gserviceaccount.com
  7. Login to Google Analytics and add the email to your account at the level of permissions you want. If you want to upload data or update filters etc. then it needs at least edit permissions, if it just needs to read data then Viewer access is fine.
  8. Make sure the GCP project the service key is for has both the Analytics API and the Analytics Reporting API access enabled. You can reach this via the Google API & Services dashboard URL: https://console.developers.google.com/apis/dashboard

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

4 (optional): Review useful auth options

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.

Auto-authentication

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 ga_auth().

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.

You can set environment variables using a .Renviron file or via the function Sys.setenv() - see ?Startup for details. The first method is described below:

  1. Choose your authentication cache file - either one you have generated via ga_auth() or your own Google Project’s service account JSON ending with file extension .json
  2. Create a file called .Renviron and 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 Home breadcrumb link in your File Explorer panel or with the path.expand("~") command.
  3. Place the absolute location of the file from step 1 into the .Renviron file, e.g. GA_AUTH_FILE = "/Users/mark/dev/auth/ga.oauth".
  4. Save the file and restart your R session.

If all goes well you should see something similar to this when you load googleAnalyticsR:

library(googleAnalyticsR)
#>Successfully authenticated via /Users/mark/dev/auth/ga.oauth

## can do authenticated calls straight away
al <- ga_account_list()

Multiple API authentification

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

Multiple GA accounts

If you ever need to authenticate with a new user, use ga_auth(new_user=TRUE)

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 googleAuthR::gar_auth()

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"))

Authentication with shiny and Rmarkdown

More details about these special cases of authentication are available on the corresponding sections of this site for Shiny and Rmarkdown

5 (optional): Explore the GA metrics and dimensions

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.)

Where to go from here ?

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.