YouTube Playlist Videos
YouTube再生リストの動画は、公開再生リストにまとめられた項目で、動画ID、タイトル、チャンネル情報、サムネイル、再生時間、取得元の再生リスト情報を持ちます。これらのレコードは、再生リストのカタログ化、シリーズのインデックス化、コンテンツの確認、動画リンクの情報補完に活用できます。
YouTube Playlist Videos API の主な機能
- 複数の再生リストURL・IDに対応1つのタスクで1つ以上の公開再生リストURLまたは再生リストIDを処理し、解決された再生リストごとに results_limit を個別に適用します。
- 正規化された動画カタログ行動画ID、タイトル、正規URL、チャンネル情報、サムネイル1件、秒単位の再生時間、取得時刻を一貫した構造で返します。
- 再生リストと所有者の情報再生リストID、再生リストのタイトル、読みやすい形式の再生時間テキストを保持し、動画行に独自のチャンネルフィールドがない場合は再生リスト所有者の情報も保持します。
YouTube Playlist Videos API のパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
urls | 必須 | list クエリの値を含む公開再生リストURL、または再生リストIDを1つ以上指定します。カンマまたは改行で区切ってください。 |
results_limit | 任意 | 各再生リストから返された動画配列のうち保持するレコードの最大件数です。デフォルトは100で、10〜2,000の整数を指定できます。 |
YouTube Playlist Videos API の使い方
既知の公開再生リストの参照を非同期タスクとして送信し、タスクが成功したら、保存された正規化動画行をページ単位で読み取ります。
- list クエリの値を含む公開再生リストURLまたは再生リストIDを1つ以上用意し、重複する参照を取り除きます。
- urls と任意で10〜2,000の results_limit を /v1/youtube/playlist-videos に POST し、返された task_id を保存します。
- タスクのステータスが succeeded または failed になるまで /v1/tasks/{task_id} をポーリングします。
- data.results.items を読み取り、results.has_more が true の間は results.next_cursor を使って続きを取得します。再生リストIDと動画IDは元のデータと照合してください。
curl -X POST "https://api.socq.ai/v1/youtube/playlist-videos" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.youtube.com/playlist?list=PLP32wGpgzmIlInfgKVFfCwVsxgGqZNIiS"],"results_limit":100}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueYouTube Playlist Videos API の主なユースケース
- 公開再生リストの一覧作成: 選定した公開再生リストについて、動画ID、タイトル、URL、チャンネル情報、サムネイル、再生時間、取得元の再生リスト情報を含む構造化された一覧を作成します。
- 講座・シリーズのインデックス化: 再生リストのタイトルを、動画タイトル、チャンネル情報、再生時間、元のリンクとともにインデックス化し、公開講座、講演、連続コンテンツを整理します。
- 動画の情報補完用シードリスト: 返された正規の動画URLとIDを重複のないキューとして使い、詳細取得、文字起こし、レビュー、アーカイブなどの別のワークフローに回します。
YouTube Playlist Videos API 活用のヒント
- 再生リストIDそのもの、または list クエリの値が入ったURLのいずれかを使用してください。URLのその他の部分は再生リストの解決に使われず、list のないURLはスキップされます。
- results_limit は、最初に返された動画配列に対する再生リストごとの上限として扱ってください。大きな再生リストを深くまで取得することを保証するものではありません。
- 完全に一致する文字列の重複しか除去されず、同じ再生リストのURLの表記違いで処理が重複することがあるため、バッチにまとめる前に各再生リストを1つの表記に統一してください。
- 非公開、削除済み、制限付き、非表示、形式不正、利用不可の項目は含まれない場合があるため、返された extra.playlist_id と動画の id を入力データと照合してください。
- レコードの来歴には collected_at を使用してください。metrics は空で created_at は null のため、公開日やエンゲージメントが必要な場合は動画の詳細を別途リクエストしてください。
関連API
YouTube Playlist Videos API 以外に別の種類の公開YouTubeデータが必要な場合は、これらのAPIをご利用ください。
- YouTube Channel Videos API — チャンネルURLから、ショートとライブ配信を除く通常の公開動画を取得します。
- YouTube Comments API — 公開コメント、投稿者、エンゲージメント、元の動画、会話の情報を取得します。
- YouTube Transcripts API — 取得可能なプレーンテキストの文字起こしを取得します。言語は任意で指定できます。
- YouTube Videos API — 既知の動画またはショートのURLから、メタデータ、サムネイル、再生時間、エンゲージメントを取得します。
- YouTube Shorts API — チャンネルごとに、公開ショート、サムネイル、再生時間、公開情報、エンゲージメントを取得します。
- YouTube Channel Live Videos API — チャンネルのライブ欄に表示されている公開配信のレコードを、取得元の情報と表示中の指標とともに取得します。
- YouTube Channels API
- YouTube Search API
- YouTube Comment Replies API
- YouTube Community Posts API
- YouTube Hashtag Search API
- YouTube Trending Shorts API
- YouTube Community Post API
- YouTube Community Post Comments API
- YouTube Related Videos API
- YouTube Channel Search API
- YouTube Shorts Search API
- YouTube Search Suggestions API
- YouTube Email Finder API
- YouTube Trending Videos API