guides

Pulling App Engagement Data with Avenue API (R)

Overview

Note: to complete this example you will need to install the AvenueAPI client for R.

In this guide we demonstrate how to download and plot Android app data for Facebook and Tinder using 7Park’s “App Engagement” API endpoint. To replicate this example you will need a valid 7Park Data API key (contact your 7Park sales representative to request a key).

Pulling App Data from the Avenue API

To start, we use the fetch_app_series function to quickly download and restructure data for Facebook and Tinder, saving the JSON return as well as standard dataframes in both “long” and “wide” formats. We can retrieve the raw JSON objects and save them as structured lists in R with the following code:

# Load the AvenueAPI client
library(AvenueAPI)

# Uncomment this line and store your API key here
# ave_key <- 'YOUR_KEY_HERE' 

# This initiates an S4 Class object with associated methods for calling the API:
ave <- connect_avenue(api_key=ave_key) 

# Retrieve data for Facebook and Tinder, saving the JSON returns in the global environment.
fb <- fetch_app_series(ave, app="com.facebook.katana", cadence="daily", start_date='2015-01-01', country_code = 'US')
td <- fetch_app_series(ave, app="com.tinder", cadence="daily", start_date='2015-01-01', country_code = 'US')

The above commands will create two structured data objects for Facebook and Tinder in your working environment (in this example, within the objects named “fb” and “td”). These objects are nested R lists and contain, in addition to app engagement data, information about the API call, any sucess/failure messages, and a summary of available metrics. While this information provides a helpful orientation to the scope of the data object returned by the API, long and wide data formats are typically easier to work with for quick plotting and statistical analysis. With this in mind the AvenueAPI package provides a generic function – transform_avenue_series – to convert the nested JSON return into a long or wide dataframe. These transformations can be quickly performed with the following code:

# Transform the JSON return into long and wide formats to facilitate quick analysis:
fblong <- transform_avenue_series(fb)
fbwide <- transform_avenue_series(fb, wide = TRUE) 
tdlong <- transform_avenue_series(fb, wide = FALSE)

These calls return dataframe structures with the following format:

# Wide data
head(fbwide)

##         date active_users   aupib install_base   mbpau   mbps megabytes
## 1 2015-01-01      59.1256 77.6580      76.1359 82.3968 5.7564   48.7176
## 2 2015-01-02      58.1389 76.4777      76.0207 78.4642 6.1299   45.6182
## 3 2015-01-03      58.2117 76.5988      75.9956 89.2116 6.7771   51.9316
## 4 2015-01-04      58.1845 76.6279      75.9313 94.1296 7.0502   54.7689
## 5 2015-01-05      58.0508 76.5151      75.8684 82.1400 6.4991   47.6830
## 6 2015-01-06      57.7337 76.1207      75.8450 82.8992 6.6123   47.8608
##   minutes    mpau    mps sessions    spau                 app country_code
## 1 27.6346 46.7387 3.2652   8.4633 14.3140 com.facebook.katana           US
## 2 23.5351 40.4808 3.1625   7.4420 12.8003 com.facebook.katana           US
## 3 25.2944 43.4525 3.3009   7.6628 13.1636 com.facebook.katana           US
## 4 26.8646 46.1714 3.4582   7.7684 13.3513 com.facebook.katana           US
## 5 23.6857 40.8016 3.2283   7.3368 12.6386 com.facebook.katana           US
## 6 23.3759 40.4892 3.2296   7.2381 12.5371 com.facebook.katana           US

# Long data
head(fblong)

##         date   value       metric                 app country_code
## 1 2015-01-01 76.1359 install_base com.facebook.katana           US
## 2 2015-01-02 76.0207 install_base com.facebook.katana           US
## 3 2015-01-03 75.9956 install_base com.facebook.katana           US
## 4 2015-01-04 75.9313 install_base com.facebook.katana           US
## 5 2015-01-05 75.8684 install_base com.facebook.katana           US
## 6 2015-01-06 75.8450 install_base com.facebook.katana           US

Also note that, once transformed using transform_avenue_series, the data are properly typed:

str(fblong)

## 'data.frame':    10296 obs. of  5 variables:
##  $ date        : Date, format: "2015-01-01" "2015-01-02" ...
##  $ value       : num  76.1 76 76 75.9 75.9 ...
##  $ metric      : chr  "install_base" "install_base" "install_base" "install_base" ...
##  $ app         : chr  "com.facebook.katana" "com.facebook.katana" "com.facebook.katana" "com.facebook.katana" ...
##  $ country_code: chr  "US" "US" "US" "US" ...

Plotting the Series

Having downloaded data for two apps, we can now build plots for two core measures of app engagement: “daily active users” (DAUs) and “time spent.” Here, we use the “long” dataframe to faciliate quick plot construction with ggplot2. Our first step is to define the metrics of interest:

# Note: this vector is utilized in the next code snippet with a call to the extract (`[`) function: (`fblong[fblong$metric %in% mets, ]`).
mets <- c("active_users", "minutes")

Next, we build a line chart (with both expoential smoothing and the raw series) to illustate engagement trends across time for the Facebook app:

library(ggplot2)
ggplot(data = fblong[fblong$metric %in% mets, ], aes(x = date, y = value, color=metric)) +
    theme(plot.title = element_text(hjust = 0.5)) +
    geom_smooth(se = FALSE, method = 'loess') + 
    geom_line() + xlab("") + ylab("") +
    theme(legend.title = element_blank()) + 
    scale_color_hue(labels=c("DAUs + Trend", "Time Spent + Trend")) +
    ggtitle("Facebook Engagement")

Following this basic pattern, we now construct a comparable chart for Tinder, here using the vline geom to denote the approximate point in the series where Tinder introduced a “pay wall” for some parts of its service:

library(lubridate)
ggplot(data = tdlong[tdlong$metric %in% mets & year(tdlong$date)==2015, ], aes(x = date, y = value, color=metric)) +
    theme(plot.title = element_text(hjust = 0.5)) +
    geom_line() + xlab("") + ylab("") +
    theme(legend.title = element_blank()) + 
    scale_color_hue(labels=c("DAUs", "Time Spent")) +
    ggtitle("Tinder Engagement (2015)") +
    geom_vline(xintercept = as.numeric(as.Date("2015-03-03")), linetype = 4, colour = "black")