YouTubeチャンネルプロファイル
scripts/channel_profile.py は、YouTube Data API v3を通じて公開チャンネルデータを読み取り、Markdownレポート（--jsonでJSON出力）を表示します。公式APIのみを使用し、YouTube Webページを読み込んだり、ディスクに書き込んだりすることはありません。
実行前の準備
- 人間がGoogle CloudプロジェクトでYouTube Data API v3を有効にし、そのAPIに制限されたAPIキーを作成する必要があります。
- キーは
YOUTUBE_API_KEY環境変数に格納します。プロンプト、ファイル、チャットに入力したり、印刷したりしないでください。設定されていない場合は停止し、人間に設定を依頼してください。他の場所でキーを探さないでください。 - 依存関係をインストールします:
pip install -r scripts/requirements.txt（requests）。
実行
python3 scripts/channel_profile.py @handle
python3 scripts/channel_profile.py https://www.youtube.com/@handle --videos 100
python3 scripts/channel_profile.py UCxxxxxxxxxxxxxxxxxxxxxx --json
オプション: --videos N（取得する最近のアップロード数、デフォルト50、最大500）、--json、--no-search、--cpm-low と --cpm-high（デフォルト0.25と4.00）。
チャンネルの特定方法
- チャンネルIDまたは
/channel/UC...URL:channels.listをidで検索。 @handleまたは/@handleURL:channels.listをforHandleで検索。/user/URL:forUsernameで検索。/c/URLはハンドルとして試行します。- いずれも一致しない場合、
search.listで最適な一致を検索し、レポートにその旨を記載します。タイトルとIDを確認してから使用してください。--no-searchでフォールバックを無効にします。 - 動画リンク、プレイリストリンク、YouTube以外のアドレスは拒否されます。チャンネルリンクを依頼してください。
クォータ
| 呼び出し | コスト |
|---|---|
channels.list | 1 ユニット |
playlistItems.list | 50 アップロードごとに 1 ユニット |
videos.list | 50 動画ごとに 1 ユニット |
search.list（フォールバックのみ） | 独自バケットから 1 呼び出し |
デフォルト実行は、10,000ユニット/日のデフォルトクォータのうち3ユニットを消費します。2026年6月1日以降、search.list は1日100回の独自バケットを持ちます。それ以前は、1回の検索でメインクォータから100ユニット消費したため、古いガイドでは100と記載されています。失敗した呼び出しもクォータを消費します。クォータは太平洋標準時の午前0時にリセットされます。すべてのレポートは消費したクォータを最後に表示します。
レポート内容
YouTubeから返されるままのデータ:
- 登録者数（YouTubeにより有効数字3桁に切り捨て）。所有者が非表示にしている場合、レポートは「非表示」と表示し、推測は行いません。
- チャンネルの総視聴数と公開動画数。
- 各直近動画の視聴数、いいね数、コメント数。
スクリプトが導出するデータ（* 印付き）:
- アップロード頻度: 最新N件のアップロード間の中央日数、月間アップロード数（（N - 1）ギャップ / 経過日数 x 30.44）、最終アップロードからの経過日数。
- 直近動画の中央値および平均視聴数。ライブ配信と今後の配信は除外。
- 傾向: 最新10件のアップロードの中央視聴数とその前10件の中央視聴数の比較。新しい動画は視聴数が集まる時間が短いことに注意。
- エンゲージメント: 動画ごとに（いいね数 + コメント数）/ 視聴数、その中央値。いいねが非表示の動画は除外。コメントがオフの動画はコメント数を0としてカウント。
- Shortsと長尺動画の割合（動画時間による）。これはヒューリスティックです: 180秒以下をShortsと判定します。APIにはShortsフラグがないためです。
- 視聴数上位5件の直近動画。
- 推定月間視聴数: 過去30日以内に公開された動画の現在の視聴数の合計。バックカタログの視聴数は含まれません。サンプルが30日前まで遡らない場合、レポートはその旨を表示し、より多くの
--videosを要求します。このチェックは、アップロードプレイリストが通常通り最新順にリストされていることを前提としています。
YouTube APIポリシーIII.E.4.hに基づき、導出データはYouTube自身の合計値と並べて、YouTubeからのデータではないことを明記する必要があります。レポートは両方を行います。星印のついた数値を引用する際は、必ずその注記を保持してください。
収益計算方法
低 = 推定月間視聴数 / 1,000 x US$0.25
高 = 推定月間視聴数 / 1,000 x US$4.00
US$0.25～US$4.00はSocial Bladeが公開しているデフォルトのCPM範囲です（socialblade.com/youtube/calculator）。レポートは実際の数値を使用した計算式を出力します。これは広告収入のみです。スポンサーシップ、メンバーシップ、ショッピング、アフィリエイト収入、ファンファンディングは含まれません。実際のRPMはニッチ、視聴者国、フォーマットによって異なります。Shorts収入は異なる条件でプールされます。YouTubeパートナープログラムに参加していないチャンネルは広告収入を得られません。常に推定範囲として呼び、収入とは呼ばないでください。
エラー
| 終了コード | 意味 | 対処方法 |
|---|---|---|
| 0 | レポートが出力されました | |
| 2 | 不正な入力、キー不足、チャンネルが見つからない | 入力を修正するか、人間にキーまたは正しいリンクを依頼する |
| 3 | クォータを使い果たした | 停止する。太平洋標準時の午前0時にリセットされることを人間に伝える。ループで再試行したりキーを切り替えたりしない |
| 4 | その他のAPIエラー（無効なキー、APIが有効でないなど） | メッセージを人間に表示する |
| 5 | ネットワークエラー | 1回再試行し、その後報告する |
エラーは失敗前に消費したクォータを出力します。すべてのメッセージとレポートは、印刷される前にキーが除去されます。
ルール
- 公式APIのみを使用。不足を補うためにYouTubeページをスクレイピングしないでください。不足はそのまま報告してください。
- 実行を超えてキャッシュしないでください。生のAPIレスポンスを保存しないでください。人間がレポートを保持する場合、API統計情報は30日を超えて保存してはなりません（ポリシーIII.E.4.b）。
- 公開データのみ。視聴者属性は公開されていません:
creator-audienceスキルを参照してください。
2026年11月5日、YouTube Data APIリファレンス、クォータページ、改訂履歴、デベロッパーポリシーに照らして確認済み。スクリプトのテストはオフラインでフィクスチャに対して実行されます。ここではライブAPIに対して実行されていません。