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キーの取得方法
- Google Cloud Console にアクセス
- 新しいプロジェクトを作成するか、既存のプロジェクトを選択
- YouTube Data API v3 を有効化
- 認証情報 → APIキー を作成
- (オプション)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 | リクエストが多すぎます | リクエスト頻度を下げる |
クォータ最適化のヒント
fieldsパラメータを使用して、必要なフィールドのみをリクエスト- カンマ区切りのIDリストを使用してリクエストをバッチ処理
- 結果をキャッシュして重複リクエストを回避
- 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 {}