🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
BytesAgain β€Ί Skills β€Ί Google-analytics-GA4
πŸ¦€ ClawHub

Google-analytics-GA4

by @whosc

Query Google Analytics GA4 properties for realtime and historical user metrics, dimensions, and metadata using the official Data API.

Versionv1.0.0
Downloads740
Stars⭐ 1
#database#data#legal
TERMINAL
clawhub install google-analytics-ga4

πŸ“– About This Skill

Google Analytics skill

Query GA4 properties using the Google Analytics Data API v1.

Capabilities

  • Realtime metrics β€” e.g. active users in the last N minutes
  • Historical reports β€” custom date ranges, metrics, dimensions, paging
  • Metadata β€” discover valid dimension and metric API names
  • Property list hint β€” Data API alone cannot enumerate properties; doc explains where to find the numeric ID

    • Setup

    1. Create a service account

    1. Open Google Cloud Console. 2. Create or select a project. 3. Enable Google Analytics Data API. 4. Create a service account: IAM & Admin β†’ Service Accounts β†’ Create service account. - Optional GCP role: BigQuery Job User (only if you also use BigQuery). 5. Finish the wizard.

    2. Create a JSON key

    1. Open the service account β†’ Keys. 2. Add key β†’ Create new key β†’ JSON. 3. Download the file and save it as ga-credentials.json (or any path you pass via --credentials / GOOGLE_APPLICATION_CREDENTIALS).

    3. Grant GA4 access

    1. Open Google Analytics. 2. Select the property. 3. Admin (gear) β†’ Property access management. 4. Add users β†’ enter the service account email (…@….iam.gserviceaccount.com). 5. Role: at least Viewer.

    4. Credentials location

    Either:

  • A. Place ga-credentials.json in this skill directory, or
  • B. Set GOOGLE_APPLICATION_CREDENTIALS to the absolute path of the JSON key.

    • Never commit real keys. .gitignore excludes ga-credentials.json and config.json.

    Examples

    Property list guidance

    python ga_query.py --action list-properties

    Realtime (active users)

    python ga_query.py --action realtime \
  --property-id YOUR-GA4-PROPERTY-ID

    Historical

    python ga_query.py --action historical \
  --property-id YOUR-GA4-PROPERTY-ID \
  --start-date 7daysAgo \
  --end-date yesterday \
  --metrics activeUsers,sessions,eventCount \
  --dimensions country,deviceCategory

    Metadata

    python ga_query.py --action metadata \
  --property-id YOUR-GA4-PROPERTY-ID

    Arguments

    Common

    | Argument | Description | Default | |----------|-------------|---------| | --property-id | Numeric GA4 property ID | Required (except list-properties) | | --credentials | Service account JSON path | ga-credentials.json |

    Realtime

    | Argument | Description | Default | |----------|-------------|---------| | --metrics | Comma-separated metrics | activeUsers | | --dimensions | Comma-separated dimensions | (none) | | --minute-range | Minutes ago window, e.g. 0-30 | 0-30 |

    Historical

    | Argument | Description | Default | |----------|-------------|---------| | --start-date | Start (YYYY-MM-DD or relative) | Required | | --end-date | End | Required | | --metrics | Comma-separated metrics | activeUsers | | --dimensions | Comma-separated dimensions | (none) | | --limit | Max rows | 10000 | | --offset | Paging offset | 0 |

    Common metrics

    | Name | Meaning | |------|------------------------------------------------------| | activeUsers | Active users | | sessions | Sessions | | eventCount | Event count | | engagementRate | Engagement rate | | averageSessionDuration | Avg session duration (seconds) | | screenPageViews | Page / screen views | | conversions | Conversions | | totalRevenue | Revenue |

    Common dimensions

    | Name | Meaning | |------|---------| | country | Country | | city | City | | deviceCategory | desktop / mobile / tablet | | eventName | Event name | | pagePath | Page path | | source | Traffic source | | medium | Medium | | campaign | Campaign | | date | Date |

    Date expressions

  • Absolute: 2024-01-15
  • Relative: today, yesterday, 7daysAgo, 30daysAgo

    • Output

    Default: Markdown tables. Use --output json for machine-readable output.

    Dependencies

    pip install google-analytics-data

    Optional (traffic source report + DingTalk): pip install requests and set DINGTALK_WEBHOOK / DINGTALK_SECRET.

    References

  • Data API docs
  • Python client
  • Dimensions & metrics schema

    • πŸ’‘ Examples

    Property list guidance

    python ga_query.py --action list-properties

    Realtime (active users)

    python ga_query.py --action realtime \
  --property-id YOUR-GA4-PROPERTY-ID

    Historical

    python ga_query.py --action historical \
  --property-id YOUR-GA4-PROPERTY-ID \
  --start-date 7daysAgo \
  --end-date yesterday \
  --metrics activeUsers,sessions,eventCount \
  --dimensions country,deviceCategory

    Metadata

    python ga_query.py --action metadata \
  --property-id YOUR-GA4-PROPERTY-ID

    βš™οΈ Configuration

    1. Create a service account

    1. Open Google Cloud Console. 2. Create or select a project. 3. Enable Google Analytics Data API. 4. Create a service account: IAM & Admin β†’ Service Accounts β†’ Create service account. - Optional GCP role: BigQuery Job User (only if you also use BigQuery). 5. Finish the wizard.

    2. Create a JSON key

    1. Open the service account β†’ Keys. 2. Add key β†’ Create new key β†’ JSON. 3. Download the file and save it as ga-credentials.json (or any path you pass via --credentials / GOOGLE_APPLICATION_CREDENTIALS).

    3. Grant GA4 access

    1. Open Google Analytics. 2. Select the property. 3. Admin (gear) β†’ Property access management. 4. Add users β†’ enter the service account email (…@….iam.gserviceaccount.com). 5. Role: at least Viewer.

    4. Credentials location

    Either:

  • A. Place ga-credentials.json in this skill directory, or
  • B. Set GOOGLE_APPLICATION_CREDENTIALS to the absolute path of the JSON key.

    • Never commit real keys. .gitignore excludes ga-credentials.json and config.json.