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
- Open Google Cloud Console.
- Create or select a project.
- Enable Google Analytics Data API.
- Create a service account: IAM & Admin → Service Accounts → Create service account.
- Optional GCP role: BigQuery Job User (only if you also use BigQuery).
- Finish the wizard.
2. Create a JSON key
- Open the service account → Keys.
- Add key → Create new key → JSON.
- Download the file and save it as
ga-credentials.json(or any path you pass via--credentials/GOOGLE_APPLICATION_CREDENTIALS).
3. Grant GA4 access
- Open Google Analytics.
- Select the property.
- Admin (gear) → Property access management.
- Add users → enter the service account email (
…@….iam.gserviceaccount.com). - Role: at least Viewer.
4. Credentials location
Either:
- A. Place
ga-credentials.jsonin this skill directory, or - B. Set
GOOGLE_APPLICATION_CREDENTIALSto 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-propertiesRealtime (active users)
python ga_query.py --action realtime \
--property-id YOUR-GA4-PROPERTY-IDHistorical
python ga_query.py --action historical \
--property-id YOUR-GA4-PROPERTY-ID \
--start-date 7daysAgo \
--end-date yesterday \
--metrics activeUsers,sessions,eventCount \
--dimensions country,deviceCategoryMetadata
python ga_query.py --action metadata \
--property-id YOUR-GA4-PROPERTY-IDArguments
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-dataOptional (traffic source report + DingTalk): pip install requests and set DINGTALK_WEBHOOK / DINGTALK_SECRET.