YouTube Analytics API
セットアップ手順

00全体像

YouTube Analytics API はサービスアカウント非対応で、チャンネルオーナーの OAuth 同意が必須。なので「チャンネルごとに refresh token を1個作って、Bitwarden で共有」する設計にしている。

AOAuth クライアントを作る（mocha全体で1回）

1. Google Cloud Console で mocha-official プロジェクトを開く
2. 「APIとサービス」→ YouTube Analytics API と YouTube Data API v3 を両方有効化
3. 「認証情報」→「認証情報を作成」→「OAuth クライアント ID」
4. アプリケーションの種類: デスクトップアプリ を選択
5. JSON をダウンロードして credentials/client_secret.json として保存
6. Bitwarden の mocha 共有 Vault にアップロード（タイトル例: insight-analysis-pro / client_secret.json）

Bチャンネルを認証する（チャンネルオーナーが1回）

新しいチャンネルを追加するたびに、そのチャンネルのオーナー（or 管理者）権限を持つ Google アカウントで認証する。

1. リポジトリと依存をセットアップ

git clone git@github.com:mochainc/insight-analysis-pro.git
cd insight-analysis-pro
pip install -r requirements.txt

2. Bitwarden から OAuth クライアント JSON を配置

mkdir -p credentials
# Bitwarden の "insight-analysis-pro / client_secret.json" を
# credentials/client_secret.json として保存

3. 認証を実行

ブラウザが自動で開くので、そのチャンネルのオーナー Google アカウントでログイン → アクセス許可。

python3 scripts/yt_auth.py \
  --channel-id UCxxxxxxxxxxxxxxxxxxxxxx \
  --label todoro-chan

成功すると tokens/UCxxxxxxxxxxxxxxxxxxxxxx.json が生成される。中身は refresh token を含むので扱い注意。

4. token を Bitwarden にアップロード

他メンバーが使えるよう、生成された JSON を Bitwarden の mocha 共有 Vault にアップロード。タイトル例: insight-analysis-pro / token / todoro-chan。

Cデータを取得する（誰でも何度でも）

1. Bitwarden から token を配置

mkdir -p tokens
# Bitwarden の "insight-analysis-pro / token / xxx" を
# tokens/UCxxxxxxxxxxxxxxxxxxxxxx.json として保存

2. 維持率カーブを取る（一番使う）

python3 scripts/yt_analytics.py retention \
  --channel-id UCxxxxxxxxxxxxxxxxxxxxxx \
  --video-id abcDEFghi12 \
  --out output/retention.json

100ポイント（0%, 1%, ..., 100%）の audienceWatchRatio と relativeRetentionPerformance が JSON で返ってくる。

3. 流入元

python3 scripts/yt_analytics.py traffic \
  --channel-id UCxxxxxxxxxxxxxxxxxxxxxx \
  --video-id abcDEFghi12

4. 登録者増減（チャンネル全体 / 日次）

python3 scripts/yt_analytics.py subscribers \
  --channel-id UCxxxxxxxxxxxxxxxxxxxxxx \
  --start 2026-04-01 --end 2026-04-30

5. 任意クエリ（生 API）

python3 scripts/yt_analytics.py raw \
  --channel-id UCxxxxxxxxxxxxxxxxxxxxxx \
  --metrics views,likes,comments \
  --dimensions day \
  --filters "video==abcDEFghi12"

CLI リファレンス

共通オプション: --start YYYY-MM-DD / --end YYYY-MM-DD / --out PATH。 --start 省略時は動画公開日（video-id があれば）か30日前にフォールバック。

セキュリティと運用ルール

• refresh token = チャンネルの読み取り権限そのもの。漏れたら Google Cloud Console で OAuth クライアントを再発行 → 全 token 失効させる
• tokens/ credentials/ は必ず .gitignore。 git status で見えていないこと確認
• 共有は Bitwarden 共有 Vault のみ。Slack DM / メール添付 / Google Drive は NG
• token ファイルはローカル保存時にパーミッション 600（yt_auth.py が自動設定）
• 退職メンバーが出たら Bitwarden 共有 Vault のアクセス権を外す

トラブルシューティング