TikTok Live Room Info
TikTokライブ配信ルーム情報は、配信中の公開ルーム1件を特定時点で捉えたもので、タイトル、ステータス、配信者のアカウント情報、カバー画像、表示中の視聴者数といいね数を含みます。これらのフィールドは、既知のルームについて、配信状況の確認、視聴者のスナップショット、ルーム情報の補完、タイムスタンプ付きのレポートに活用できます。
TikTok Live Room Info API の主な機能
- ルームIDと配信者IDによる検索room_id と対応する配信者の user_id から既知のライブ配信ルームを1件特定し、正規化された live_room レコードを最大1件返します。
- ルームと配信者の情報現在のルームのタイトルとステータスに加え、配信者の公開ID、ユーザー名、表示名を返します。
- 視聴者とカバー画像のスナップショット表示中の視聴者数、いいね数、公開カバー画像、取得時のタイムスタンプを取得し、特定時点の値として解釈できるようにします。
TikTok Live Room Info API のパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
room_id | 必須 | 必須。空でないライブ配信ルームの識別子です。現在のTikTokライブ配信セッションを公開しているソースから取得した数値の識別子を、文字列として指定してください。 |
user_id | 必須 | 必須。ルームの配信者を表す、空でない数値のTikTokユーザー識別子です。文字列として指定し、同じルームと組み合わせて使用します。 |
TikTok Live Room Info API の使い方
配信中の既知のルーム1件の識別子を組み合わせて非同期の検索を送信し、タスク結果から正規化されたスナップショットを読み取ります。
- 現在のTikTokライブ配信セッションを公開しているソースから room_id を取得し、同じ情報源または TikTok Profiles の結果から対応する配信者の user_id を取得します。
- 空でない文字列の識別子を両方とも /v1/tiktok/live-room-info に POST します。
- status が succeeded または failed になるまで /v1/tasks/{task_id} をポーリングします。
- /v1/tasks/{task_id}?limit=50 から data.results.items を読み取ります。特定できたルームのレコードは最大1件で、通常の next_cursor は results.has_more が true の場合にのみ使用します。
curl -X POST "https://api.socq.ai/v1/tiktok/live-room-info" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"room_id":"7523685855395842871","user_id":"6742945285876515845"}'
# Poll GET /v1/tasks/{task_id}, then read data.results.items from /v1/tasks/{task_id}?limit=50.TikTok Live Room Info API の主なユースケース
- 特定時点の配信状況の確認: 返された status、タイトル、ルームID、collected_at の値を使い、既知のルームについて取得できたスナップショットを確認します。
- 視聴者スナップショットのレポート: viewers_count と likes_count を collected_at とともに記録し、既知の配信中に異なる時点で得られた観測値を比較します。
- ライブ配信ルームの情報補完: 既存のライブ配信ルームのレコードに、配信者のID、ユーザー名、表示名、ルームのタイトル、ステータス、カバー画像を追加します。
TikTok Live Room Info API 活用のヒント
- room_id は、同じ配信中セッションの配信者の user_id と組み合わせてください。ルームとユーザーが一致しない場合、レコードが返されないか、入力に起因するソースエラーが返されることがあります。
- 大きな数値のTikTok IDがクライアントやデータベースで丸められないよう、両方の識別子を文字列のまま保持してください。
- 検索はルームが配信中と見込まれる間に実行し、結果が空の場合はオフラインのルームのレコードとしてではなく、終了、利用不可、無効、または不一致として扱ってください。
- ステータスと指標の観測時刻には collected_at を使用してください。正規化レコードでは created_at は null、url は空になります。
関連API
TikTok Live Room Info API 以外に別の種類の公開TikTokデータが必要な場合は、これらのAPIをご利用ください。
- TikTok Profiles API — ユーザー名から、公開プロフィールのアカウント情報、プロフィール文、アカウント属性、オーディエンス数を取得します。
- TikTok Hashtags API — 指定したハッシュタグの公開動画、クリエイター、メディア、サウンド、エンゲージメントを取得します。
- TikTok Search API — キーワードで公開動画を検索します。対応する並び順と公開日のフィルターを指定できます。
- TikTok User Videos API — ユーザー名から、プロフィールフィードの公開動画をキャプション、クリエイター、メディア、タイムスタンプ、エンゲージメント、元のアカウント情報とともに取得します。
- TikTok Search Users API — キーワードで公開TikTokアカウントを検索します。
- TikTok Top Search API — キーワードで動画と画像投稿を検索し、キャプション、クリエイター、インタラクション数を返します。
- TikTok Comments API
- TikTok Videos API
- TikTok Comment Replies API
- TikTok Followers List API
- TikTok Following List API
- TikTok Trending Feed API
- TikTok Video Transcript API
- TikTok Song API
- TikTok Song Videos API
- TikTok Popular Songs API
- TikTok User Live API
- TikTok Audience Demographics API
- TikTok Similar Accounts API
- TikTok Reposts API
- TikTok Playlists API
- TikTok Hashtag Views API
- TikTok Sound Search API
- TikTok Live Search API
- TikTok Photo Search API
- TikTok Trending Searches API
- TikTok Creator Search Insights API
- TikTok Live Ranking API
- TikTok Live Shopping API
- TikTok Fake Views Checker API
- TikTok Comment Keywords API