Skip to main content

​
Overview

The GoogleAnalytics class provides integration with Google Analytics 4 (GA4) to fetch traffic metrics, engagement data, and conversion information for your content.

​
Installation

from data_sources.modules.google_analytics import GoogleAnalytics

​
Authentication

The module uses Google service account credentials for authentication.

​
Environment Variables

GA4_PROPERTY_ID=your-property-id
GA4_CREDENTIALS_PATH=/path/to/credentials.json

​
Service Account Setup

  1. Create a service account in Google Cloud Console
  2. Download the credentials JSON file
  3. Grant the service account “Viewer” access to your GA4 property
  4. Set the credentials path in your environment

​
Initialization

ga = GoogleAnalytics(
    property_id="123456789",  # Optional, defaults to env var
    credentials_path="/path/to/credentials.json"  # Optional, defaults to env var
)
​
property_id
str
GA4 property ID. Defaults to GA4_PROPERTY_ID environment variable.
​
credentials_path
str
Path to service account credentials JSON. Defaults to GA4_CREDENTIALS_PATH environment variable.

​
Methods

​
get_top_pages

Get top performing pages by pageviews. 
top_pages = ga.get_top_pages(
    days=30,
    limit=20,
    path_filter="/blog/"
)
​
days
int
default:"30"
Number of days to look back
​
limit
int
default:"20"
Number of results to return
​
path_filter
str
Filter pages by path (e.g., “/blog/”)
​
results
list
List of page performance data
​
path
str
Page URL path
​
title
str
Page title
​
pageviews
int
Total pageviews
​
sessions
int
Total sessions
​
avg_session_duration
float
Average session duration in seconds
​
bounce_rate
float
Bounce rate (0-1)
​
engagement_rate
float
Engagement rate (0-1)

​
get_page_trends

Get traffic trends for a specific page over time. 
trends = ga.get_page_trends(
    url="/blog/podcast-monetization",
    days=90,
    granularity="week"
)
​
url
str
required
Page path to analyze
​
days
int
default:"90"
Number of days to analyze
​
granularity
str
default:"week"
Time granularity: “day” or “week”
​
trends
dict
​
url
str
Page URL
​
timeline
list
List of data points by period
​
trend_direction
str
“rising”, “declining”, or “stable”
​
trend_percent
float
Percentage change
​
total_pageviews
int
Total pageviews in period

​
get_conversions

Get conversion data by page. 
conversions = ga.get_conversions(
    days=30,
    path_filter="/blog/"
)
​
days
int
default:"30"
Number of days to look back
​
path_filter
str
Filter pages by path
​
results
list
​
path
str
Page URL path
​
title
str
Page title
​
pageviews
int
Total pageviews
​
conversions
float
Total conversions
​
conversion_rate
float
Conversion rate percentage
​
revenue
float
Total revenue

​
get_traffic_sources

Get traffic source breakdown for a page or entire site. 
sources = ga.get_traffic_sources(
    url="/blog/podcast-monetization",  # Optional
    days=30
)
​
url
str
Specific page path (None = all pages)
​
days
int
default:"30"
Number of days to analyze
​
results
list
​
source
str
Traffic source (e.g., “Organic Search”, “Direct”)
​
sessions
int
Total sessions
​
pageviews
int
Total pageviews
​
engagement_rate
float
Engagement rate (0-1)

​
get_declining_pages

Identify pages with declining traffic. 
declining = ga.get_declining_pages(
    comparison_days=30,
    threshold_percent=-20.0,
    path_filter="/blog/"
)
​
comparison_days
int
default:"30"
Compare this many recent days vs previous period
​
threshold_percent
float
default:"-20.0"
Consider declining if drop exceeds this percentage
​
path_filter
str
Filter pages by path
​
results
list
​
path
str
Page URL path
​
title
str
Page title
​
pageviews
int
Current pageviews
​
previous_pageviews
int
Previous period pageviews
​
change_percent
float
Percentage change (negative)
​
priority
str
“high” or “medium”

​
Example Usage

from dotenv import load_dotenv
from data_sources.modules.google_analytics import GoogleAnalytics

load_dotenv('data_sources/config/.env')

ga = GoogleAnalytics()

# Get top 10 blog articles
top_pages = ga.get_top_pages(days=30, limit=10)
for i, page in enumerate(top_pages, 1):
    print(f"{i}. {page['title']}")
    print(f"   {page['path']}")
    print(f"   {page['pageviews']:,} pageviews | {page['engagement_rate']:.1%} engagement")
    print()

# Find declining articles
declining = ga.get_declining_pages(comparison_days=30)
for page in declining[:5]:
    print(f"- {page['title']}")
    print(f"  {page['path']}")
    print(f"  {page['change_percent']:.1f}% change ({page['previous_pageviews']} → {page['pageviews']})")
    print()

​
Source Code Reference

Location: data_sources/modules/google_analytics.py:24 The module uses the Google Analytics Data API v1beta with service account authentication. All requests are made using the BetaAnalyticsDataClient with read-only analytics scope.

Build docs developers (and LLMs) love

Get started for freeTalk to us