davila7--claude-code-templates/cli-tool/components/skills/analytics/google-analytics/REFERENCE.md

Google Analytics Metrics Reference

Complete reference for Google Analytics 4 (GA4) metrics and dimensions.

Core Metrics

User Metrics

Metric	Description	Use Case
activeUsers	Users who engaged with your site or app	Overall audience size
newUsers	First-time users	Growth tracking
totalUsers	Total number of users	Audience reach
userEngagementDuration	Total time users spent engaged	Content quality
engagedSessions	Sessions lasting >10s with conversion or 2+ page views	Quality sessions

Session Metrics

Metric	Description	Use Case
sessions	Total number of sessions	Traffic volume
sessionsPerUser	Average sessions per user	User retention
averageSessionDuration	Mean session length	Engagement depth
bounceRate	Percentage of single-page sessions	Content relevance
engagementRate	Percentage of engaged sessions	Quality of traffic

Page/Screen Metrics

Metric	Description	Use Case
screenPageViews	Total page and screen views	Content consumption
screenPageViewsPerSession	Average pages per session	Site exploration
screenPageViewsPerUser	Average pages per user	User journey depth

Event Metrics

Metric	Description	Use Case
eventCount	Total number of events	Interaction tracking
eventCountPerUser	Average events per user	User activity level
conversions	Total conversion events	Goal achievement
totalRevenue	Total revenue from all sources	Monetization

E-commerce Metrics

Metric	Description	Use Case
transactions	Number of purchases	Sales volume
purchaseRevenue	Revenue from purchases	Sales performance
averagePurchaseRevenue	Average transaction value	Revenue per sale
itemsViewed	Product detail views	Product interest
addToCarts	Items added to cart	Purchase intent
checkouts	Checkout initiations	Conversion funnel

Key Dimensions

Traffic Source Dimensions

Dimension	Description	Example Values
sessionSource	Source of traffic	google, facebook, direct
sessionMedium	Marketing medium	organic, cpc, referral, email
sessionCampaignName	Campaign identifier	spring-sale, black-friday
sessionDefaultChannelGroup	Channel grouping	Organic Search, Paid Social, Direct
firstUserSource	Source of user's first visit	google, twitter, newsletter

Content Dimensions

Dimension	Description	Example Values
pagePath	Page URL path	/blog/post-title, /products/item
pageTitle	Page title	Home, Product Page, Blog Post
pageLocation	Full page URL	https://example.com/page
landingPage	First page of session	/home, /blog/article
exitPage	Last page of session	/checkout, /contact

User Dimensions

Dimension	Description	Example Values
country	User country	United States, United Kingdom
city	User city	New York, London, Tokyo
deviceCategory	Device type	mobile, desktop, tablet
browser	Browser name	Chrome, Safari, Firefox
operatingSystem	OS name	Windows, macOS, Android, iOS

Time Dimensions

Dimension	Description	Example Values
date	Date (YYYYMMDD)	20260118
year	Year	2026
month	Month	01, 02, 03
week	Week number	01, 02, 03
dayOfWeek	Day of week	Sunday, Monday
hour	Hour of day	00-23

Common Metric Combinations

Traffic Analysis

metrics = [
    "sessions",
    "activeUsers",
    "newUsers",
    "engagementRate",
    "bounceRate"
]
dimensions = ["sessionSource", "sessionMedium"]

Content Performance

metrics = [
    "screenPageViews",
    "averageSessionDuration",
    "bounceRate",
    "eventCount"
]
dimensions = ["pagePath", "pageTitle"]

User Behavior

metrics = [
    "activeUsers",
    "sessionsPerUser",
    "screenPageViewsPerSession",
    "userEngagementDuration"
]
dimensions = ["deviceCategory", "country"]

Conversion Tracking

metrics = [
    "conversions",
    "sessions",
    "eventCount",
    "engagementRate"
]
dimensions = ["sessionSource", "sessionMedium", "sessionCampaignName"]

E-commerce Analysis

metrics = [
    "transactions",
    "purchaseRevenue",
    "averagePurchaseRevenue",
    "itemsViewed",
    "addToCarts"
]
dimensions = ["sessionSource", "deviceCategory"]

Date Range Formats

Relative Ranges

• yesterday - Previous day
• today - Current day
• 7daysAgo - Week ago
• 30daysAgo - Month ago
• 90daysAgo - Quarter ago

Absolute Ranges

• Format: YYYY-MM-DD
• Example: 2026-01-01 to 2026-01-31

Common Periods

# Last 7 days
start_date = "7daysAgo"
end_date = "yesterday"

# Last 30 days
start_date = "30daysAgo"
end_date = "yesterday"

# Month-to-date
start_date = "2026-01-01"
end_date = "today"

# Compare periods
current_start = "30daysAgo"
current_end = "yesterday"
previous_start = "60daysAgo"
previous_end = "31daysAgo"

Filters

Basic Filters

# Filter by page path
dimension_filter = {
    "filter": {
        "fieldName": "pagePath",
        "stringFilter": {"value": "/blog"}
    }
}

# Filter by country
dimension_filter = {
    "filter": {
        "fieldName": "country",
        "stringFilter": {"value": "United States"}
    }
}

# Filter by session source
dimension_filter = {
    "filter": {
        "fieldName": "sessionSource",
        "stringFilter": {"value": "google"}
    }
}

Numeric Filters

# Sessions greater than 100
metric_filter = {
    "filter": {
        "fieldName": "sessions",
        "numericFilter": {
            "operation": "GREATER_THAN",
            "value": {"int64Value": "100"}
        }
    }
}

Filter Operators

Operator	Description	Example
EXACT	Exact match	Country = "United States"
BEGINS_WITH	Starts with	Page path starts with "/blog"
ENDS_WITH	Ends with	Page path ends with ".html"
CONTAINS	Contains substring	Page title contains "guide"
REGEX	Regular expression	Path matches pattern

Order By

Sort results by metrics or dimensions:

# Order by sessions descending
order_bys = [{
    "metric": {"metricName": "sessions"},
    "desc": True
}]

# Order by page path ascending
order_bys = [{
    "dimension": {"dimensionName": "pagePath"},
    "desc": False
}]

API Response Structure

{
    "dimensionHeaders": [
        {"name": "sessionSource"},
        {"name": "sessionMedium"}
    ],
    "metricHeaders": [
        {"name": "sessions", "type": "TYPE_INTEGER"},
        {"name": "bounceRate", "type": "TYPE_FLOAT"}
    ],
    "rows": [
        {
            "dimensionValues": [
                {"value": "google"},
                {"value": "organic"}
            ],
            "metricValues": [
                {"value": "1250"},
                {"value": "0.45"}
            ]
        }
    ],
    "rowCount": 1,
    "metadata": {...}
}

Best Practices

Performance

• Request only needed metrics and dimensions
• Use date ranges that balance detail and performance
• Limit results with limit parameter (max 100,000)
• Use pagination for large datasets

Accuracy

• Allow 24-48 hours for data processing
• Use yesterday instead of today for complete data
• Be aware of sampling in large datasets
• Check metadata.samplingMetadatas in responses

Analysis

• Compare periods for context (week-over-week, month-over-month)
• Segment by meaningful dimensions (device, source, location)
• Focus on engagement metrics, not just volume
• Track trends over time, not just snapshots

Common Calculations

Conversion Rate

conversion_rate = (conversions / sessions) * 100

Average Order Value

aov = purchaseRevenue / transactions

Pages per Session

pages_per_session = screenPageViews / sessions

Engagement Rate

engagement_rate = (engagedSessions / sessions) * 100

Revenue per User

rpu = totalRevenue / activeUsers

Resources

• GA4 Dimensions & Metrics Explorer
• GA4 API Reference
• GA4 Query Explorer