YouTube Search
YouTube検索の結果は、キーワードやフレーズに一致した通常の公開動画で、タイトル、チャンネル、サムネイル、再生時間、公開情報、表示中のエンゲージメントを持ちます。これらのレコードは、トピックの発見、コンテンツ調査、競合の追跡、機会分析に活用できます。
YouTube Search API の主な機能
- URL不要の動画発見URLを事前に知らなくても、公開されている通常の動画を見つけられます。
- 結果の並び替え関連度、公開日、評価、公開されている視聴回数で結果を並び替えられます。
- 公開期間1時間、1日、1週間、1か月、1年の公開期間で結果を絞り込めます。
- 長さと字幕のフィルター短い・中程度・長いの動画の長さで絞り込み、必要に応じて字幕があるものに限定できます。
- 正規化された動画結果正規化された動画メタデータ、チャンネル情報、サムネイル、再生時間、公開データ、公開指標を返します。
YouTube Search API のパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
query | 必須 | 公開動画を探すためのキーワードまたはフレーズです。 |
results_limit | 任意 | 取得する公開動画結果の最大件数です。正の整数で指定し、デフォルトは100です。 |
sort_by | 任意 | 結果の並び順です。デフォルトは relevance です。 |
published_within | 任意 | 任意。リクエスト時点から遡って数える公開期間です。 |
duration | 任意 | 任意。YouTubeの動画の長さのカテゴリです。 |
has_captions | 任意 | 任意。字幕の有無で絞り込むフィルターです。指定しなければこのフィルターは適用されません。 |
YouTube Search API の使い方
クエリは単なるキーワードではなく、取得戦略として設計してください。まずは全体像をつかめる程度に広く始め、どの条件で候補が除外されたかがわかるよう、フィルターは1つずつ追加します。
- トピックと目的を決めます。トピックに最も合う動画、最新の動画、視聴回数の多い動画、文字起こしに使える候補のどれが必要かを明確にします。
- query と results_limit に加え、その目的に必要な並び順とフィルターだけを /v1/youtube/search に POST します。
- リクエスト全体を task_id とともに保存し、検索が成功または失敗するまで /v1/tasks/{task_id} をポーリングします。
- 動画IDで結果の重複を排除し、順位の文脈と collected_at を保持したうえで、has_more が true の間はページネーションを続けます。
curl -X POST "https://api.socq.ai/v1/youtube/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"NASA Artemis","results_limit":10,"sort_by":"date","published_within":"month","duration":"medium","has_captions":true}'
# Poll GET /v1/tasks/{task_id}
# Read GET /v1/tasks/{task_id}?limit=50YouTube Search API の主なユースケース
- トピック・市場調査: 製品、業界、組織、イベント、新たなトピックに関する公開動画を見つけます。
- クリエイター・競合の発見: 検索結果と投稿元チャンネルの情報を使い、関連するクリエイター、ブランド、競合を特定します。
- 最新動画のモニタリング: 日付順の並び替えと公開期間を組み合わせ、確認や分析のために最近の動画を取得します。
- 文字起こし向けデータセット: 字幕があるものに限定して、文字起こしの取得、要約、分類、検索に使う動画を見つけます。
YouTube Search API 活用のヒント
- すべての概念を1つの長いフレーズに詰め込むのではなく、具体的なクエリのバリエーションを2〜3個試してください。重なる部分は、違いと同じくらい多くのことを教えてくれます。
- フィルターは段階的に追加してください。公開期間、長さ、字幕を一度に指定すると、結果が空だったときにどの条件が厳しすぎたのか判断しにくくなります。
- モニタリングには date と published_within を組み合わせてください。期間を指定しない relevance は、より広い別の調査目的に向いています。
- ランキングは安定していません。サンプル内の順位や構成が重要な場合は、リクエスト、タスクID、動画ID、collected_at を必ず保存してください。
- results_limit は上限であり、網羅性を保証するものではありません。公開状況や選択したフィルターによって、レコードが少なくなることがあります。
- クエリのバリエーションをまたいで動画IDで重複を排除しつつ、後で関連性を分析できるよう、どのクエリで一致したかを保持してください。
- URLがわかったら、何度も検索し直すのではなく、最新の詳細には Videos を、利用可能な字幕テキストには Transcripts を使用してください。
関連API
YouTube Search API 以外に別の種類の公開YouTubeデータが必要な場合は、これらのAPIをご利用ください。
- YouTube Comments API — 公開コメント、投稿者、エンゲージメント、元の動画、会話の情報を取得します。
- YouTube Transcripts API — 取得可能なプレーンテキストの文字起こしを取得します。言語は任意で指定できます。
- YouTube Channels API — 公開チャンネルのアカウント情報、画像、認証状態、表示中のオーディエンス統計を取得します。
- YouTube Videos API — 既知の動画またはショートのURLから、メタデータ、サムネイル、再生時間、エンゲージメントを取得します。
- YouTube Hashtag Search API — ハッシュタグフィードから公開動画を探します。すべてのコンテンツか、ショートのみかを選んで取得できます。
- YouTube Channel Search API — キーワードでチャンネルを検索し、チャンネル名、チャンネル登録者数、アイコン、説明文の抜粋を返します。
- YouTube Channel Videos API
- YouTube Shorts API
- YouTube Channel Live Videos API
- YouTube Comment Replies API
- YouTube Community Posts API
- YouTube Playlist Videos API
- YouTube Trending Shorts API
- YouTube Community Post API
- YouTube Community Post Comments API
- YouTube Related Videos API
- YouTube Shorts Search API
- YouTube Search Suggestions API
- YouTube Email Finder API
- YouTube Trending Videos API