YouTube Videos
YouTube動画は、タイトル、説明、チャンネル情報、サムネイル、再生時間、公開情報、ハッシュタグ、ソース分類、表示中のエンゲージメントを持つ公開アップロードです。これらのメタデータとパフォーマンス指標は、動画情報の補完、コンテンツ調査、モニタリング、比較分析に活用できます。
YouTube Videos API の主な機能
- 既知URLの一括検索既知の公開動画URLやショートURLを、1回のリクエストで複数まとめて照会できます。
- 固定の動画IDすべての結果について、固定の動画ID、正規URL、タイトル、公開されている説明、投稿元チャンネルを返します。
- コンテンツのメタデータサムネイル、再生時間、ハッシュタグ、公開日、正規化されたコンテンツ種別を含みます。
- 特定時点のエンゲージメント指標公開されている視聴回数、高評価数、コメント数を collected_at とともに取得し、特定時点での比較に使えます。
- 一貫した動画スキーマ通常の動画と対応しているショートURLのどちらにも、同じ正規化された動画構造を提供します。
YouTube Videos API のパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
urls | 必須 | 公開されているYouTube動画またはショートのURLです。カンマまたは改行で区切って指定します。 |
YouTube Videos API の使い方
集めたリンクを、アプリケーションで結合・検索・更新できるレコードに変換します。リクエストは非同期のため、アクセス可能なすべてのURLの処理が完了するまでタスクIDを保持してください。
- 公開されている視聴ページまたはショートのURLを集めて重複を排除します。チャンネルURLや検索結果URLは別のエンドポイントで扱います。
- urls 配列を /v1/youtube/videos に POST し、返された task_id を元のバッチと紐づけて保存します。
- /v1/tasks/{task_id} をポーリングします。queued と running は、バッチがまだ処理中であることを示します。
- 成功したら data.results.items を id でインデックス化し、has_more が true の間は next_cursor を使って続きを取得します。
curl -X POST "https://api.socq.ai/v1/youtube/videos" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.youtube.com/watch?v=arj7oStGLkU"]}'
# Poll GET /v1/tasks/{task_id}
# Read GET /v1/tasks/{task_id}?limit=50YouTube Videos API の主なユースケース
- URLリストの情報補完: 既存のYouTube URLリストに、タイトル、チャンネル情報、サムネイル、再生時間、公開日、公開指標を追加します。
- 選定した動画の比較: 選んだ動画やショートの間で、公開されている視聴回数、高評価数、コメント数、再生時間、公開情報を比較します。
- キャンペーン・競合のモニタリング: 既知のキャンペーン動画、クリエイター動画、競合動画のメタデータのスナップショットを繰り返し取得します。
- コンテンツカタログ: 正規化された動画レコードを、社内検索、レポート、モデレーション、要約、分析のワークフローに提供します。
YouTube Videos API 活用のヒント
- id を主キーにしてください。タイトルは変わることがあり、同じ動画が複数の有効なURL形式で届くこともあります。
- 外部リンクには canonical_url を使い、レコードの出どころを追跡する必要がある場合は input_url も保持してください。
- 指標は collected_at 時点のページの状態を表します。2つのスナップショットを比較すると有用ですが、古いものを上書きするとその履歴が失われます。
- 説明欄のリンクは、表示、クロール、インポートの前に信頼できない外部入力として扱ってください。
- 結果がないことは、そのURLが存在しなかった証拠ではありません。非公開、削除済み、制限付き、または一時的にアクセスできない項目はバッチから抜け落ちることがあります。
- コメントと文字起こしのテキストは意図的に分けています。ワークフローでその段階に進んだ項目についてのみリクエストしてください。
- トピックから動画を探す場合は Search から始めてください。対象のURLがすでにわかっている場合は Videos を使用します。
関連API
YouTube Videos API 以外に別の種類の公開YouTubeデータが必要な場合は、これらのAPIをご利用ください。
- YouTube Channel Videos API — チャンネルURLから、ショートとライブ配信を除く通常の公開動画を取得します。
- YouTube Comments API — 公開コメント、投稿者、エンゲージメント、元の動画、会話の情報を取得します。
- YouTube Transcripts API — 取得可能なプレーンテキストの文字起こしを取得します。言語は任意で指定できます。
- YouTube Channels API — 公開チャンネルのアカウント情報、画像、認証状態、表示中のオーディエンス統計を取得します。
- YouTube Shorts API — チャンネルごとに、公開ショート、サムネイル、再生時間、公開情報、エンゲージメントを取得します。
- YouTube Related Videos API — 動画URLの横におすすめとして表示される動画を一覧で取得し、タイトル、チャンネル、視聴回数、サムネイルを返します。
- YouTube Search API
- YouTube Channel Live Videos 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 Channel Search API
- YouTube Shorts Search API
- YouTube Search Suggestions API
- YouTube Email Finder API
- YouTube Trending Videos API