Retention with Google Analytics Data API and plotly

User retention is one of the most important metrics for any app. To define retention we need to define a cohort. In the case of weekly retention, a cohort is all users who started using the app in a given week, and the users will be retained only if they are actively using the app the following weeks. So if 100 users started using the app last week and from those users only 50 of them have used the app this week, we’d have a 50% retention for last week’s cohort.

Google Analytics exposes the retention data through the GA4 API, which we will use for this blog. Here’s the Quickstart Guide to set up the API access and credentials. Once the API is set up, we’ll install the Python client library google-analytics-data and we can start making API calls. Note that this will only work for a GA4 property, if you have a UA property, see this guide.

First we need to import the Client and the Types we need for a weekly retention report. We also need pandas for dataframe manipulation and for plotting.

from import BetaAnalyticsDataClient
from import RunReportRequest
from import DateRange
from import Dimension
from import Metric
from import CohortSpec, CohortsRange, Cohort
import pandas as pd
import as px

Once we have all imports ready, we need to set up the client and our report request.

property_id = "YOUR-PROPERTY-ID"
client = BetaAnalyticsDataClient(credentials=your_credentials)
end_offset = 5
# Week starts on sunday, ends on saturday
saturdays = pd.date_range('2022-01-01',, freq='W-SAT')
end_dates = [saturday.strftime("%Y-%m-%d") for saturday in saturdays]
start_dates = [(saturday - dt.timedelta(6)).strftime("%Y-%m-%d") for saturday in saturdays]
cohorts = [Cohort(name=start,
                  date_range=DateRange(start_date=start, end_date=end))
           for start, end in zip(start_dates, end_dates)]
request = RunReportRequest(
    dimensions=[Dimension(name="cohort"), Dimension(name='cohortNthWeek')],

The RunReportRequest constructor will construct a report request with the parameters we supply. For weekly retention we need the cohortNthWeek dimension and the cohortActiveUsers metric. Next we need to define the cohort specification. for that we use the CohortSpec object. We supply the cohorts we are interested in using the cohorts parameter. This takes a list of Cohort objects that we define as follows. We want to display a 5 week retention and the week starts on Sunday and ends on Saturday. Our first week will start on 26-12-2021. From that we can create start and end dates we need for the date_range parameter. The cohort dimension we’re interested in is the firstSessionDate and the name of the cohorts will be the start date of each cohort, which we will use later on to index our dataframe. For the cohorts_range parameter we need to specify the granularity and the end_offset. The granularity can be DAILY ,WEEKLY or MONTHLY. We will use WEEKLY as that’s the granularity we’re interested in. The end_offset will be 5 weeks, so we will see at most 5 weeks of retention for each cohort. Once we’re done setting up the report we can run the report. The response will be limited to 10000 rows unless we set the limit parameter, which can be set to 100000 at most. For more rows, use pagination.

response = client.run_report(request)

The response will be in JSON format and will include rows of the resulting report. Each row will have the metrics and dimensions for each cohort and for each date range. In order to visualise the retention data we need a dataframe indexed by the cohort start date and with columns from Week 0 to Week 5. We will build a simple list of lists dataframe using the response data. Each list will represent one cohort.

columns = ['cohort_date'] + [f'Week {n}' for n in range(end_offset + 1)]
df = []
for date in start_dates:
    cohort = [date]
    for row in response.rows:
        if row.dimension_values[0].value == date:
df = pd.DataFrame(df, columns=columns)
df = df.set_index('cohort_date')

Because the response is not sorted by cohort, we look up each start date and the metric values to our row. The dataframe will look like this.

cohort_date Week 0 Week 1 Week 2 Week 3 Week 4 Week 5                                       
2021-12-26     619    239    168    146    143     84
2022-01-02     709    217    167    139    100   None
2022-01-09     678    217    156    102   None   None
2022-01-16     899    261    138   None   None   None
2022-01-23    1415    303   None   None   None   None

We want to show retention as a percentage but we also want to keep the number of users because that is important information to show on a retention plot. We will keep a copy of the original dataframe to use as custom data for the plot and divide all columns by the first column to get the fraction of users retained.

df = df.astype('float')
df_custom = df.copy()
df = df.divide(df['Week 0'], axis = 0)

The final dataframe will look like this:

cohort_date  Week 0    Week 1    Week 2    Week 3    Week 4    Week 5                                                     
2021-12-26      1.0  0.386107  0.271405  0.235864  0.231018  0.135703
2022-01-02      1.0  0.306065  0.235543  0.196051  0.141044       NaN
2022-01-09      1.0  0.320059  0.230088  0.150442       NaN       NaN
2022-01-16      1.0  0.290323  0.153504       NaN       NaN       NaN
2022-01-23      1.0  0.214134       NaN       NaN       NaN       NaN

Now the fun part: visualisation. We will use plotly to visualise this table as a heatmap. Plotly express has a great plot for this called imshow(). Alternatively you can use go.Heatmap, which is the underlying plot in imshow()

fig = px.imshow(df,
                labels=dict(y='Cohort Start Date', x='Weeks', color='Retention'),
                      hovertemplate='Week: %{x} <br>'
                                    'Retention: %{z:.2%} <br>'
                                    'Cohort Start Date: %{y}<br>'
                                    'Users: %{customdata}'
fig.update_layout(dict(title='Weekly Retention',
		 height = 500,
		 width = 800))
fig.update_traces(showscale = False,
		coloraxis = None,
		colorscale = 'burgyl',
		xgap = 2,
		ygap = 2)

In order to display the number of users as well as the percentage retained, we need to add custom data to our plot and use it in the hovertemplate. The <extra></extra>part removes the trace name from the hover box. After some formatting we get the final plot.

In this blog, we saw how to work with cohort retention data from the GA4 API and how to visualise the retention data using plotly. There are many other metrics and dimensions that can be explored with the GA4 API, hope this blog was useful and will help you with your own GA4 property analytics.

By Zeynep Bicer
Categorized as blog

Leave a comment

Your email address will not be published. Required fields are marked *