google-analytics

Google Analytics (GA4)

Google Analytics Data API を使用して、GA4 からレポートやインサイトを取得します。

前提条件

Google OAuth 認証情報が必要です。

• GOOGLE_CLIENT_ID
• GOOGLE_CLIENT_SECRET
• 有効な OAuth アクセストークン（必要に応じて更新）

認証情報は .env、.env.local、または ~/.claude/.env.global に設定してください。

アクセストークンの取得

# Step 1: Get authorization code (user must visit this URL in browser)
echo "https://accounts.google.com/o/oauth2/v2/auth?client_id=${GOOGLE_CLIENT_ID}&redirect_uri=urn:ietf:wg:oauth:2.0:oob&scope=https://www.googleapis.com/auth/analytics.readonly&response_type=code&access_type=offline"

# Step 2: Exchange code for tokens
curl -s -X POST "https://oauth2.googleapis.com/token" \
  -d "code={AUTH_CODE}" \
  -d "client_id=${GOOGLE_CLIENT_ID}" \
  -d "client_secret=${GOOGLE_CLIENT_SECRET}" \
  -d "redirect_uri=urn:ietf:wg:oauth:2.0:oob" \
  -d "grant_type=authorization_code"

# Step 3: Refresh an expired token
curl -s -X POST "https://oauth2.googleapis.com/token" \
  -d "refresh_token={REFRESH_TOKEN}" \
  -d "client_id=${GOOGLE_CLIENT_ID}" \
  -d "client_secret=${GOOGLE_CLIENT_SECRET}" \
  -d "grant_type=refresh_token"

リフレッシュトークンは安全に保管してください。アクセストークンの有効期限は 1 時間です。

GA4 プロパティ ID の確認

curl -s -H "Authorization: Bearer ${GA_ACCESS_TOKEN}" \
  "https://analyticsadmin.googleapis.com/v1beta/accountSummaries" \
  | python3 -c "
import json, sys
data = json.load(sys.stdin)
for acct in data.get('accountSummaries', []):
    for prop in acct.get('propertySummaries', []):
        print(f\"{prop['property']}  |  {prop.get('displayName','')}  |  Account: {acct.get('displayName','')}\")
"

プロパティ ID の形式は properties/XXXXXXXXX です。

---

API ベース

POST https://analyticsdata.googleapis.com/v1beta/{property_id}:runReport

すべてのレポートリクエストでは、JSON ボディを使用して POST します。必ず Authorization: Bearer {ACCESS_TOKEN} を含めてください。

---

1. トラフィック概要レポート

指定した期間のセッション数、ユーザー数、ページビュー数、エンゲージメント率を取得します。

curl の例

curl -s -X POST \
  "https://analyticsdata.googleapis.com/v1beta/properties/{PROPERTY_ID}:runReport" \
  -H "Authorization: Bearer ${GA_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}],
    "metrics": [
      {"name": "sessions"},
      {"name": "totalUsers"},
      {"name": "newUsers"},
      {"name": "screenPageViews"},
      {"name": "engagementRate"},
      {"name": "averageSessionDuration"},
      {"name": "bounceRate"}
    ]
  }'

日付範囲のショートカット

• today、yesterday
• 7daysAgo、14daysAgo、28daysAgo、30daysAgo、90daysAgo
• 特定の日付：2024-01-01
• 2 つの dateRanges を渡して期間を比較できます

---

2. ユーザー獲得レポート

ユーザーの流入元（チャネル、ソース、キャンペーン）を確認します。

curl -s -X POST \
  "https://analyticsdata.googleapis.com/v1beta/properties/{PROPERTY_ID}:runReport" \
  -H "Authorization: Bearer ${GA_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}],
    "dimensions": [
      {"name": "sessionDefaultChannelGroup"}
    ],
    "metrics": [
      {"name": "sessions"},
      {"name": "totalUsers"},
      {"name": "engagementRate"},
      {"name": "conversions"}
    ],
    "orderBys": [{"metric": {"metricName": "sessions"}, "desc": true}],
    "limit": 20
  }'

獲得分析に役立つディメンション

ディメンション	説明
sessionDefaultChannelGroup	チャネルグループ（Organic、Paid、Social など）
sessionSource	トラフィックソース（google、facebook など）
sessionMedium	メディア（organic、cpc、referral など）
sessionCampaignName	UTM キャンペーン名
firstUserSource	ファーストタッチのアトリビューションソース

---

3. 人気ページレポート

サイトで最もトラフィックの多いページを確認します。

curl -s -X POST \
  "https://analyticsdata.googleapis.com/v1beta/properties/{PROPERTY_ID}:runReport" \
  -H "Authorization: Bearer ${GA_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}],
    "dimensions": [
      {"name": "pagePath"}
    ],
    "metrics": [
      {"name": "screenPageViews"},
      {"name": "totalUsers"},
      {"name": "engagementRate"},
      {"name": "averageSessionDuration"}
    ],
    "orderBys": [{"metric": {"metricName": "screenPageViews"}, "desc": true}],
    "limit": 25
  }'

---

4. エンゲージメント指標

ユーザーがコンテンツをどのように利用しているかを把握します。

curl -s -X POST \
  "https://analyticsdata.googleapis.com/v1beta/properties/{PROPERTY_ID}:runReport" \
  -H "Authorization: Bearer ${GA_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}],
    "dimensions": [
      {"name": "pagePath"}
    ],
    "metrics": [
      {"name": "engagedSessions"},
      {"name": "engagementRate"},
      {"name": "averageSessionDuration"},
      {"name": "screenPageViewsPerSession"},
      {"name": "eventCount"}
    ],
    "orderBys": [{"metric": {"metricName": "engagedSessions"}, "desc": true}],
    "limit": 20
  }'

主なエンゲージメント指標

指標	測定内容
engagementRate	エンゲージメントのあったセッション（10 秒超、2 ページ以上、またはコンバージョン）の割合
averageSessionDuration	セッション時間の平均（秒）
screenPageViewsPerSession	セッションあたりのページ数
bounceRate	エンゲージメントのなかったセッションの割合
eventCount	発生したイベントの合計数

---

5. コンバージョンのトラッキング

コンバージョンイベント（購入、登録など）のレポートを作成します。

curl -s -X POST \
  "https://analyticsdata.googleapis.com/v1beta/properties/{PROPERTY_ID}:runReport" \
  -H "Authorization: Bearer ${GA_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}],
    "dimensions": [
      {"name": "eventName"}
    ],
    "metrics": [
      {"name": "eventCount"},
      {"name": "totalUsers"},
      {"name": "eventValue"}
    ],
    "dimensionFilter": {
      "filter": {
        "fieldName": "eventName",
        "inListFilter": {
          "values": ["purchase", "sign_up", "generate_lead", "begin_checkout"]
        }
      }
    }
  }'

チャネル別コンバージョン

curl -s -X POST \
  "https://analyticsdata.googleapis.com/v1beta/properties/{PROPERTY_ID}:runReport" \
  -H "Authorization: Bearer ${GA_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}],
    "dimensions": [
      {"name": "sessionDefaultChannelGroup"}
    ],
    "metrics": [
      {"name": "sessions"},
      {"name": "conversions"},
      {"name": "totalRevenue"}
    ],
    "orderBys": [{"metric": {"metricName": "conversions"}, "desc": true}]
  }'

---

6. オーディエンスセグメント

デバイス、地域、属性ごとにトラフィックを分類します。

デバイスカテゴリ別

curl -s -X POST \
  "https://analyticsdata.googleapis.com/v1beta/properties/{PROPERTY_ID}:runReport" \
  -H "Authorization: Bearer ${GA_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}],
    "dimensions": [{"name": "deviceCategory"}],
    "metrics": [
      {"name": "sessions"},
      {"name": "totalUsers"},
      {"name": "engagementRate"},
      {"name": "conversions"}
    ]
  }'

国別

ディメンションの deviceCategory を country に置き換えます。

ランディングページとソース別

curl -s -X POST \
  "https://analyticsdata.googleapis.com/v1beta/properties/{PROPERTY_ID}:runReport" \
  -H "Authorization: Bearer ${GA_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}],
    "dimensions": [
      {"name": "landingPage"},
      {"name": "sessionSource"}
    ],
    "metrics": [
      {"name": "sessions"},
      {"name": "engagementRate"},
      {"name": "conversions"}
    ],
    "orderBys": [{"metric": {"metricName": "sessions"}, "desc": true}],
    "limit": 30
  }'

---

7. 期間比較

2 つの期間を比較して傾向を把握します。

curl -s -X POST \
  "https://analyticsdata.googleapis.com/v1beta/properties/{PROPERTY_ID}:runReport" \
  -H "Authorization: Bearer ${GA_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "dateRanges": [
      {"startDate": "30daysAgo", "endDate": "today", "name": "current"},
      {"startDate": "60daysAgo", "endDate": "31daysAgo", "name": "previous"}
    ],
    "metrics": [
      {"name": "sessions"},
      {"name": "totalUsers"},
      {"name": "conversions"},
      {"name": "engagementRate"}
    ]
  }'

---

レスポンスの解析

GA4 API は JSON を返します。python3 または jq で解析してください。

# Parse report into a table
curl -s -X POST "..." | python3 -c "
import json, sys
data = json.load(sys.stdin)
headers = [h['name'] for h in data.get('dimensionHeaders',[])] + [m['name'] for m in data.get('metricHeaders',[])]
print(' | '.join(headers))
print('-' * (len(headers) * 20))
for row in data.get('rows', []):
    dims = [d['value'] for d in row.get('dimensionValues',[])]
    mets = [m['value'] for m in row.get('metricValues',[])]
    print(' | '.join(dims + mets))
"

---

ワークフロー：月次分析レポート

月次レポートを依頼された場合：

1. 期間比較を含むトラフィック概要（セッション数、ユーザー数、ページビュー数）を取得します
2. チャネル別の獲得内訳を取得します
3. ページビュー数上位 20 ページを取得します
4. チャネル別のコンバージョン概要を取得します
5. デバイス別および国別の内訳を取得します

表、傾向（上向き／下向きの矢印）、推奨事項を含む構造化レポートとして提示します。

## Monthly Analytics Report: {Property Name}
### Period: {date range} vs {previous period}

### Traffic Summary
| Metric | Current | Previous | Change |
|--------|---------|----------|--------|
| Sessions | X | Y | +Z% |
| ...

### Top Channels
...

### Top Pages
...

### Conversion Summary
...

### Recommendations
- [Based on data patterns]

よくある問題

• 403 Forbidden：ユーザーに GA4 プロパティへのアクセス権がありません
• 空の行：指定した日付範囲またはフィルターに該当するデータがありません
• クォータ超過：GA4 API には 1 日あたりのクォータがあります。日付範囲を短くするか、リクエストをまとめてください
• プロパティが見つからない：プロパティ ID の形式（properties/XXXXXXXXX）を確認してください