Communitygithub.com

Yrzhe/claude-skills

YouTube Data API v3の完全なラッパー - 動画検索、動画/チャンネル/プレイリスト詳細の取得、コメント取得、字幕ダウンロードなど。時間/再生回数/評価などによるフィルタリングと並べ替えをサポート。

claude-skills とは?

このスキルは、YouTube Data API v3を完全にラップしたPythonスクリプト群であり、Claude CodeやCursor、CodexなどのAIエージェント環境で利用できます。APIキーの設定を行うことで、動画の検索、詳細情報の取得、チャンネルやプレイリストの情報取得、コメントの取得、字幕のダウンロードなど、YouTubeの主要なデータ操作をコマンドラインから実行できます。検索機能では、公開期間、並べ替え順、動画の画質・長さ・キャプションの有無、地域、ライブ配信ステータスなど、多様なフィルタリングとソートが可能です。また、取得結果はJSON、CSV、シンプル形式で出力でき、ページネーションやエラーハンドリング、クォータ最適化のためのヒントも提供されています。標準のAPIキーで利用できる読み取り操作に加え、OAuth認証が必要なアップロードや書き込み操作についても言及されており、開発者やAIエージェントユーザーがYouTubeデータを効率的に収集・分析するための強力なツールとなっています。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Yrzhe/claude-skills/tree/HEAD/plugins/youtube-data-api/skills/youtube-data-api

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

YouTube Data API v3 スキル

公式YouTube Data API v3ドキュメントに基づく完全なラッパーです。

設定

APIキーの設定

# オプション1: 環境変数(推奨)
export YOUTUBE_API_KEY="YOUR_API_KEY_HERE"

# オプション2: 設定ファイルを直接編集
# ~/.claude/skills/youtube-data-api/scripts/config.py を編集

APIキーの取得方法

  1. Google Cloud Console にアクセス
  2. 新しいプロジェクトを作成するか、既存のプロジェクトを選択
  3. YouTube Data API v3 を有効化
  4. 認証情報 → APIキー を作成
  5. (オプション)APIキーをYouTube Data APIのみに制限

クォータ制限

操作の種類クォータコスト(単位)
読み取り操作(リスト)1
検索リクエスト100
書き込み操作(挿入/更新/削除)50
動画アップロード1600

デフォルトの1日あたりのクォータ: 10,000単位


コア機能

1. 動画の検索(Search)

クォータコスト: 100単位/リクエスト

# 基本検索
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "Python tutorial" \
    --max-results 25

# 時間でフィルタ(過去1週間)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "machine learning" \
    --published-after "7d" \
    --type video

# 再生回数で並べ替え
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "React hooks" \
    --order viewCount \
    --type video

# HD動画のみ
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "4K nature" \
    --video-definition high \
    --type video

# キャプション付き動画
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "TED talk" \
    --video-caption closedCaption \
    --type video

# ライブ配信中動画
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "gaming" \
    --event-type live \
    --type video

# 地域でフィルタ
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "news" \
    --region-code US \
    --relevance-language en

# 動画の長さでフィルタ
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "documentary" \
    --video-duration long \
    --type video

検索パラメータリファレンス

パラメータ説明値
--query, -q検索キーワードブール演算子をサポート(python AND tutorial)
--typeリソースタイプvideo, channel, playlist
--max-results結果数1~50、デフォルト25
--order並べ替え順relevance(デフォルト)、date, rating, viewCount, title
--published-after公開日時(以降)1d, 7d, 30d, 1y または ISO 8601形式
--published-before公開日時(以前)同上
--region-code地域コードISO 3166-1(例:US, CN, JP)
--relevance-language言語ISO 639-1(例:en, zh, ja)
--video-duration動画の長さshort(4分未満), medium(4~20分), long(20分超)
--video-definition画質high(HD), standard(SD)
--video-captionキャプションclosedCaption(キャプションあり), none(キャプションなし)
--video-dimension次元2d, 3d
--event-typeライブステータスlive(配信中), completed(終了), upcoming(予定)
--channel-idチャンネルを限定チャンネルID
--safe-searchセーフサーチnone, moderate, strict

2. 動画詳細の取得(Videos)

クォータコスト: 1単位/リクエスト

# 単一動画の詳細を取得
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py video \
    --id "dQw4w9WgXcQ" \
    --parts snippet,statistics,contentDetails

# 複数動画を一括取得
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py video \
    --id "dQw4w9WgXcQ,jNQXAC9IVRw,9bZkp7q19f0" \
    --parts snippet,statistics

# トレンド動画を取得
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py video \
    --chart mostPopular \
    --region-code US \
    --max-results 50

# カテゴリ別トレンド
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py video \
    --chart mostPopular \
    --video-category-id 10 \
    --region-code JP

Video Parts リファレンス

パーツ内容
snippetタイトル、説明、サムネイル、チャンネル情報、公開時刻、タグ
statistics再生回数、いいね数、コメント数
contentDetails長さ、画質、キャプション情報、地域制限
statusアップロードステータス、プライバシー、ライセンス
player埋め込みプレーヤーHTML
topicDetails関連トピックID
recordingDetails録画場所、日付
liveStreamingDetailsライブ情報(開始/終了時刻、視聴者数)

動画カテゴリID リファレンス

IDカテゴリIDカテゴリ
1映画&アニメーション20ゲーム
2自動車&乗り物22人物&ブログ
10音楽23コメディ
15ペット&動物24エンターテイメント
17スポーツ25ニュース&政治
19旅行&イベント26ハウツー&スタイル
27教育28科学&テクノロジー

3. チャンネル情報の取得(Channels)

クォータコスト: 1単位/リクエスト

# チャンネルIDで取得
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py channel \
    --id "UC_x5XG1OV2P6uZZ5FSM9Ttw" \
    --parts snippet,statistics,contentDetails

# ユーザー名で取得
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py channel \
    --for-username "GoogleDevelopers" \
    --parts snippet,statistics

# ハンドル(@ユーザー名)で取得
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py channel \
    --for-handle "@Google" \
    --parts snippet,statistics,brandingSettings

Channel Parts リファレンス

パーツ内容
snippetチャンネル名、説明、サムネイル、国
statistics登録者数、動画数、総再生回数
contentDetails関連プレイリスト(アップロード、いいねなど)
brandingSettingsチャンネルバナー、キーワード、デフォルト言語
topicDetailsチャンネルトピック
statusチャンネルステータス(長時間動画アップロード権限など)

4. プレイリストの取得(Playlists)

クォータコスト: 1単位/リクエスト

# プレイリストIDで取得
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py playlist \
    --id "PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf" \
    --parts snippet,contentDetails

# チャンネルの全プレイリストを取得
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py playlist \
    --channel-id "UC_x5XG1OV2P6uZZ5FSM9Ttw" \
    --max-results 50

5. プレイリストの動画を取得(PlaylistItems)

クォータコスト: 1単位/リクエスト

# プレイリスト内の全動画を取得
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py playlist-items \
    --playlist-id "PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf" \
    --max-results 50

# ページネーション
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py playlist-items \
    --playlist-id "PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf" \
    --page-token "NEXT_PAGE_TOKEN"

6. コメントの取得(Comments & CommentThreads)

クォータコスト: 1単位/リクエスト

# 動画の全コメントを取得(トップレベル)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py comments \
    --video-id "dQw4w9WgXcQ" \
    --max-results 100 \
    --order relevance

# チャンネルのコメントを取得
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py comments \
    --channel-id "UC_x5XG1OV2P6uZZ5FSM9Ttw" \
    --max-results 50

# コメントへの返信を取得
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py comment-replies \
    --parent-id "COMMENT_ID" \
    --max-results 50

コメント並べ替えオプション

並べ替え説明
relevance関連性順(デフォルト)
time時間順(新しい順)

7. キャプションの取得(Captions)

クォータコスト: 1単位/リクエスト(リスト)、50単位(ダウンロード)

# 動画の全キャプショントラックを一覧表示
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py captions \
    --video-id "dQw4w9WgXcQ" \
    --list

# キャプションをダウンロード(OAuthが必要)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py captions \
    --video-id "dQw4w9WgXcQ" \
    --download \
    --caption-id "CAPTION_ID" \
    --format srt

注意: キャプションのダウンロードには動画所有者の許可(OAuth)が必要です。公開動画の場合は、yt-dlpを使用して自動生成キャプションを取得できます。

yt-dlpを使用した字幕取得(代替方法)

# yt-dlpをインストール
pip install yt-dlp

# 利用可能な字幕を一覧表示
pyt-dlp --list-subs "https://www.youtube.com/watch?v=VIDEO_ID"

# 字幕をダウンロード(動画はスキップ)
-US --write-sub --write-auto-sub --sub-lang en,zh-Hans --skip-download \
    "https://www.youtube.com/watch?v=VIDEO_ID"

# ダウンロードしてSRT形式に変換
-US --write-sub --write-auto-sub --sub-lang en --sub-format srt --skip-download \
    "https://www.youtube.com/watch?v=VIDEO_ID"

8. 動画カテゴリの取得(VideoCategories)

クォータコスト: 1単位/リクエスト

# 地域の動画カテゴリを取得
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py categories \
    --region-code US

# 中国のカテゴリを取得
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py categories \
    --region-code CN

9. 対応地域と言語の取得

クォータコスト: 1単位/リクエスト

# 対応地域のリストを取得
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py regions

# 対応言語のリストを取得
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py languages

共通ユースケースの例

シナリオ1: 先週の特定トピックに関するトレンド動画を取得

# 過去7日間の「AI」に関する動画を検索し、再生回数順に並べ替え
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "AI artificial intelligence" \
    --published-after "7d" \
    --order viewCount \
    --type video \
    --max-results 50 \
    --output ai_trending.json

# これらの動画の詳細統計を取得
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py video \
    --ids-from ai_trending.json \
    --parts snippet,statistics,contentDetails \
    --output ai_trending_details.json

シナリオ2: チャンネルの全動画を分析

# 1. チャンネル情報を取得
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py channel \
    --for-handle "@GoogleDevelopers" \
    --parts snippet,statistics,contentDetails \
    --output channel_info.json

# 2. アップロードプレイリストIDを取得(contentDetails.relatedPlaylists.uploads から)

# 3. アップロードされた全動画を取得
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py playlist-items \
    --playlist-id "UPLOADS_PLAYLIST_ID" \
    --max-results 50 \
    --all-pages \
    --output channel_videos.json

シナリオ3: 字幕付き動画を取得

# 1. 動画を検索
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "TED talk motivation" \
    --video-caption closedCaption \
    --type video \
    --max-results 10 \
    --output ted_videos.json

# 2. yt-dlpを使用して字幕をダウンロード
for video_id in $(jq -r '.items[].id.videoId' ted_videos.json); do
    yt-dlp --write-sub --write-auto-sub --sub-lang en --skip-download \
        "https://www.youtube.com/watch?v=$video_id" \
        -o "subtitles/%(id)s.%(ext)s"
done

シナリオ4: 動画コメントを分析

# 動画の全コメントを取得
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py comments \
    --video-id "VIDEO_ID" \
    --max-results 100 \
    --all-pages \
    --output comments.json

# コメントデータには以下が含まれます:
# - 著者名
# - コメントテキスト
# - いいね数
# - 公開時刻
# - 返信数

出力形式

すべてのコマンドはデフォルトでJSON形式で出力され、--outputパラメータでファイルに保存できます。

# ファイルに出力
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "Python" \
    --output results.json

# CSV形式(表形式データ)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "Python" \
    --format csv \
    --output results.csv

# シンプル出力(タイトルとIDのみ)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "Python" \
    --format simple

ページネーション

大規模なデータセットの場合、APIはpageTokenを使用してページネーションを行います:

# すべてのページを自動取得
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "Python" \
    --all-pages \
    --max-total 500 \
    --output all_results.json

# 手動ページネーション
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "Python" \
    --page-token "NEXT_PAGE_TOKEN"

エラーハンドリング

一般的なエラーコード

コード説明解決策
400不正なリクエストパラメータ形式を確認
401認証エラーAPIキーを確認
403クォータ超過または権限不足クォータを確認するか、増加をリクエスト
404リソースが見つかりませんIDが正しいか確認
429リクエストが多すぎますリクエスト頻度を下げる

クォータ最適化のヒント

  1. fieldsパラメータを使用して、必要なフィールドのみをリクエスト
  2. カンマ区切りのIDリストを使用してリクエストをバッチ処理
  3. 結果をキャッシュして重複リクエストを回避
  4. ETagを使用してリソースが更新されたかどうかを確認
# 必要なフィールドのみを取得(応答サイズを削減)
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py video \
    --id "VIDEO_ID" \
    --fields "items(id,snippet(title,channelTitle),statistics(viewCount))"

OAuthを必要とする操作

以下の操作にはユーザー認証(APIキーのみでは不十分)が必要です:

  • 動画のアップロード
  • 動画メタデータの更新
  • 動画の削除
  • プレイリストの管理
  • コメントの投稿/削除
  • 字幕のダウンロード(動画所有者以外の場合)

OAuth認証情報の設定

# ~/.claude/skills/youtube-data-api/scripts/config.py に追加:
# YOUTUBE_CLIENT_ID = "your_client_id"
# YOUTUBE_CLIENT_SECRET = "your_client_secret"

インストール

# リポジトリのクローン
skilled mount yrzhe/youtube-data-api

高度な使用例

API応答からのデータ変換

# 検索結果をカスタム形式に変換
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "Python" \
    --format csv \
    --output results.csv

他のツールとの統合

# jqを使用した処理
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "Python" | jq '.items[].snippet.title'

# xargsを使用したバッチ処理
python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py search \
    --query "Python" | jq -r '.items[].id.videoId' | xargs -I {} \
    python ~/.claude/skills/youtube-data-api/scripts/youtube_api.py video --id {}

関連リソース

関連スキル