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

Realtime

Historical

Common metrics

Common dimensions

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