1. Install the necessary packages into R via the GitHub repository

# Install the latest version of remotes via CRAN
install.packages("remotes")
# Install ganalytics via the GitHub repository.
remotes::install_github("jdeboer/ganalytics")
# End

2. Prepare your Google API application (you only need to do this once)

• Browse to [Google API Console] (https://code.google.com/apis/console/)
• Check you are signed into Google with the account you wish to use.
• Choose Create Project from the Google API Console and give your project a name (or choose an existing project if you have one already).
• From the APIs page, enable the Analytics API. You may also want to enable the Tag Manager API if you wish to try that.
• You will need to agree and accept the Google APIs and Analytics API Terms of Service to proceed.
• Go to the Credentials page, click Add credentials, choose OAuth 2.0 client ID, then select “Other”.
• Note your Client ID and Client Secret and download the JSON file to your R working directory.

Note: For further information about Google APIs, please refer to the References section at the end of this document.

3. Set your system environment variables (this is optional but recommended)

• Add the following two user variables:

  	Variable name	Variable value
  1	GOOGLE_APIS_CONSUMER_ID	<Your client ID>
  2	GOOGLE_APIS_CONSUMER_SECRET	<Your client secret>

  • To do this in Windows:
    • Search for and select “Edit Environment Variables For Your Account” from the Start menu.
    • Within the Environment Variables window, add the above User Variables by selecting New and entering the Variable Name and Variable Value, then click OK. Do this for both variables listed in the table above.
    • Click OK.
    • Restart your computer for the new environment variables to take effect.
  • There is also a free open source utility to set environment variables on Mac OS called EnvPane
  • Another method that works across platforms is to create an .Renviron file within your active R working directory that is structured like this:

GOOGLE_APIS_CONSUMER_ID = <Your client ID>
GOOGLE_APIS_CONSUMER_SECRET = <Your client secret>

Alternatively you can temporarily set your environment variables straight from R using this command:

Sys.setenv(
  GOOGLE_APIS_CONSUMER_ID = "<Your client ID>",
  GOOGLE_APIS_CONSUMER_SECRET = "<Your client secret>"
)

Note: For other operating systems please refer to the Reference section at the end of this document.

4. Authenticate and attempt your first query with ganalytics

• ganalytics needs to know the ID of the Google Analytics view that you wish to query. You can obtain this in a number of ways:
  • Using the Google Analytics Query Explorer tool
  • From the Admin page in Google Analytics under View Settings, or
  • The browser’s address bar while viewing a report in Google Analytics - look for the digits between the letter ‘p’ and trailing ‘/’, e.g. .../a11111111w22222222p33333333/ shows a view ID of 33333333.
• Alternatively, ganalytics can look up the view ID for you:
  • If you have access to only one Google Analytics account, with one property, then ganalytics will automatically select the default view for you from that property.
  • Otherwise it will select the default view of the first property from the first account that it finds in the list of accounts that you have access to.

• Return to R and execute the following to load the ganalytics package:

  library(ganalytics)

• If you have successfully set your system environment variables in step 3 above, then you can execute the following, optionally providing the email address you use to sign-in to Google Analytics:

  my_creds <- GoogleApiCreds("you@domain.com")

• Otherwise do one of the following:

  • If you downloaded the JSON file containing your Google API app credentials, then provide the file path:

    my_creds <- GoogleApiCreds("you@domain.com", "client_secret.json")

  • Or, instead of a file you can supply the client_id and client_secret directly:

    my_creds <- GoogleApiCreds(
      "you@domain.com",
      list(client_id = "<client id>", client_secret = "<client secret>")
    )

• Now formulate and run your Google Analytics query, remembering to substitute view_id with the view ID you wish to use:

  myQuery <- GaQuery( view_id, creds = my_creds ) # view_id is optional
  GetGaData(myQuery)

• You should then be directed to accounts.google.com within your default web browser asking you to sign-in to your Google account if you are not already. Once signed-in you will be asked to grant read-only access to your Google Analytics account for the Google API project you created in step 1.

• Make sure you are signed into the Google account you wish to use, then grant access by selecting “Allow access”. You can then close the page and return back to R.

If you have successfully executed all of the above R commands you should see the output of the default ganalytics query; sessions by day for the past 7 days. For example:

        date sessions
1 2015-03-27     2988
2 2015-03-28     1594
3 2015-03-29     1912
4 2015-03-30     3061
5 2015-03-31     2609
6 2015-04-01     2762
7 2015-04-02     2179
8 2015-04-03     1552

Note: A small file will be saved to your home directory (‘My Documents’ in Windows) to cache your new reusable authentication token.

Asumptions

The following examples assume you have successfully completed the above steps and have named your Google Analytics query object: myQuery.

Example 1 - Setting the date range

# Set the date range from 1 January 2013 to 31 May 2013: (Dates are specified in the format "YYYY-MM-DD".)
DateRange(myQuery) <- c("2013-01-01", "2013-05-31")

myData <- GetGaData(myQuery)
summary(myData)

# Adjust the start date to 1 March 2013:
StartDate(myQuery) <- "2013-03-01"
# Adjust the end date to 31 March 2013:
EndDate(myQuery) <- "2013-03-31"

myData <- GetGaData(myQuery)
summary(myData)
# End

Example 2 - Choosing what metrics to report

# Report number of page views instead
Metrics(myQuery) <- "pageviews"

myData <- GetGaData(myQuery)
summary(myData)

# Report both pageviews and sessions
Metrics(myQuery) <- c("pageviews", "sessions")
# These variations are also acceptable
Metrics(myQuery) <- c("ga:pageviews", "ga.sessions")

myData <- GetGaData(myQuery)
summary(myData)
# End

Example 3 - Selecting what dimensions to split your metrics by

# Similar to metrics, but for dimensions
Dimensions(myQuery) <- c("year", "week", "dayOfWeekName", "hour")

# Lets set a wider date range
DateRange(myQuery) <- c("2012-10-01", "2013-03-31")

myData <- GetGaData(myQuery)
head(myData)
tail(myData)
# End

Example 4 - Sort by

# Sort by descending number of pageviews
SortBy(myQuery) <- "-pageviews"

myData <- GetGaData(myQuery)
head(myData)
tail(myData)
# End

Example 5 - Row filters

# Filter for Sunday sessions only
sundayExpr <- Expr(~dayOfWeekName == "Sunday")
TableFilter(myQuery) <- sundayExpr

myData <- GetGaData(myQuery)
head(myData)

# Remove the filter
TableFilter(myQuery) <- NULL

myData <- GetGaData(myQuery)
head(myData)
# End

Example 6 - Combining filters with AND

# Expression to define Sunday sessions
sundayExpr <- Expr(~dayOfWeekName == "Sunday")
# Expression to define organic search sessions
organicExpr <- Expr(~medium == "organic")
# Expression to define organic search sessions made on a Sunday
sundayOrganic <- sundayExpr & organicExpr
TableFilter(myQuery) <- sundayOrganic

myData <- GetGaData(myQuery)
head(myData)

# Let's concatenate medium to the dimensions for our query
Dimensions(myQuery) <- c(Dimensions(myQuery), "medium")

myData <- GetGaData(myQuery)
head(myData)
# End

Example 7 - Combining filters with OR

# In a similar way to AND
loyalExpr <- !Expr(~sessionCount %matches% "^[0-3]$") # Made more than 3 sessions
recentExpr <- Expr(~daysSinceLastSession %matches% "^[0-6]$") # Visited sometime within the past 7 days.
loyalOrRecent <- loyalExpr | recentExpr
TableFilter(myQuery) <- loyalOrRecent

myData <- GetGaData(myQuery)
summary(myData)
# End

Example 8 - Filters that combine ORs with ANDs

loyalExpr <- !Expr(~sessionCount %matches% "^[0-3]$") # Made more than 3 sessions
recentExpr <- Expr(~daysSinceLastSession %matches% "^[0-6]$") # Visited sometime within the past 7 days.
loyalOrRecent <- loyalExpr | recentExpr
sundayExpr <- Expr(~dayOfWeekName == "Sunday")
loyalOrRecent_Sunday <- loyalOrRecent & sundayExpr
TableFilter(myQuery) <- loyalOrRecent_Sunday

myData <- GetGaData(myQuery)
summary(myData)

# Perform the same query but change which dimensions to view
Dimensions(myQuery) <- c("sessionCount", "daysSinceLastSession", "dayOfWeek")

myData <- GetGaData(myQuery)
summary(myData)
# End

Example 9 - Sorting ‘numeric’ dimensions (continuing from example 8)

# Continuing from example 8...

# Change filter to loyal session AND recent sessions AND visited on Sunday
loyalAndRecent_Sunday <- loyalExpr & recentExpr & sundayExpr
TableFilter(myQuery) <- loyalAndRecent_Sunday

# Sort by decending visit count and ascending days since last visit.
SortBy(myQuery) <- c("-sessionCount", "+daysSinceLastSession")
myData <- GetGaData(myQuery)
head(myData)

# Notice that the Google Analytics Core Reporting API doesn't recognise 'numerical' dimensions as
# ordered factors when sorting. We can use R to sort instead, such as using dplyr.
library(dplyr)
myData <- myData %>% arrange(desc(sessionCount), daysSinceLastSession)
head(myData)
tail(myData)
# End

Example 10 - Session segmentation

# Visit segmentation is expressed similarly to row filters and supports AND and OR combinations.
# Define a segment for sessions where a "thank-you", "thankyou" or "success" page was viewed.
thankyouExpr <- Expr(~pagePath %matches% "thank\\-?you|success")
Segments(myQuery) <- thankyouExpr

# Reset the filter
TableFilter(myQuery) <- NULL

# Split by traffic source and medium
Dimensions(myQuery) <- c("source", "medium")

# Sort by decending number of sessions
SortBy(myQuery) <- "-sessions"

myData <- GetGaData(myQuery)
head(myData)
# End

Example 11 - Using automatic pagination to get more than 10,000 rows of data per query

# Sessions by date and hour for the years 2016 and 2017:
# First let's clear any filters or segments defined previously
TableFilter(myQuery) <- NULL
Segments(myQuery) <- NULL
# Define our date range
DateRange(myQuery) <- c("2016-01-01", "2017-12-31")
# Define our metrics and dimensions
Metrics(myQuery) <- "sessions"
Dimensions(myQuery) <- c("date", "dayOfWeekName", "hour")
# Let's allow a maximum of 20000 rows (default is 10000)
MaxResults(myQuery) <- 20000

myData <- GetGaData(myQuery)
nrow(myData)

## Let's use dplyr to analyse the data
library(dplyr)

# Sessions by day of week
sessions_by_dayOfWeek <- myData %>%
  count(dayOfWeekName, wt = sessions) %>% 
  mutate(dayOfWeekName = factor(dayOfWeekName, levels = c(
    "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"
  ), labels = c("Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"), ordered = TRUE)) %>% 
  arrange(dayOfWeekName)
with(
  sessions_by_dayOfWeek,
  barplot(n, names.arg = dayOfWeekName, xlab = "day of week", ylab = "sessions")
)

# Sessions by hour of day
sessions_by_hour <- myData %>%
  count(hour, wt = sessions)
with(
  sessions_by_hour,
  barplot(n, names.arg = hour, xlab = "hour", ylab = "sessions")
)
# End

Example 12 - Using ggplot2

To run this example first install ggplot2 if you haven’t already.

install.packages("ggplot2")

Once installed, then run the following example.

library(ggplot2)
library(dplyr)

# Sessions by date and hour for the years 2016 and 2017:
# First let's clear any filters or segments defined previously
TableFilter(myQuery) <- NULL
Segments(myQuery) <- NULL
# Define our date range
DateRange(myQuery) <- c("2016-01-01", "2017-12-31")
# Define our metrics and dimensions
Metrics(myQuery) <- "sessions"
Dimensions(myQuery) <- c("date", "dayOfWeek", "hour", "deviceCategory")
# Let's allow a maximum of 40000 rows (default is 10000)
MaxResults(myQuery) <- 40000

myData <- GetGaData(myQuery)

# Sessions by hour of day and day of week
avg_sessions_by_hour_wday_device <- myData %>% 
  group_by(hour, dayOfWeek, deviceCategory) %>% 
  summarise(sessions = mean(sessions)) %>% 
  ungroup()

# Relabel the days of week
levels(avg_sessions_by_hour_wday_device$dayOfWeek) <- c(
  "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"
)

# Plot the summary data
qplot(
  x = hour,
  y = sessions,
  data = avg_sessions_by_hour_wday_device,
  facets = ~dayOfWeek,
  fill = deviceCategory,
  geom = "col"
)

# End