YouTube Channel Live Videos
YouTubeチャンネルのライブ配信は、特定のチャンネルのライブタブに表示される公開配信の項目で、動画ID、チャンネル情報、サムネイル、タイムスタンプ、表示中のエンゲージメントを持ちます。YouTubeがそのチャンネルで表示している内容に応じて、配信中、配信予定、アーカイブ済みの配信が含まれることがありますが、正規化されたライブ状態のラベルは保証されません。
YouTube Channel Live Videos API の主な機能
- 正規のチャンネルURLに対応公開されている /@handle、/channel/{id}、/c/{name}、/user/{name} 形式のYouTube URLを解決します。
- チャンネルのライブタブからの取得送信した各チャンネルのライブタブに表示されている配信項目を取得します。
- チャンネルごとの取得件数入力チャンネルごとに20〜2,000件のレコードをリクエストできます。デフォルトは100です。
- 正規化された配信レコード動画ID、タイトル、説明、チャンネル、サムネイル、再生時間、ハッシュタグ、公開日時、取得元の文脈を、利用可能な範囲で返します。
- 表示中のエンゲージメントのスナップショット公開されている視聴回数、高評価数、コメント数を collected_at とともに取得し、特定時点の分析に使えます。
- 非同期での結果配信タスクのステータスをポーリングし、タスクIDを保持して、カーソルページネーションで確実に非同期の結果を受け取れます。
YouTube Channel Live Videos API のパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
urls | 必須 | 公開YouTubeチャンネルのURLです。カンマまたは改行で区切って指定します。対応するパスは /@handle、/channel/{id}、/c/{name}、/user/{name} です。 |
results_limit | 任意 | チャンネルURLごとにリクエストする最大レコード数です。20〜2,000の整数で指定し、デフォルトは100です。 |
YouTube Channel Live Videos API の使い方
正規の公開チャンネルURLを送信し、それぞれの取得件数を指定します。リクエストは非同期タスクを作成するため、完了の確認と結果の取得は別のステップになります。
- 対応しているハンドル、チャンネルID、カスタム、ユーザーのいずれかのパスを使った公開YouTubeチャンネルURLを1つ以上用意します。
- urls と results_limit を /v1/youtube/channel-live-videos に POST し、返された task_id を保持します。
- タスクが succeeded または failed になるまで /v1/tasks/{task_id} をポーリングします。
- /v1/tasks/{task_id}?limit=50 から結果ページを読み取り、has_more が true の間は next_cursor を cursor として渡します。
curl -X POST "https://api.socq.ai/v1/youtube/channel-live-videos" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.youtube.com/@YouTube"],"results_limit":20}'
# Poll GET /v1/tasks/{task_id}
# Read GET /v1/tasks/{task_id}?limit=50&cursor={next_cursor}YouTube Channel Live Videos API の主なユースケース
- 配信一覧の構築: 選定したチャンネルに紐づく公開ライブ配信の構造化リストを作成します。
- ライブ配信番組の調査: 定期的にライブ配信を行うチャンネル間で、タイトル、配信タイミング、再生時間、投稿パターンを比較します。
- クリエイターの配信モニタリング: クリエイター、ブランド、パブリッシャー、競合のチャンネルで、どの公開配信レコードが表示されているかを追跡します。
- 配信後のパフォーマンスのスナップショット: 表示中の視聴回数、高評価数、コメント数を取得時刻とともに保存し、後からトレンドを比較します。
- 公開メディアカタログの情報補完: 正規化された配信メタデータと配信元チャンネルの情報を、検索、レポート、分類のシステムに追加します。
YouTube Channel Live Videos API 活用のヒント
- results_limit はすべてのチャンネルに適用されます。5つのURLに上限100を指定すると、タスク全体の重複排除の前に最大500件のレコードをリクエストすることになります。
- 空でないハンドル、チャンネルID、カスタム名、ユーザー名を含む正規のチャンネルURLを使用してください。/channel だけのパスでは取得元を解決できません。
- チャンネルのライブタブを取得対象の範囲として扱ってください。配信中、配信予定、アーカイブ済みの表示状況は、取得のたびに変わることがあります。
- type や extra.content_type から、配信中・配信予定・アーカイブ済みの状態を確実に判断しようとしないでください。正規化されたペイロードには専用のライブ状態フィールドがありません。
- レスポンスに含まれるのはメタデータとサムネイルの参照であり、ライブチャット、再生可能なストリームURL、字幕、文字起こしのテキストは含まれません。
- 同等のチャンネル入力から同じ動画が見つかることがあります。保存されるタスク結果は、正規化された動画IDで重複排除され、IDがない場合はURLで重複排除されます。
- タスク結果の limit は results_limit とは別物です。1ページあたり1〜500件の保存済み行をリクエストし、has_more が false になるまで不透明な next_cursor を渡し続けてください。
- 公開メタデータが取得できても、非公開やメンバー限定の視聴が可能になるわけではありません。取得元がその分類を報告している場合は extra.is_members_only を保持してください。
関連API
YouTube Channel Live Videos API 以外に別の種類の公開YouTubeデータが必要な場合は、これらのAPIをご利用ください。
- YouTube Channel Videos API — チャンネルURLから、ショートとライブ配信を除く通常の公開動画を取得します。
- YouTube Comments API — 公開コメント、投稿者、エンゲージメント、元の動画、会話の情報を取得します。
- YouTube Transcripts API — 取得可能なプレーンテキストの文字起こしを取得します。言語は任意で指定できます。
- YouTube Channels API — 公開チャンネルのアカウント情報、画像、認証状態、表示中のオーディエンス統計を取得します。
- YouTube Videos API — 既知の動画またはショートのURLから、メタデータ、サムネイル、再生時間、エンゲージメントを取得します。
- YouTube Shorts API — チャンネルごとに、公開ショート、サムネイル、再生時間、公開情報、エンゲージメントを取得します。
- YouTube Search API
- YouTube Comment Replies API
- YouTube Community Posts API
- YouTube Hashtag Search API
- YouTube Playlist Videos 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