google-analytic-process 0.1.2

A simple API for running Google Analytics 4 reports

GA4 Reporter

A simple and clean Python API for running Google Analytics 4 reports. This package provides an easy-to-use interface for extracting data from GA4 properties using the Google Analytics Data API.

Features

• Simple API for running GA4 reports
• Returns data as pandas DataFrames
• Supports custom dimensions and metrics
• Flexible date range selection
• Both class-based and functional interfaces

Installation

pip install ga4-reporter

Prerequisites

1. A Google Analytics 4 property
2. A service account with access to your GA4 property
3. Service account credentials JSON file

Setting up Google Analytics 4 API Access

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Analytics Data API
4. Create a service account and download the credentials JSON file
5. In GA4, add the service account email to your property with "Viewer" permissions

Usage

Using the convenience function (Recommended)

from ga4_reporter import run_report
from datetime import datetime, timedelta

# Define date range
end_date = datetime.now().date()
start_date = end_date - timedelta(days=7)

# Define dimensions and metrics
dimensions = [
    "date",
    "sessionDefaultChannelGroup",
    "sessionCampaignName"
]

metrics = [
    "sessions",
    "transactions",
    "totalRevenue"
]

# Run the report
df = run_report(
    dimensions=dimensions,
    metrics=metrics,
    start_date=start_date,
    end_date=end_date,
    credentials_path="/path/to/credentials.json",
    property_id="276493948"
)

print(df.head())

Using the GA4Reporter class

from ga4_reporter import GA4Reporter
from datetime import datetime, timedelta

# Initialize the reporter
reporter = GA4Reporter(
    property_id="276493948",
    credentials_path="/path/to/credentials.json"
)

# Define parameters
dimensions = ["date", "deviceCategory"]
metrics = ["sessions", "totalUsers"]
start_date = datetime(2024, 1, 1)
end_date = datetime(2024, 1, 31)

# Run the report
df = reporter.run_report(
    dimensions=dimensions,
    metrics=metrics,
    start_date=start_date,
    end_date=end_date
)

print(df.head())

API Reference

run_report() function

Convenience function to run a GA4 report without instantiating the class.

Parameters:

• dimensions (List[str]): List of dimension names (e.g., ["date", "sessionDefaultChannelGroup"])
• metrics (List[str]): List of metric names (e.g., ["sessions", "totalRevenue"])
• start_date (str | date | datetime): Start date for the report
• end_date (str | date | datetime): End date for the report
• credentials_path (str): Path to the service account credentials JSON file
• property_id (str, optional): The GA4 property ID. Defaults to "276493948"
• limit (int, optional): Maximum number of rows to return. Defaults to 1000000
• offset (int, optional): Number of rows to skip. Defaults to 0

Returns:

• pd.DataFrame: DataFrame containing the report data

GA4Reporter class

__init__(property_id, credentials_path)

Initialize the GA4Reporter.

Parameters:

• property_id (str): The GA4 property ID
• credentials_path (str): Path to the service account credentials JSON file

run_report(dimensions, metrics, start_date, end_date, limit=1000000, offset=0)

Run a Google Analytics 4 report.

Parameters: Same as the run_report() function (except credentials_path and property_id which are set during initialization)

Returns:

• pd.DataFrame: DataFrame containing the report data

Available Dimensions and Metrics

For a complete list of available dimensions and metrics, refer to the Google Analytics Data API documentation.

Common Dimensions:

• date
• sessionDefaultChannelGroup
• sessionCampaignName
• deviceCategory
• countryId
• pagePath
• eventName

Common Metrics:

• sessions
• totalUsers
• transactions
• totalRevenue
• engagementRate
• bounceRate
• screenPageViews

Examples

Example 1: Basic Usage

from ga4_reporter import run_report

df = run_report(
    dimensions=["date"],
    metrics=["sessions"],
    start_date="2024-01-01",
    end_date="2024-01-31",
    credentials_path="/path/to/credentials.json",
    property_id="YOUR_PROPERTY_ID"
)

Example 2: Multiple Dimensions and Metrics

from ga4_reporter import run_report
from datetime import datetime, timedelta

end_date = datetime.now().date()
start_date = end_date - timedelta(days=30)

dimensions = [
    "date",
    "sessionDefaultChannelGroup",
    "deviceCategory",
    "newVsReturning"
]

metrics = [
    "sessions",
    "transactions",
    "totalUsers",
    "totalRevenue",
    "engagementRate"
]

df = run_report(
    dimensions=dimensions,
    metrics=metrics,
    start_date=start_date,
    end_date=end_date,
    credentials_path="/path/to/credentials.json",
    property_id="YOUR_PROPERTY_ID"
)

# Process the data
print(f"Total sessions: {df['sessions'].sum()}")
print(f"Total revenue: ${df['totalRevenue'].sum():.2f}")

Example 3: Pagination

from ga4_reporter import GA4Reporter

reporter = GA4Reporter(
    property_id="YOUR_PROPERTY_ID",
    credentials_path="/path/to/credentials.json"
)

# Get first 10,000 rows
df_page1 = reporter.run_report(
    dimensions=["date", "pagePath"],
    metrics=["screenPageViews"],
    start_date="2024-01-01",
    end_date="2024-01-31",
    limit=10000,
    offset=0
)

# Get next 10,000 rows
df_page2 = reporter.run_report(
    dimensions=["date", "pagePath"],
    metrics=["screenPageViews"],
    start_date="2024-01-01",
    end_date="2024-01-31",
    limit=10000,
    offset=10000
)

Requirements

• Python >= 3.7
• pandas >= 1.3.0
• numpy >= 1.21.0
• google-analytics-data >= 0.16.0

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please use the GitHub issue tracker.

Changelog

0.1.0 (2024-01-XX)

• Initial release
• Basic GA4 reporting functionality
• Support for custom dimensions and metrics
• Pandas DataFrame output