YouTube Community Posts
YouTubeコミュニティ投稿は、チャンネルのタブに公開されるお知らせで、投稿テキスト、投稿元チャンネルの情報、投稿日時、公開リンク、添付画像を持ちます。これらのレコードは、チャンネルのフィード一覧の作成、お知らせの確認、チャンネル横断の投稿分析に活用できます。
YouTube Community Posts API の主な機能
- 複数チャンネルURLからの取得@handle、/channel/、/c/、/user/ のパスを使った完全な公開チャンネルURLを受け付け、選択した件数上限をチャンネルごとに個別に適用します。
- 正規化された投稿レコード公開投稿ID、コミュニティのURL、テキスト、投稿のタイムスタンプ、取得のタイムスタンプを一貫した構造で返します。
- チャンネルと投稿の紐づけ各投稿を、チャンネルID、ハンドル、表示名、公開チャンネルURL、送信した取得元URLと紐づけたまま保持します。
- 添付画像の参照公開されている投稿画像を正規化されたメディア項目に対応づけ、画像中心の投稿も投稿レコードと紐づいた状態に保ちます。
- 範囲を限定したフィードの走査チャンネルごとに取得元の続きのページをたどり、IDまたはURLで重複する投稿を除外して、選択した上限、フィードの終端、100ページの上限のいずれかで停止します。
YouTube Community Posts API のパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
urls | 必須 | 必須。公開YouTubeチャンネルのURLです。カンマまたは改行で区切って指定します。対応するパスは @handle、/channel/、/c/、/user/ で始まるものです。 |
results_limit | 任意 | 入力チャンネルごとに取得するコミュニティ投稿の最大件数です。デフォルトは100で、20〜2000の整数を指定できます。 |
YouTube Community Posts API の使い方
既知の公開チャンネルを1つ以上、非同期タスクとして送信し、完了後に保存されたコミュニティ投稿のレコードを読み取ります。
- @handle、/channel/、/c/、/user/ のいずれかのパスを使った、完全な公開YouTubeチャンネルURLを用意します。
- urls と20〜2000の results_limit を /v1/youtube/community-posts に POST します。
- 返された task_id を保持し、タスクが queued、running、retrying の間は GET /v1/tasks/{task_id} をポーリングします。
- 成功したら data.results.items を読み取り、data.results.has_more が true の間は data.results.next_cursor をタスクリクエストの cursor として渡します。
curl -X POST "https://api.socq.ai/v1/youtube/community-posts" \
-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 data.results.items and pass data.results.next_cursor as cursor while has_more is trueYouTube Community Posts API の主なユースケース
- チャンネルのコミュニティフィード一覧: 投稿ID、URL、テキスト、タイムスタンプ、取得元チャンネルの文脈を使い、選定した公開チャンネルから確認しやすいフィードを構築します。
- お知らせ・クリエイティブの確認: 公開投稿のテキストと保持された画像の参照をあわせて確認し、各チャンネルが動画フィード以外でどのようにお知らせを発信しているかを比較します。
- チャンネル横断の投稿分析: 正規化された投稿をチャンネル情報と投稿日時でグループ化し、既知のチャンネル群のコミュニティ投稿の活動を比較します。
YouTube Community Posts API 活用のヒント
- 対応しているYouTubeホスト上の完全なチャンネルURLを送信してください。動画、投稿、再生リストのURLや、URLではない単なる値は、公開チャンネル入力の仕様を満たさずエラーになります。
- results_limit はすべてのURLに適用されるため、複数チャンネルのリクエストは規模を意識して設定してください。3チャンネルに20を指定すると、最大60件の保存済み投稿をリクエストすることになります。
- 公開コミュニティタブがないチャンネルや、表示されるフィードが短いチャンネルではレコードが少なくなることがあるため、results_limit は上限として扱ってください。
- cursor は GET /v1/tasks/{task_id} でのみ使用してください。取得元の続きの処理は内部で行われ、このエンドポイントの公開リクエストパラメータではありません。
- 保存したレコードは投稿IDで重複排除し、IDがない場合はURLを使用してください。複数の送信チャンネルを統合する場合は extra.input_url を保持してください。
- 後段で利用する前に text、media、created_at を確認してください。現在の正規化レコードには、アンケートの選択肢や埋め込み動画の添付メタデータは保持されません。
関連API
YouTube Community Posts API 以外に別の種類の公開YouTubeデータが必要な場合は、これらのAPIをご利用ください。
- YouTube Channel Videos API — チャンネルURLから、ショートとライブ配信を除く通常の公開動画を取得します。
- YouTube Transcripts API — 取得可能なプレーンテキストの文字起こしを取得します。言語は任意で指定できます。
- YouTube Channels API — 公開チャンネルのアカウント情報、画像、認証状態、表示中のオーディエンス統計を取得します。
- YouTube Videos API — 既知の動画またはショートのURLから、メタデータ、サムネイル、再生時間、エンゲージメントを取得します。
- YouTube Community Post API — リンクから1件のコミュニティ投稿を読み取り、全文、添付画像、高評価数、投稿したチャンネルを返します。
- YouTube Community Post Comments API — コミュニティ投稿のリンクから、その下のコメントを収集し、コメントしたチャンネル、高評価数、返信数を返します。
- YouTube Comments API
- YouTube Shorts API
- YouTube Search API
- YouTube Channel Live Videos API
- YouTube Comment Replies API
- YouTube Hashtag Search API
- YouTube Playlist Videos API
- YouTube Trending Shorts 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