The Data API and Google Analytics Admin API are used with the Google Analytics 4 properties, the newest version of Google Analytics and evolution from Universal Analytics.
See a demo video on GA4 and some of the new ga_data() features in this GA4 API FTW YouTube video.
You can see the GA4 accounts you have access to under your authentication via ga_account_list("ga4")
library(googleAnalyticsR)
ga_auth(email="my@email.com")
ga_account_list("ga4")Universal metadata for what you can query via the Data API can be found by specifying that API in the ga_meta() function:
metadata <- ga_meta(version = "data")You may have custom dimensions and metrics set up for your web property - to get a list of those specify the web property in the meta data call:
# Google Analytics 4 metadata for a particular Web Property
ga_meta("data", propertyId = 206670707)Custom events and user scoped custom dimensions have names starting with customEvent: and customUser: respectively. Include them in your reports with the prefix.
Make sure to authenticate first using ga_auth() or otherwise.
The primary data fetching function is ga_data()
You need your propertyId to query data, and then at least a metric and date range:
# replace with your propertyId
my_property_id <- 206670707
basic <- ga_data(
my_property_id,
metrics = c("activeUsers","sessions"),
date_range = c("2020-03-31", "2020-04-27")
)
basic
# A tibble: 1 x 2
# activeUsers sessions
# <dbl> <dbl>
#1 1716 2783Dimensions can be added to split out your results:
# split out metrics by the dimensions specified
dimensions <- ga_data(
my_property_id,
metrics = c("activeUsers","sessions"),
dimensions = c("date","city","dayOfWeek"),
date_range = c("2020-03-31", "2020-04-27")
)
dimensions
# A tibble: 100 x 5
# date city dayOfWeek activeUsers sessions
# <date> <chr> <chr> <dbl> <dbl>
# 1 2020-04-08 (not set) 4 18 21
# 2 2020-04-08 Rome 4 12 14
# 3 2020-04-15 (not set) 4 9 11
# 4 2020-04-27 (not set) 2 9 11
# 5 2020-04-09 (not set) 5 8 10
# 6 2020-04-14 (not set) 3 8 8
# 7 2020-04-22 (not set) 4 8 9
# 8 2020-03-31 (not set) 3 7 10
# 9 2020-04-08 Bologna 4 7 7
#10 2020-04-07 (not set) 3 6 7
# … with 90 more rowsSome of the most useful dimensions and metrics to fetch are eventName and eventCount, which is effectively the most granular report given the new GA4 data model. Combined with filters (see below) this can get you to useful conversion events.
# if you set metrics=NULL you will get only the distinct events
ga_data(
my_property_id,
metrics = NULL,
dimensions = "eventName",
date_range = c("2020-03-31", "2020-04-27")
)
## A tibble: 9 x 1
# eventName
# <chr>
#1 click
#2 first_visit
#3 page_view
#4 scroll
#5 session_start
#6 user_engagement
#7 video_complete
#8 video_progress
#9 video_start
# eventsCounts per eventName
events <- ga_data(
my_property_id,
metrics = c("eventCount"),
dimensions = c("date","eventName"),
date_range = c("2020-03-31", "2020-04-27")
)
events
## A tibble: 100 x 3
# date eventName eventCount
# <date> <chr> <dbl>
# 1 2020-04-08 page_view 239
# 2 2020-04-08 session_start 207
# 3 2020-04-09 page_view 203
# ...
# filter to one event
ga_data(
my_property_id,
metrics = "eventCount",
dimensions = "eventName",
date_range = c("2020-03-31", "2020-04-27"),
dim_filters = ga_data_filter(eventName=="video_start")
)
## A tibble: 1 x 2
# eventName eventCount
# <chr> <dbl>
#1 video_start 4By default the API returns 100 results. Add the limit parameter to change the number of results returned. To get all results, use -1
only_5 <- ga_data(
my_property_id,
metrics = c("activeUsers","sessions"),
dimensions = c("date","city","dayOfWeek"),
date_range = c("2020-03-31", "2020-04-27"),
limit = 5
)
only_5
# A tibble: 5 x 5
# date city dayOfWeek activeUsers sessions
# <date> <chr> <chr> <dbl> <dbl>
#1 2020-04-08 (not set) 4 18 21
#2 2020-04-08 Rome 4 12 14
#3 2020-04-15 (not set) 4 9 11
#4 2020-04-27 (not set) 2 9 11
#5 2020-04-09 (not set) 5 8 10
all_results <- ga_data(
my_property_id,
metrics = c("activeUsers","sessions"),
dimensions = c("date","city","dayOfWeek"),
date_range = c("2020-03-31", "2020-04-27"),
limit = -1
)
all_results
# A tibble: 1,763 x 5
# date city dayOfWeek activeUsers sessions
# <date> <chr> <chr> <dbl> <dbl>
# 1 2020-04-08 (not set) 4 18 21
# 2 2020-04-08 Rome 4 12 14
# 3 2020-04-15 (not set) 4 9 11
# 4 2020-04-27 (not set) 2 9 11
# 5 2020-04-09 (not set) 5 8 10
# 6 2020-04-14 (not set) 3 8 8
# 7 2020-04-22 (not set) 4 8 9
# 8 2020-03-31 (not set) 3 7 10
# 9 2020-04-08 Bologna 4 7 7
#10 2020-04-07 (not set) 3 6 7
# … with 1,753 more rowsYou can also select how big the API will page. The default is the maximum 100000 rows - you may want to change this if you experience problems downloading a lot of data with several columns. Set via the page_size parameter:
# get all results, but page every 500 rows
all_results_paged <- ga_data(
my_property_id,
metrics = c("activeUsers","sessions"),
dimensions = c("date","city","dayOfWeek"),
date_range = c("2020-03-31", "2020-04-27"),
limit = -1,
page_size = 500L
)
#ℹ 2021-02-20 12:26:11 > Downloaded [ 500 ] of total [ 1763 ] rows
#ℹ 2021-02-20 12:26:11 > Paging API from offset [ 500 ]
#ℹ 2021-02-20 12:26:12 > Downloaded [ 500 ] of total [ 1763 ] rows
#ℹ 2021-02-20 12:26:12 > Paging API from offset [ 1000 ]
#ℹ 2021-02-20 12:26:13 > Downloaded [ 500 ] of total [ 1763 ] rows
#ℹ 2021-02-20 12:26:13 > Paging API from offset [ 1500 ]
#ℹ 2021-02-20 12:26:14 > Downloaded [ 263 ] of total [ 1763 ] rows
# get 510 rows, page every 500 rows (so 2 total)
top510_paged500 <- ga_data(
my_property_id,
metrics = c("activeUsers","sessions"),
dimensions = c("date","city","dayOfWeek"),
date_range = c("2020-03-31", "2020-04-27"),
limit = 510,
page_size = 500L
)
#ℹ 2021-02-20 12:26:45 > Downloaded [ 500 ] of total [ 1763 ] rows
#ℹ 2021-02-20 12:26:45 > Paging API from offset [ 500 ]
#ℹ 2021-02-20 12:26:46 > Downloaded [ 10 ] of total [ 1763 ] rowsWhen fetching custom dimensions and metrics, specify the prefix as you read it in the meta data table. See this Google article on custom definitions for details.
# will include your custom data
my_meta <- ga_meta("data", propertyId = 206670707)
custom <- ga_data(
my_property_id,
metrics = c("customEvent:credits_spent"),
dimensions = c("date","customUser:last_level","customEvent:achievement_id"),
date_range = c("2020-03-31", "2020-04-27"),
limit = -1
)You can also create custom metrics and dimensions on the fly with calculated metrics. These let you send in combinations of metrics or dimensions:
# metric and dimension expressions
# create your own named metrics
ga_data(
my_property_id,
metrics = c("activeUsers","sessions",sessionsPerUser = "sessions/activeUsers"),
dimensions = c("date","city","dayOfWeek"),
date_range = c("2020-03-31", "2020-04-27"),
limit = 100
)
## A tibble: 100 x 6
# date city dayOfWeek activeUsers sessions sessionsPerUser
# <date> <chr> <chr> <dbl> <dbl> <dbl>
# 1 2020-04-03 Kaliningrad 6 3 3 1
# 2 2020-04-19 Munich 1 3 4 1.33
# 3 2020-04-27 Hamburg 2 3 3 1
# 4 2020-04-16 London 5 5 6 1.2
#...
# create your own aggregation dimensions
ga_data(
my_property_id,
metrics = c("activeUsers","sessions"),
dimensions = c("date","city","dayOfWeek", cdow = "city/dayOfWeek"),
date_range = c("2020-03-31", "2020-04-27"),
limit = 100
)
## A tibble: 100 x 6
# date city dayOfWeek cdow activeUsers sessions
# <date> <chr> <chr> <chr> <dbl> <dbl>
# 1 2020-04-18 (not set) 7 (not set)/7 5 6
# 2 2020-04-14 Madrid 3 Madrid/3 5 6
# 3 2020-04-17 London 6 London/6 5 6
# useful for creating referral data
ga_data(
my_property_id,
metrics = c("activeUsers","sessions"),
dimensions = c("date", sessionMediumSource = "sessionMedium/sessionSource"),
date_range = c("2020-03-31", "2020-04-27"),
limit = 100
)
## A tibble: 100 x 4
# date sessionMediumSource activeUsers sessions
# <date> <chr> <dbl> <dbl>
# 1 2020-04-27 organic/google 80 93
# 2 2020-04-15 organic/google 79 101
# 3 2020-04-07 organic/google 72 87You can send in up to 4 date ranges, via a vector of dates:
date_range4 <- ga_data(
my_property_id,
metrics = c("activeUsers","sessions"),
dimensions = c("date","city","dayOfWeek"),
date_range = c("2020-03-31", "2020-04-06",
"2020-04-07", "2020-04-14",
"2020-04-15", "2020-04-22",
"2020-04-23", "2020-04-30"),
limit = -1
)The date is output with a dateRange column indicating which date ranges the data belongs to:
date_range4
# A tibble: 7,948 x 6
# date city dayOfWeek dateRange activeUsers sessions
# <date> <chr> <chr> <chr> <dbl> <dbl>
# 1 2020-04-06 Laval 2 date_range_0 1 1
# 2 2020-04-29 Ghent 4 date_range_3 1 1
# 3 2020-03-31 Wokingham 3 date_range_0 1 1
# 4 2020-04-01 Zielona Gora 4 date_range_0 1 1
# 5 2020-04-16 Charlottesville 5 date_range_2 1 1
# 6 2020-04-25 Fulshear 7 date_range_3 1 1
# … with 7,938 more rowsYou can send in dates as strings in YYYY-MM-DD format; as R Dates (e.g. Sys.Date()) or via the API keywords “today”, “yesterday”, or “NdaysAgo”)
# use R to make useful date vectors
dates <- rev(seq(Sys.Date(), by = -7, length.out = 8))
dates
#[1] "2020-10-19" "2020-10-26" "2020-11-02" "2020-11-09" "2020-11-16" "2020-11-23" "2020-11-30" "2020-12-07"
# r dates
ga_data(
my_property_id,
metrics = c("activeUsers","sessions"),
dimensions = c("date","city","dayOfWeek"),
date_range = dates,
limit = -1
)
# text dates
ga_data(
my_property_id,
metrics = c("activeUsers","sessions"),
dimensions = c("date","city","dayOfWeek"),
date_range = c("yesterday","today","3daysAgo","2daysAgo"),
limit = -1)Filters are simpler to create but more flexible than in Universal Analytics.
There is now only one filter function - ga_data_filter(). As was the case for google_analytics() , you use the filter function to construct metric filters or dimension filters in the dim_filters or met_filters parameters in your ga_data() call.
ga_data(
206670707,
metrics = c("activeUsers","sessions"),
dimensions = c("date","city","dayOfWeek"),
date_range = c("2020-03-31", "2020-04-27"),
dim_filters = ga_data_filter(city=="Copenhagen"),
limit = 100
)
# A tibble: 17 x 5
# date city dayOfWeek activeUsers sessions
# <date> <chr> <chr> <dbl> <dbl>
# 1 2020-04-16 Copenhagen 5 3 4
# 2 2020-04-10 Copenhagen 6 2 2
# 3 2020-04-15 Copenhagen 4 2 2
# 4 2020-04-17 Copenhagen 6 2 2
# ...The base object is ga_data_filter() - this holds the logic for the specific metric or dimension you are using. The function uses a new DSL for GA4 filters, the syntax rules are detailed below:
ga_data()
city=="Copenhagen"
ga_meta("data")
"city", "session"), or unquoted ( city or session) if you want to use validation.city or session), or you have fetched your custom fields via ga_meta("data", propertyId=123456)
==, >, >=, <, <= for metrics==, %begins%, %ends%, %contains%, %contains%, %regex%, %regex_partial% for dimensions%BEGINS%, %ENDS% etc. or %==% for case insensitive exact matches"dim1"), numerics (55), string vectors (c("dim1", "dim2")), numeric vectors (c(1,2,3)) or NULL (NULL) which will correspond to different types of filters&, |, ! which correspond to AND, OR and NOT respectively.Fields are metrics and dimensions that are available to your GA4 implementation, including custom fields. You can see what is available by calling the ga_meta("data") function.
Do not construct metric filters and use in the dim_filters argument or vice-versa.
You can use quoted ("city", "session") or unquoted fields ( city or session) which will check the field is valid before you send it to the API.
If you want to use custom fields from your property, do a call to ga_meta("data", propertyId=1234546) replacing your propertyId for the GA4 property that has the custom fields. Once fetched, they will be placed in your local environment for all future calls to ga_data_filter() - use the custom events with a cust_ prefix e.g.
# gets fields including custom event field "customEvent:test_dim"
my_meta <- ga_meta("data", propertyId = 206670707)
# use the custom event in a filter
ga_data_filter(cust_test_dim == "test")Values are checked in the filter object based on the R class of the object you are passing in as its value:
character: stringFilter - e.g. "Copenhagen"
character vector: inListFilter e.g. c("Copenhagen","London","New York")
numeric: NumericFilter e.g. 5
numeric 2-length vector: BetweenFilter e.g. c(5, 10)
NULL: Will filter for NULL e.g. city==NULL - often used with ! (not NULL)e.g. if you pass in a character of length one ("Copenhagen") then it will assume to be a class StringFilter (all dimensions that match “Copenhagen”) if you pass in a character of length greater than one c("Copenhagen","London","New York"), then it assume to be a class InListFilter (dimensions must match one in the list)
All filters are made up of filter expressions using ga_data_filter():
simple_filter <- ga_data(
206670707,
metrics = c("activeUsers","sessions"),
dimensions = c("date","city","dayOfWeek"),
date_range = c("2020-03-31", "2020-04-27"),
dim_filters = ga_data_filter(city=="Copenhagen"),
limit = 100
)
simple_filter
# A tibble: 17 x 5
# date city dayOfWeek activeUsers sessions
# <date> <chr> <chr> <dbl> <dbl>
# 1 2020-04-16 Copenhagen 5 3 4
# 2 2020-04-10 Copenhagen 6 2 2
# 3 2020-04-15 Copenhagen 4 2 2
# 4 2020-04-17 Copenhagen 6 2 2
# ...If you need more complicated filters, then build them using the DSL syntax. This lets you combine ga_data_filter() objects in various ways.
## filter clauses
# OR string filter
ga_data_filter(city=="Copenhagen" | city == "London")## ===orGroup:
## [[1]]
## --GA4 Filter:
## --| city
## ----stringFilter:
## value: Copenhagen | matchType: EXACT | caseSensitive: TRUE
## [[2]]
## --GA4 Filter:
## --| city
## ----stringFilter:
## value: London | matchType: EXACT | caseSensitive: TRUE
# inlist string filter - equivalent to above
ga_data_filter(city==c("Copenhagen","London"))## --| city
## ----inListFilter:
## values: Copenhagen London
## caseSensitive: TRUE
# AND string filters
ga_data_filter(city=="Copenhagen" & dayOfWeek == "5")## ===andGroup:
## [[1]]
## --GA4 Filter:
## --| city
## ----stringFilter:
## value: Copenhagen | matchType: EXACT | caseSensitive: TRUE
## [[2]]
## --GA4 Filter:
## --| dayOfWeek
## ----stringFilter:
## value: 5 | matchType: EXACT | caseSensitive: TRUE
# NOT string filter
ga_data_filter(!(city=="Copenhagen" | city == "London"))## ===notExpression:
## ===orGroup:
## [[1]]
## --GA4 Filter:
## --| city
## ----stringFilter:
## value: Copenhagen | matchType: EXACT | caseSensitive: TRUE
## [[2]]
## --GA4 Filter:
## --| city
## ----stringFilter:
## value: London | matchType: EXACT | caseSensitive: TRUE
# multiple filter clauses
ga_data_filter(city==c("Copenhagen","London","Paris","New York") &
(dayOfWeek=="5" | dayOfWeek=="6"))## =======andGroup:
## [[1]]
## --GA4 Filter:
## --| city
## ----inListFilter:
## values: Copenhagen London Paris New York
## caseSensitive: TRUE
##
## [[2]]
## ===orGroup:
## [[1]]
## --GA4 Filter:
## --| dayOfWeek
## ----stringFilter:
## value: 5 | matchType: EXACT | caseSensitive: TRUE
## [[2]]
## --GA4 Filter:
## --| dayOfWeek
## ----stringFilter:
## value: 6 | matchType: EXACT | caseSensitive: TRUEValidation is carried out if the field is unquoted. If you don’t want validation use quotes.
# validation of fields - correct
ga_data_filter(city=="Copenhagen")## --| city
## ----stringFilter:
## value: Copenhagen | matchType: EXACT | caseSensitive: TRUE
# validation of fields - error
tryCatch(ga_data_filter(cittty=="Copenhagen"),
error = function(err) err$message)## [1] "object 'cittty' not found"
# avoid validation by quoting
ga_data_filter("cittty"=="Copenhagen")## --| cittty
## ----stringFilter:
## value: Copenhagen | matchType: EXACT | caseSensitive: TRUEFor custom fields use ga_meta("data", propertyId=12345) first to fetch them.
# gets fields including custom event field "customEvent:test_dim"
my_meta <- ga_meta("data", propertyId = 206670707)
# use the custom event in a filter
ga_data_filter(cust_test_dim == "test")met_filters
An example of metric filters are below:
metric_filter <- ga_data(
206670707,
metrics = c("activeUsers","sessions"),
dimensions = c("date","city","dayOfWeek"),
date_range = c("2020-03-31", "2020-04-27"),
met_filters = ga_data_filter(sessions>10),
limit = 100
)
metric_filter
# A tibble: 7 x 5
# date city dayOfWeek activeUsers sessions
# <date> <chr> <chr> <dbl> <dbl>
#1 2020-04-08 (not set) 4 18 21
#2 2020-04-08 Rome 4 12 14
#3 2020-04-15 (not set) 4 9 11
#4 2020-04-27 (not set) 2 9 11
# ...
## numeric filter types
# numeric equal filter
ga_data_filter(sessions==5)## --| sessions
## ----numericFilter:
## operation: EQUAL | value: 5
# between numeric filter
ga_data_filter(sessions==c(5,6))## --| sessions
## ----betweenFilter:
## from: 5 to: 6
# greater than numeric
ga_data_filter(sessions > 0)## --| sessions
## ----numericFilter:
## operation: GREATER_THAN | value: 0
# greater than or equal
ga_data_filter(sessions >= 1)## --| sessions
## ----numericFilter:
## operation: GREATER_THAN_OR_EQUAL | value: 1
# less than numeric
ga_data_filter(sessions < 100)## --| sessions
## ----numericFilter:
## operation: LESS_THAN | value: 100
# less than or equal numeric
ga_data_filter(sessions <= 100)## --| sessions
## ----numericFilter:
## operation: LESS_THAN_OR_EQUAL | value: 100dim_filters
All the string filters that can be used are below:
## string filter types
# begins with string
ga_data_filter(city %begins% "Cope")## --| city
## ----stringFilter:
## value: Cope | matchType: BEGINS_WITH | caseSensitive: TRUE
# ends with string
ga_data_filter(city %ends% "hagen")## --| city
## ----stringFilter:
## value: hagen | matchType: ENDS_WITH | caseSensitive: TRUE
# contains string
ga_data_filter(city %contains% "ope")## --| city
## ----stringFilter:
## value: ope | matchType: CONTAINS | caseSensitive: TRUE
# regex (full) string
ga_data_filter(city %regex% "^Cope")## --| city
## ----stringFilter:
## value: ^Cope | matchType: FULL_REGEXP | caseSensitive: TRUE
# regex (partial) string
ga_data_filter(city %regex_partial% "ope")## --| city
## ----stringFilter:
## value: ope | matchType: PARTIAL_REGEXP | caseSensitive: TRUEBy default string filters are case sensitive. Use UPPERCASE operator to make then case insensitive
# begins with string (case insensitive)
ga_data_filter(city %BEGINS% "cope")## --| city
## ----stringFilter:
## value: cope | matchType: BEGINS_WITH | caseSensitive: FALSE
# ends with string (case insensitive)
ga_data_filter(city %ENDS% "Hagen")## --| city
## ----stringFilter:
## value: Hagen | matchType: ENDS_WITH | caseSensitive: FALSE
# case insensitive exact match
ga_data_filter(city %==% "copeNHAGen")## --| city
## ----stringFilter:
## value: copeNHAGen | matchType: EXACT | caseSensitive: FALSEYou can also recursively nest filter expressions to make more complicated ones.
The filter below looks for visitors from Copenhagen, London, Paris or New York who arrived on day 5 or 6 of the week, or from Google referrers but not including Google Ads.
# use previously created filters to build another filter expression:
# multiple filter clauses
f1 <- ga_data_filter(city==c("Copenhagen","London","Paris","New York") &
(dayOfWeek=="5" | dayOfWeek=="6"))
# build up complicated filters
f2 <- ga_data_filter(f1 | sessionSource=="google" & !city=="(not set)")
f3 <- ga_data_filter(f2 & !sessionMedium=="cpc")
f3## ===============andGroup:
## [[1]]
## ===========orGroup:
## [[1]]
## =======andGroup:
## [[1]]
## --GA4 Filter:
## --| city
## ----inListFilter:
## values: Copenhagen London Paris New York
## caseSensitive: TRUE
##
## [[2]]
## ===orGroup:
## [[1]]
## --GA4 Filter:
## --| dayOfWeek
## ----stringFilter:
## value: 5 | matchType: EXACT | caseSensitive: TRUE
## [[2]]
## --GA4 Filter:
## --| dayOfWeek
## ----stringFilter:
## value: 6 | matchType: EXACT | caseSensitive: TRUE
##
##
## [[2]]
## ===andGroup:
## [[1]]
## --GA4 Filter:
## --| sessionSource
## ----stringFilter:
## value: google | matchType: EXACT | caseSensitive: TRUE
## [[2]]
## notExpression:
## --GA4 Filter:
## --| city
## ----stringFilter:
## value: (not set) | matchType: EXACT | caseSensitive: TRUE
##
##
## [[2]]
## notExpression:
## --GA4 Filter:
## --| sessionMedium
## ----stringFilter:
## value: cpc | matchType: EXACT | caseSensitive: TRUEYou can use filter expression objects above directly like so:
complex_filter <- ga_data(
206670707,
metrics = c("activeUsers","sessions"),
dimensions = c("date","city","dayOfWeek"),
date_range = c("2020-03-31", "2020-04-27"),
dim_filters = f3,
limit = 100
)
complex_filter
## A tibble: 100 x 5
# date city dayOfWeek activeUsers sessions
# <date> <chr> <chr> <dbl> <dbl>
# 1 2020-04-27 Melbourne 2 3 4
# 2 2020-04-10 Eindhoven 6 2 3
# 3 2020-04-07 Bristol 3 2 2
# 4 2020-04-01 Reston 4 2 2
# ...You can order or sort results using a new DSL via the function ga_data_order() that operate on the fields (dimensions/metrics) in your returned data.
The DSL will validate the fields you are sending in are valid. You then prefix the field with a + for ascending order or - for descending order like so:
# session in descending order
ga_data_order(-sessions)## [[1]]
## ==GA4 OrderBy==
## Metric: sessions
## Descending: TRUE
# city dimension in ascending alphanumeric order
ga_data_order(+city)## [[1]]
## ==GA4 OrderBy==
## Dimension: city
## OrderType: ALPHANUMERIC
## Descending: FALSEYou can have multiple orders - add the -/+{field} after the former without commas:
# as above plus sessions in descending order
ga_data_order(+city -sessions)## [[1]]
## ==GA4 OrderBy==
## Dimension: city
## OrderType: ALPHANUMERIC
## Descending: FALSE
##
## [[2]]
## ==GA4 OrderBy==
## Metric: sessions
## Descending: TRUE
# as above plus activeUsers in ascending order
ga_data_order(+city -sessions +activeUsers)## [[1]]
## ==GA4 OrderBy==
## Dimension: city
## OrderType: ALPHANUMERIC
## Descending: FALSE
##
## [[2]]
## ==GA4 OrderBy==
## Metric: sessions
## Descending: TRUE
##
## [[3]]
## ==GA4 OrderBy==
## Metric: activeUsers
## Descending: FALSEFor dimensions, you have a choice on what type of sort is available:
ALPHANUMERIC - For example, “2” < “A” < “X” < “b” < “z”CASE_INSENSITIVE_ALPHANUMERIC - Case insensitive alphanumeric sort by lower case Unicode code point. For example, “2” < “A” < “b” < “X” < “z”NUMERIC - Dimension values are converted to numbers before sorting. For example in NUMERIC sort, “25” < “100”, and in ALPHANUMERIC sort, “100” < “25”. Non-numeric dimension values all have equal ordering value below all numeric valuesUse ga_data_order() objects in the orderBys argument:
ga_data(
206670707,
metrics = c("activeUsers","sessions"),
dimensions = c("date","city","dayOfWeek"),
date_range = c("2020-03-31", "2020-04-27"),
orderBys = ga_data_order(-sessions -dayOfWeek)
)
## A tibble: 100 x 5
# date city dayOfWeek activeUsers sessions
# <date> <chr> <chr> <dbl> <dbl>
# 1 2020-04-08 (not set) 4 18 21
# 2 2020-04-08 Rome 4 12 14
# 3 2020-04-20 London 2 6 14
# 4 2020-04-09 Warsaw 5 5 11
# 5 2020-04-15 (not set) 4 9 11
# 6 2020-04-21 Amsterdam 3 3 11
# 7 2020-04-27 (not set) 2 9 11
# ...You can also combine ga_data_order() objects with c()
a <- ga_data_order(-sessions)
b <- ga_data_order(-dayOfWeek, type = "NUMERIC")
ga_data(
206670707,
metrics = c("activeUsers","sessions"),
dimensions = c("date","city","dayOfWeek"),
date_range = c("2020-03-31", "2020-04-27"),
orderBys = c(a, b),
limit = 100
)
## A tibble: 100 x 5
# date city dayOfWeek activeUsers sessions
# <date> <chr> <chr> <dbl> <dbl>
# 1 2020-04-08 (not set) 4 18 21
# 2 2020-04-08 Rome 4 12 14
# 3 2020-04-20 London 2 6 14
# 4 2020-04-09 Warsaw 5 5 11
# 5 2020-04-15 (not set) 4 9 11
# 6 2020-04-21 Amsterdam 3 3 11
# 7 2020-04-27 (not set) 2 9 11
# ...Fields are metrics and dimensions that are available to your GA4 implementation, including custom fields. You can see what is available by calling the ga_meta("data") function.
You can use quoted ("city", "session") or unquoted fields ( city or session) which will check the field is valid before you send it to the API.
If you want to use custom fields from your property, do a call to ga_meta("data", propertyId=1234546) similar to the filter fields explained above, and prefix the custom field with cust_
Real-time data can be fetched with the same function as the regular Data API, but it is calling another endpoint. Add the realtime=TRUE argument to the function.
A limited subset of dimensions and metrics are available in the real-time API. Date ranges are ignored.
# run a real-time report
realtime <- ga_data(
206670707,
metrics = "activeUsers",
dimensions = "city",
dim_filters = ga_data_filter(city=="Copenhagen"),
limit = 100,
realtime = TRUE)Each API call includes the TOTAL, MAXIMUM and MINIMUM metric aggregations in the returned data.frame’s metadata. You can access this data using base R’s attr() function or use ga_data_aggregations() to extract the data.frames:
aggs <- ga_data(
206670707,
date_range = c(Sys.Date() - 4, Sys.Date() - 1),
metrics = "activeUsers",
dimensions = c("city","unifiedScreenName"),
limit = 100)
all_aggs <- ga_data_aggregations(aggs, type = "all")
all_aggs
#$totals
## A tibble: 1 x 4
# city unifiedScreenName dateRange activeUsers
# <chr> <chr> <chr> <dbl>
#1 RESERVED_TOTAL RESERVED_TOTAL date_range_0 250
#
#$maximums
## A tibble: 1 x 4
# city unifiedScreenName dateRange activeUsers
# <chr> <chr> <chr> <dbl>
#1 RESERVED_MAX RESERVED_MAX date_range_0 4
#
#$minimums
## A tibble: 1 x 4
# city unifiedScreenName dateRange activeUsers
# <chr> <chr> <chr> <dbl>
#1 RESERVED_MIN RESERVED_MIN date_range_0 0
# now in a list
all_aggs$totals
## A tibble: 1 x 4
# city unifiedScreenName dateRange activeUsers
# <chr> <chr> <chr> <dbl>
#1 RESERVED_TOTAL RESERVED_TOTAL date_range_0 250
# extract individual aggregations individually
maxes <- ga_data_aggregations(aggs, type = "maximums")
maxes
## A tibble: 1 x 4
# city unifiedScreenName dateRange activeUsers
# <chr> <chr> <chr> <dbl>
#1 RESERVED_MAX RESERVED_MAX date_range_0 4If you request more than one date range, the aggregations will be calculated for each one:
# use R to generate some dates
dates <- rev(seq(Sys.Date(), by = -7, length.out = 8))
dates
#[1] "2020-10-19" "2020-10-26" "2020-11-02" "2020-11-09" "2020-11-16" "2020-11-23" "2020-11-30" "2020-12-07"
aggs <- ga_data(
206670707,
date_range = dates,
metrics = "activeUsers",
dimensions = c("city","unifiedScreenName"),
limit = 100)
# get the totals
ga_data_aggregations(aggs, type = "totals")
## A tibble: 4 x 4
# city unifiedScreenName dateRange activeUsers
# <chr> <chr> <chr> <dbl>
#1 RESERVED_TOTAL RESERVED_TOTAL date_range_0 200
#2 RESERVED_TOTAL RESERVED_TOTAL date_range_1 4
#3 RESERVED_TOTAL RESERVED_TOTAL date_range_2 2
#4 RESERVED_TOTAL RESERVED_TOTAL date_range_3 399There is no sampling but there are token quotas for API fetches on a per-project basis. Normally these are not visible until you are close to the quota limits, but you can see them if you set the googleAuthR verbose level below 3 (options(googleAuthR.verbose=2))) or if the API call costs more than 50 units.
The bigger and more complex the query you make, the more tokens you use.
See this Google guide on how API quotas are assigned. The quotas are on a per GCP project and Ga4 web property level, and you get more if on GA360.
An example taken from above:
options(googleAuthR.verbose=2)
complex_filter <- ga_data(
206670707,
metrics = c("activeUsers","sessions"),
dimensions = c("date","city","dayOfWeek"),
date_range = c("2020-03-31", "2020-04-06",
"2020-04-07", "2020-04-14",
"2020-04-15", "2020-04-22",
"2020-04-23", "2020-04-30"),
metricAggregations = c("TOTAL","MINIMUM","MAXIMUM"),
orderBys = ga_data_order(-sessions +city),
dim_filters = ga_data_filter(
city==c("Copenhagen","London","Paris","New York") &
(dayOfWeek=="5" | dayOfWeek=="6")),
limit = -1
)
#>ℹ 2020-11-24 16:12:36 > tokensPerDay: Query Cost [ 15 ] / Remaining [ 24847 ]
#>ℹ 2020-11-24 16:12:36 > tokensPerHour: Query Cost [ 15 ] / Remaining [ 4967 ]
#>ℹ 2020-11-24 16:12:36 > concurrentRequests: 10 / 10
#>ℹ 2020-11-24 16:12:36 > serverErrorsPerProjectPerHour: 10 / 10The quotas are:
tokensPerDay - how many tokens in 24hrstokensPerHour - how many tokens in 1 hrconcurrentRequests - how many API requests at onceserverErrorsPerProjectPerHour - how many bad API calls you can make per project/hrIf you ever need to inspect the API request, set options(googleAuthR.verbose=2) to see the request JSON. This is helpful in bug reports.
If you use the raw_json argument only in ga_data() to send in a string of the JSON as specified by the runReport object, this can be used to fetch unimplemented API features or buggy requests to help debugging.
ga_data(206670707, raw_json = '{"metrics":[{"name":"sessions"}],"orderBys":[{"dimension":{"orderType":"ALPHANUMERIC","dimensionName":"date"},"desc":false}],"dimensions":[{"name":"date"}],"dateRanges":[{"startDate":"2021-01-01","endDate":"2021-01-07"}],"keepEmptyRows":true,"limit":100,"returnPropertyQuota":true}')
# ℹ 2021-04-13 10:50:17 > Making API request with raw JSON: {"metrics":[{"name":"sessions"}],"orderBys":[{"dimension":{"orderType":"ALPHANUMERIC","dimensionName":"date"},"desc":false}],"dimensions":[{"name":"date"}],"dateRanges":[{"startDate":"2021-01-01","endDate":"2021-01-07"}],"keepEmptyRows":true,"limit":100,"returnPropertyQuota":true}
# ℹ 2021-04-13 10:50:17 > Request: https://analyticsdata.googleapis.com/v1beta/properties/206670707:runReport/
# ℹ 2021-04-13 10:50:17 > Body JSON parsed to: "{\"metrics\":[{\"name\":\"sessions\"}],\"orderBys\":[{\"dimension\":{\"orderType\":\"ALPHANUMERIC\",\"dimensionName\":\"date\"},\"desc\":false}],\"dimensions\":[{\"name\":\"date\"}],\"dateRanges\":[{\"startDate\":\"2021-01-01\",\"endDate\":\"2021-01-07\"}],\"keepEmptyRows\":true,\"limit\":100,\"returnPropertyQuota\":true}"
#ℹ 2021-04-13 10:50:18 > tokensPerDay: Query Cost [ 1 ] / Remaining [ 24927 ]
#ℹ 2021-04-13 10:50:18 > tokensPerHour: Query Cost [ 1 ] / Remaining [ 4927 ]
#ℹ 2021-04-13 10:50:18 > concurrentRequests: 10 / 10
#ℹ 2021-04-13 10:50:18 > serverErrorsPerProjectPerHour: 10 / 10
#ℹ 2021-04-13 10:50:18 > Downloaded [ 7 ] of total [ 7 ] rows
## A tibble: 7 x 2
# date sessions
# <date> <dbl>
#1 2021-01-01 33
#2 2021-01-02 34
#3 2021-01-03 66
#4 2021-01-04 89
# ...You can also query the realtime API:
ga_data(
propertyId = ga4_propertyId,
raw_json = '{"metrics":[{"name":"activeUsers"}],"limit":100,"returnPropertyQuota":true}',
realtime = TRUE)
## A tibble: 1 x 1
# activeUsers
# <dbl>
#1 2If you pass in an R list instead of raw JSON string that will be converted into JSON via jsonlite::fromJSON()