google-analytics-cli

Google Analytics CLI スキル

GA4 API 用の読み取り専用 CLI、google-analytics-cli を利用できます。レポートの実行、リアルタイムのアクティビティの監視、アカウントやプロパティの構造の確認に使用します。

クイックスタート

# Check if the CLI is available
google-analytics-cli --help

# List accounts and properties
google-analytics-cli accounts

CLI がインストールされていない場合は、インストールします。

npm install -g google-analytics-cli

認証

CLI では Google サービスアカウントの認証情報を使用します。認証情報は次の順に解決されます。

1. --credentials <path> フラグ（コマンドごと）
2. --profile <name> フラグまたは GA_PROFILE 環境変数 → ~/.config/google-analytics-cli/profiles/<name>.json
3. GOOGLE_APPLICATION_CREDENTIALS 環境変数
4. ~/.config/google-analytics-cli/credentials.json（自動検出）
5. gcloud Application Default Credentials

コマンドを実行する前に、google-analytics-cli accounts を実行して認証情報を確認してください。失敗した場合は、サービスアカウントを設定し、Google Analytics で閲覧者アクセス権を付与するようユーザーに依頼してください。

ユーザーが複数の GA アカウント（複数のクライアントや組織など）を管理している場合は、google-analytics-cli profiles を実行して利用可能なプロファイルを一覧表示し、--profile <name>（例：accounts --profile account-a）を指定して対象を選択します。--credentials と --profile は同時に使用できません。--credentials は GA_PROFILE より優先されます。

プロパティ ID

ほとんどのコマンドでは GA4 プロパティ ID が必要です。次の方法で指定できます。

• 位置引数：google-analytics-cli report 123456789 ...
• --property フラグ：google-analytics-cli report --property 123456789 ...
• GA_PROPERTY_ID 環境変数：export GA_PROPERTY_ID=123456789

数値のみの形式（123456789）と、接頭辞付きの形式（properties/123456789）のどちらも使用できます。

出力形式

すべてのコマンドは、デフォルトで整形済み JSON を出力します。1 行の JSON を出力するには --format compact を使用します。

管理コマンド

# List all accounts and their properties
google-analytics-cli accounts

# Get details about a specific property
google-analytics-cli property 123456789

# List properties for an account
google-analytics-cli properties 987654321
google-analytics-cli properties 987654321 --show-deleted

# List data streams for a property
google-analytics-cli data-streams 123456789

# List key events (conversions) for a property
google-analytics-cli key-events 123456789

# List custom dimensions for a property (Admin API)
google-analytics-cli admin-custom-dimensions 123456789

# List custom metrics for a property (Admin API)
google-analytics-cli admin-custom-metrics 123456789

# Get data retention settings for a property
google-analytics-cli data-retention 123456789

# List Google Ads links for a property
google-analytics-cli ads-links 123456789

# List annotations for a property (alpha API)
google-analytics-cli annotations 123456789

# Get custom dimensions and metrics for a property (Data API, filters by customDefinition)
google-analytics-cli custom-dims 123456789

# List configured credentials profiles (for users with multiple GA accounts)
google-analytics-cli profiles

変更履歴

アカウントの変更履歴イベントを検索します。

google-analytics-cli change-history 987654321
google-analytics-cli change-history 987654321 --filter-property 123456789
google-analytics-cli change-history 987654321 --earliest-change-time 2026-01-01T00:00:00Z
google-analytics-cli change-history 987654321 --earliest-change-time 2026-01-01T00:00:00Z --latest-change-time 2026-03-01T00:00:00Z
google-analytics-cli change-history 987654321 --actor-email [email protected]
google-analytics-cli change-history 987654321 --resource-type '["PROPERTY","DATA_STREAM"]'
google-analytics-cli change-history 987654321 --action '["CREATED","UPDATED"]'

アクセスレポート

プロパティにアクセスしたユーザーを確認するため、アクセスレポートを実行します。

google-analytics-cli access-report 123456789 \
  --dimensions "accessorEmail,accessMechanism" \
  --metrics "accessCount" \
  --date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday"}]'

オプション：--dimension-filter、--metric-filter、--order-by、--limit、--offset、--time-zone、--return-entity-quota、--include-all-users、--expand-groups。

注：アクセスレポートでは内部的に name ではなく dimensionName／metricName を、property ではなく entity を使用します。

レポートの実行

report コマンドは GA4 Data API のレポートを実行します。

google-analytics-cli report <property_id> \
  --dimensions "<comma-separated>" \
  --metrics "<comma-separated>" \
  --date-ranges '<JSON array>' \
  [--dimension-filter '<JSON>'] \
  [--metric-filter '<JSON>'] \
  [--order-by '<JSON array>'] \
  [--limit <n>] \
  [--offset <n>] \
  [--currency-code <ISO4217>] \
  [--keep-empty-rows] \
  [--return-property-quota]

必須オプション：--dimensions、--metrics、--date-ranges。

日付範囲

--date-ranges オプションには、日付範囲オブジェクトの JSON 配列を指定します。

# Relative dates
--date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday"}]'

# Absolute dates
--date-ranges '[{"startDate": "2026-01-01", "endDate": "2026-01-31"}]'

# Compare two periods
--date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday", "name": "current"}, {"startDate": "60daysAgo", "endDate": "31daysAgo", "name": "previous"}]'

有効な日付の値：

• 絶対日付：YYYY-MM-DD（例：2026-01-01）
• 相対日付：NdaysAgo（例：30daysAgo、7daysAgo）
• 特殊な値：yesterday、today
• 1 回のリクエストで指定できる日付範囲は最大 4 つ です

ディメンションフィルター

--dimension-filter オプションには JSON の FilterExpression を指定します。

# Exact match
--dimension-filter '{"filter": {"fieldName": "country", "stringFilter": {"matchType": "EXACT", "value": "United States"}}}'

# Contains
--dimension-filter '{"filter": {"fieldName": "pagePath", "stringFilter": {"matchType": "CONTAINS", "value": "/blog"}}}'

# Regex
--dimension-filter '{"filter": {"fieldName": "pagePath", "stringFilter": {"matchType": "PARTIAL_REGEXP", "value": "^/products/[0-9]+"}}}'

# In list
--dimension-filter '{"filter": {"fieldName": "eventName", "inListFilter": {"values": ["page_view", "scroll", "click"]}}}'

# AND group
--dimension-filter '{"andGroup": {"expressions": [{"filter": {"fieldName": "country", "stringFilter": {"matchType": "EXACT", "value": "United States"}}}, {"filter": {"fieldName": "deviceCategory", "stringFilter": {"matchType": "EXACT", "value": "mobile"}}}]}}'

# OR group
--dimension-filter '{"orGroup": {"expressions": [{"filter": {"fieldName": "country", "stringFilter": {"matchType": "EXACT", "value": "United States"}}}, {"filter": {"fieldName": "country", "stringFilter": {"matchType": "EXACT", "value": "Canada"}}}]}}'

# NOT
--dimension-filter '{"notExpression": {"filter": {"fieldName": "pagePath", "stringFilter": {"matchType": "EXACT", "value": "/"}}}}'

StringFilter の matchType 値：EXACT、BEGINS_WITH、ENDS_WITH、CONTAINS、FULL_REGEXP、PARTIAL_REGEXP。

指標フィルター

--metric-filter オプションには、数値フィルターを含む同じ FilterExpression 構造を指定します。

# Greater than
--metric-filter '{"filter": {"fieldName": "sessions", "numericFilter": {"operation": "GREATER_THAN", "value": {"int64Value": "100"}}}}'

# Between
--metric-filter '{"filter": {"fieldName": "bounceRate", "betweenFilter": {"fromValue": {"doubleValue": 0.5}, "toValue": {"doubleValue": 0.9}}}}'

NumericFilter の演算子：EQUAL、LESS_THAN、LESS_THAN_OR_EQUAL、GREATER_THAN、GREATER_THAN_OR_EQUAL。

NumericValue：整数には {"int64Value": "string"}、小数には {"doubleValue": number} を使用します。

並べ替え

--order-by オプションには JSON 配列を指定します。

# By metric descending
--order-by '[{"metric": {"metricName": "sessions"}, "desc": true}]'

# By dimension alphabetically
--order-by '[{"dimension": {"dimensionName": "date", "orderType": "ALPHANUMERIC"}}]'

# Multiple sort keys
--order-by '[{"metric": {"metricName": "sessions"}, "desc": true}, {"dimension": {"dimensionName": "country"}}]'

DimensionOrderBy の orderType 値：ALPHANUMERIC、CASE_INSENSITIVE_ALPHANUMERIC、NUMERIC。

ピボットレポート

クロス集計分析用のピボットレポートを実行します。

google-analytics-cli pivot-report 123456789 \
  --dimensions "country,browser" \
  --metrics "sessions,activeUsers" \
  --date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday"}]' \
  --pivots '[{"fieldNames": ["browser"], "limit": 5, "orderBys": [{"metric": {"metricName": "sessions"}, "desc": true}]}]'

オプション：--dimension-filter、--metric-filter、--currency-code、--keep-empty-rows、--return-property-quota。

バッチレポート

1 回のリクエストで最大 5 件のレポートを実行します。

google-analytics-cli batch-report 123456789 \
  --requests '[{"dimensions": [{"name": "date"}], "metrics": [{"name": "activeUsers"}], "dateRanges": [{"startDate": "7daysAgo", "endDate": "yesterday"}]}, {"dimensions": [{"name": "country"}], "metrics": [{"name": "sessions"}], "dateRanges": [{"startDate": "7daysAgo", "endDate": "yesterday"}]}]'

メタデータと互換性

# Get full metadata (all available dimensions and metrics)
google-analytics-cli metadata 123456789

# Check if dimensions and metrics are compatible
google-analytics-cli check-compatibility 123456789 \
  --dimensions "date,country" \
  --metrics "sessions,activeUsers"

オプション：--dimension-filter、--metric-filter（report と同じ FilterExpression 形式）。

オーディエンスのエクスポート

# Create an audience export
google-analytics-cli audience-export-create 123456789 \
  --audience "properties/123456789/audiences/456" \
  --dimensions "deviceId,userId"

# Get status of an audience export
google-analytics-cli audience-export properties/123456789/audienceExports/789

# List all audience exports
google-analytics-cli audience-exports 123456789

# Query rows from a completed audience export
google-analytics-cli audience-export-query properties/123456789/audienceExports/789 \
  --limit 1000 --offset 0

リアルタイムレポート

realtime コマンドは現在のアクティビティを監視します。日付範囲と通貨コードは不要です。

google-analytics-cli realtime <property_id> \
  --dimensions "<comma-separated>" \
  --metrics "<comma-separated>" \
  [--dimension-filter '<JSON>'] \
  [--metric-filter '<JSON>'] \
  [--order-by '<JSON array>'] \
  [--limit <n>] \
  [--return-property-quota]

リアルタイムレポートの対象は、過去 30 分間 のアクティビティです。

リアルタイムのディメンション（限定セット）

appVersion、audienceId、audienceName、audienceResourceName、city、cityId、country、countryId、deviceCategory、eventName、minutesAgo、platform、streamId、streamName、unifiedScreenName

注：minutesAgo は現在の分が "00"、1 分前が "01" となり、最大 "29" です。

リアルタイムの指標（4 つのみ）

activeUsers、eventCount、keyEvents、screenPageViews

よく使うディメンションのリファレンス

トラフィックソース（セッション単位）： sessionSource、sessionMedium、sessionSourceMedium、sessionDefaultChannelGroup、sessionCampaignName、sessionCampaignId

トラフィックソース（初回ユーザーの獲得）： firstUserSource、firstUserMedium、firstUserSourceMedium、firstUserDefaultChannelGroup、firstUserCampaignName

ページ／画面： pagePath、pageTitle、pagePathPlusQueryString、landingPage、landingPagePlusQueryString、hostName、fullPageUrl、contentGroup

イベント： eventName、isKeyEvent

ユーザー： newVsReturning、userAgeBracket、userGender、firstSessionDate

地域： country、countryId、city、cityId、region、continent、language

デバイス： deviceCategory、browser、operatingSystem、operatingSystemVersion、screenResolution、mobileDeviceBranding、platform

時間： date、dateHour、day、dayOfWeek、dayOfWeekName、hour、month、week、year、yearMonth、nthDay

E コマース： transactionId、itemName、itemId、itemCategory、itemBrand、itemVariant、orderCoupon

Google Ads： sessionGoogleAdsCampaignName、sessionGoogleAdsAdGroupName、sessionGoogleAdsKeyword、sessionGoogleAdsAdNetworkType、googleAdsAccountName

オーディエンス： audienceId、audienceName

カスタムディメンション： customEvent:parameter_name（イベント単位）、customUser:parameter_name（ユーザー単位）、customItem:parameter_name（アイテム単位）

よく使う指標のリファレンス

ユーザー： activeUsers、newUsers、totalUsers

セッション： sessions、sessionsPerUser、averageSessionDuration、bounceRate

エンゲージメント： engagedSessions、engagementRate、screenPageViews、screenPageViewsPerSession、screenPageViewsPerUser、userEngagementDuration

イベント： eventCount、eventCountPerUser、eventValue、eventsPerSession

キーイベント（コンバージョン）： keyEvents、sessionKeyEventRate、userKeyEventRate

E コマース／収益： ecommercePurchases、purchaseRevenue、totalRevenue、transactions、averagePurchaseRevenue、averageRevenuePerUser、itemRevenue、addToCarts、checkouts、cartToViewRate

広告： advertiserAdClicks、advertiserAdCost、advertiserAdCostPerClick、advertiserAdImpressions、returnOnAdSpend

カスタム指標： customEvent:parameter_name（合計）、averageCustomEvent:parameter_name（平均）、countCustomEvent:parameter_name（件数）

レポート例

トラフィックの概要（過去 30 日間）：

google-analytics-cli report 123456789 \
  --dimensions "sessionDefaultChannelGroup" \
  --metrics "sessions,activeUsers,engagementRate,keyEvents,totalRevenue" \
  --date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday"}]' \
  --order-by '[{"metric": {"metricName": "sessions"}, "desc": true}]'

閲覧数の多いページ：

google-analytics-cli report 123456789 \
  --dimensions "pagePath" \
  --metrics "screenPageViews,activeUsers,averageSessionDuration,bounceRate" \
  --date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday"}]' \
  --order-by '[{"metric": {"metricName": "screenPageViews"}, "desc": true}]' \
  --limit 20

日別の推移：

google-analytics-cli report 123456789 \
  --dimensions "date" \
  --metrics "activeUsers,sessions,screenPageViews,keyEvents" \
  --date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday"}]' \
  --order-by '[{"dimension": {"dimensionName": "date"}}]'

トラフィックソースの内訳：

google-analytics-cli report 123456789 \
  --dimensions "sessionSource,sessionMedium" \
  --metrics "sessions,activeUsers,engagementRate,bounceRate,keyEvents" \
  --date-ranges '[{"startDate": "7daysAgo", "endDate": "yesterday"}]' \
  --order-by '[{"metric": {"metricName": "sessions"}, "desc": true}]' \
  --limit 20

ランディングページのパフォーマンス：

google-analytics-cli report 123456789 \
  --dimensions "landingPage" \
  --metrics "sessions,activeUsers,bounceRate,keyEvents,averageSessionDuration" \
  --date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday"}]' \
  --order-by '[{"metric": {"metricName": "sessions"}, "desc": true}]' \
  --limit 20

デバイスの内訳：

google-analytics-cli report 123456789 \
  --dimensions "deviceCategory" \
  --metrics "activeUsers,sessions,engagementRate,bounceRate,screenPageViews" \
  --date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday"}]'

地域：

google-analytics-cli report 123456789 \
  --dimensions "country" \
  --metrics "activeUsers,sessions,engagementRate,keyEvents" \
  --date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday"}]' \
  --order-by '[{"metric": {"metricName": "activeUsers"}, "desc": true}]' \
  --limit 20

イベント分析：

google-analytics-cli report 123456789 \
  --dimensions "eventName" \
  --metrics "eventCount,eventCountPerUser,eventValue" \
  --date-ranges '[{"startDate": "7daysAgo", "endDate": "yesterday"}]' \
  --order-by '[{"metric": {"metricName": "eventCount"}, "desc": true}]' \
  --limit 20

期間比較：

google-analytics-cli report 123456789 \
  --dimensions "sessionDefaultChannelGroup" \
  --metrics "sessions,activeUsers,keyEvents" \
  --date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday", "name": "current"}, {"startDate": "60daysAgo", "endDate": "31daysAgo", "name": "previous"}]' \
  --order-by '[{"metric": {"metricName": "sessions"}, "desc": true}]'

E コマースのパフォーマンス：

google-analytics-cli report 123456789 \
  --dimensions "itemName" \
  --metrics "itemRevenue,itemsPurchased,addToCarts,cartToViewRate" \
  --date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday"}]' \
  --order-by '[{"metric": {"metricName": "itemRevenue"}, "desc": true}]' \
  --limit 20

新規ユーザーとリピーター：

google-analytics-cli report 123456789 \
  --dimensions "newVsReturning" \
  --metrics "activeUsers,sessions,engagementRate,screenPageViews,keyEvents" \
  --date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday"}]'

ユーザー獲得（初回接点）：

google-analytics-cli report 123456789 \
  --dimensions "firstUserDefaultChannelGroup" \
  --metrics "newUsers,activeUsers,sessions,keyEvents,totalRevenue" \
  --date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday"}]' \
  --order-by '[{"metric": {"metricName": "newUsers"}, "desc": true}]'

キャンペーン（UTM）のパフォーマンス：

google-analytics-cli report 123456789 \
  --dimensions "sessionCampaignName,sessionSourceMedium" \
  --metrics "sessions,activeUsers,engagementRate,keyEvents,totalRevenue" \
  --date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday"}]' \
  --order-by '[{"metric": {"metricName": "sessions"}, "desc": true}]' \
  --limit 20

Google Ads キャンペーンのパフォーマンス：

google-analytics-cli report 123456789 \
  --dimensions "sessionGoogleAdsCampaignName" \
  --metrics "sessions,keyEvents,advertiserAdCost,advertiserAdClicks,returnOnAdSpend" \
  --date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday"}]' \
  --order-by '[{"metric": {"metricName": "advertiserAdCost"}, "desc": true}]'

フィルター済みレポート（ブログページのみ、米国のモバイルユーザー）：

google-analytics-cli report 123456789 \
  --dimensions "pagePath" \
  --metrics "screenPageViews,activeUsers,engagementRate" \
  --date-ranges '[{"startDate": "30daysAgo", "endDate": "yesterday"}]' \
  --dimension-filter '{"andGroup": {"expressions": [{"filter": {"fieldName": "pagePath", "stringFilter": {"matchType": "BEGINS_WITH", "value": "/blog"}}}, {"filter": {"fieldName": "country", "stringFilter": {"matchType": "EXACT", "value": "United States"}}}, {"filter": {"fieldName": "deviceCategory", "stringFilter": {"matchType": "EXACT", "value": "mobile"}}}]}}' \
  --order-by '[{"metric": {"metricName": "screenPageViews"}, "desc": true}]' \
  --limit 20

リアルタイム -- 国別のアクティブユーザー：

google-analytics-cli realtime 123456789 \
  --dimensions "country" \
  --metrics "activeUsers" \
  --order-by '[{"metric": {"metricName": "activeUsers"}, "desc": true}]'

リアルタイム -- アクティブなページ：

google-analytics-cli realtime 123456789 \
  --dimensions "unifiedScreenName" \
  --metrics "activeUsers,screenPageViews" \
  --order-by '[{"metric": {"metricName": "activeUsers"}, "desc": true}]' \
  --limit 10

重要なルール

1. ディメンションと指標の互換性。 すべてのディメンションと指標を組み合わせて使えるわけではありません。互換性エラーが発生した場合は、ディメンションの数を減らすか、別の組み合わせを試してください。レポートを実行する前に check-compatibility コマンドでテストするか、metadata を使って利用可能なすべてのディメンションと指標を確認してください。

2. 1 回のレポートリクエストで指定できるディメンションは最大 9 個です。

3. 1 回のレポートリクエストで指定できる日付範囲は最大 4 個です。

4. レスポンスの上限は 250,000 行です。ページネーションには --offset と --limit を使用してください。

5. リアルタイムデータには制限があります。使用できるのはディメンション 15 個、指標 4 個のみです。日付範囲、通貨コード、オフセットは指定できません。直近 30 分間のデータが対象です。

6. しきい値が適用されるディメンション。 userAgeBracket、userGender、audienceId／audienceName では、行数が少ない場合、プライバシー保護のため、しきい値が適用された（サンプリング済みの）データが返されることがあります。

7. 割り当て量。 現在の割り当て量の状況を確認するには、--return-property-quota を使用してください。標準プロパティには 1 日あたり 200,000 トークンが割り当てられます。

8. フィルターの対象。 --dimension-filter で指定できるのはディメンションのフィールド名のみです。--metric-filter で指定できるのは指標のフィールド名のみです。これらは API によって個別に適用されます。

9. バッチレポート。 1 回のバッチリクエストに含められるレポートオブジェクトは最大 5 個です。

10. オーディエンスのエクスポート。 エクスポートを作成すると、長時間実行されるオペレーションが返されます。状態が ACTIVE になるまで audience-export でポーリングし、その後 audience-export-query で行をクエリしてください。

ワークフローのガイダンス

概要

1. google-analytics-cli accounts を実行してプロパティを確認します
2. sessionDefaultChannelGroup と主要な指標を使ってトラフィック概要レポートを実行します
3. 日単位の日付ディメンションを使って傾向を提示します

詳細分析

1. 広い範囲から始めます。トラフィックチャネルと主要指標を確認します
2. 詳細を調べます。パフォーマンスの低い特定のページ、イベント、流入元を確認します
3. 期間を比較して傾向を特定します
4. デバイスや地域ごとの内訳を確認し、セグメント固有の問題を調べます
5. --dimension-filter を使って特定のセグメントに絞り込みます

プロパティの確認

1. google-analytics-cli properties <account_id> を実行してすべてのプロパティを確認します
2. google-analytics-cli data-streams <property_id> を実行してデータストリームを確認します
3. google-analytics-cli key-events <property_id> を実行して設定済みのコンバージョンを確認します
4. google-analytics-cli metadata <property_id> を実行して利用可能なすべてのディメンションと指標を確認します
5. 複雑なレポートを作成する前に、google-analytics-cli check-compatibility <property_id> を実行します

エラー処理

• 権限が拒否されました -- サービスアカウントに Google Analytics の閲覧者権限が必要です
• 互換性のないディメンション／指標 -- check-compatibility でテストし、ディメンションの数を減らすか、別の組み合わせを試してください
• 結果が空です -- プロパティ ID、日付範囲、および該当するディメンションのデータが存在するかを確認してください
• 割り当て量を超えました -- --return-property-quota で使用状況を確認し、リクエストの頻度または複雑さを減らしてください

API ドキュメントの参照先

• google-analytics-cli のドキュメント
• GA4 Data API の概要
• ディメンションと指標のリファレンス
• Realtime API スキーマ
• FilterExpression のリファレンス
• OrderBy のリファレンス
• 割り当て量と制限
• GA4 Admin API