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#

bash

python ga_query.py --action list-properties

Realtime (active users)#

bash

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

Historical#

bash

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#

bash

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

Arguments#

Common#

ArgumentDescriptionDefault--property-idNumeric GA4 property IDRequired (except list-properties)--credentialsService account JSON pathga-credentials.json

Realtime#

ArgumentDescriptionDefault--metricsComma-separated metricsactiveUsers``--dimensionsComma-separated dimensions(none)--minute-rangeMinutes ago window, e.g. 0-30``0-30

Historical#

ArgumentDescriptionDefault--start-dateStart ( YYYY-MM-DD or relative)Required--end-dateEndRequired--metricsComma-separated metricsactiveUsers``--dimensionsComma-separated dimensions(none)--limitMax rows10000``--offsetPaging offset0

Common metrics#

NameMeaningactiveUsersActive userssessionsSessionseventCountEvent countengagementRateEngagement rateaverageSessionDurationAvg session duration (seconds)screenPageViewsPage / screen viewsconversionsConversionstotalRevenueRevenue

Common dimensions#

NameMeaningcountryCountrycityCitydeviceCategorydesktop / mobile / tableteventNameEvent namepagePathPage pathsourceTraffic sourcemediumMediumcampaignCampaigndateDate

Date expressions#

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

Output#

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

Dependencies#

bash

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