TikTok User Live
TikTokアカウントのライブ配信状況は特定の時点で配信しているかどうかを示し、配信中の場合はルームのタイトル、カバー画像、視聴者数がわかることもあります。クリエイターのアカウント情報と取得時刻をステータスとあわせて保持すると、どのアカウントが配信していたか、情報がどれだけ新しいかを把握しやすくなります。
TikTok User Live API の主な機能
- 配信中かオフラインかを判別成功した検索では、配信中なら true、オフラインなら false の is_live が必ず返されます。配信していないアカウントも結果から消えるのではなく、ステータスのレコードとして残ります。
- 配信中のルームの詳細を確認配信中のレコードには、ルームのタイトル、クリエイター名、カバー画像、視聴者数が含まれる場合があり、配信中かどうかだけでなく配信の情報も得られます。
- ルームIDではなくアカウントのハンドルから開始別のライブ配信ルーム詳細の検索で必要となる room_id と user_id を事前に調べなくても、1回のリクエストで複数の公開ユーザー名を検索できます。
TikTok User Live API のパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
usernames | 必須 | 必須。1つ以上の公開アカウントのハンドルのリストです(@ の有無は問いません)。Playgroundでは1行に1つずつユーザー名を入力し、JSONではプロフィールURLではなく ["thejustalex", "@tiktok"] のような配列を使用してください。 |
TikTok User Live API の使い方
リクエストを送るとバックグラウンドの収集タスクが開始されるため、最初のレスポンスでは完成したデータではなくタスクIDが返されます。そのIDを使って進行状況を確認し、結果を取得します。
- プロフィールやライブ配信ルームのリンクではなく、1つ以上の公開ユーザー名を用意します。アカウントのプロフィールから @ の後ろのハンドルをコピーできます。
- 例を実行する前に、$SOCQ_API_KEY をご自身のAPIキーに置き換えるか、その環境変数を設定してください。以下の Authorization ヘッダーを付けてJSON入力を POST /v1/tiktok/user-live に送信し、レスポンスの task_id を保存します。
- 保存したIDで GET /v1/tasks/{task_id} を使い、進行状況を確認します。queued は待機中、running は収集中、retrying は再試行中を意味します。succeeded になるまで待ってから結果を読み取ってください。タスクが failed の場合は、error_message で理由を確認します。
- タスクが成功したら data.results.items を読み取ります。このリストの各項目は、確認に成功した1つのアカウントのステータスを表します。リストが空の場合は、タスクが完了したもののレコードが返されなかったことを意味します。
- data.results.has_more が true の場合、next_cursor の値は保存済み結果の別ページを示すマーカーです。その値を変更せずに GET /v1/tasks/{task_id}?cursor=... の cursor パラメータにコピーし、has_more が false になるまで続けます。
curl -X POST "https://api.socq.ai/v1/tiktok/user-live" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"usernames":["thejustalex"]}'TikTok User Live API の主なユースケース
- アカウントのライブ配信状況ボードの作成: 各クリエイター、配信中・オフラインのステータス、取得日時を含む表を作成し、指定したアカウントのうち直近の観測時点でどれが配信していたかを確認できるようにします。
- 配信中ルームの確認リストの作成: is_live=true のレコードを抽出し、ルームのリンク、タイトル、視聴者数をまとめて、開いて確認する配信中ルームのリストを作成します。
TikTok User Live API 活用のヒント
- 重複を含むハンドルのリストを送信する前に、先頭の @ を取り除き、大文字・小文字を区別せずに重複を排除してください。そうすれば tiktok と @TikTok で入力数の見積もりが膨らむことはありません。
- レコードが is_live=false の場合は、アカウントの検索に失敗したと報告するのではなく、オフラインとして表示し、取得できないルームのフィールドは空のままにしてください。
- 自分で更新するステータスボードでは、以前の結果を直前の観測と取り違えないよう、ステータスの横に collected_at を表示してください。
- 対応する room_id と user_id をすでに持っていて、ルーム単体を検索したい場合は、それらのIDを usernames フィールドに送信するのではなく、TikTok Live Room Info を使用してください。
関連API
TikTok User Live API 以外に別の種類の公開TikTokデータが必要な場合は、これらのAPIをご利用ください。
- TikTok Profiles API — ユーザー名から、公開プロフィールのアカウント情報、プロフィール文、アカウント属性、オーディエンス数を取得します。
- TikTok Videos API — 動画URLから、クリエイター、キャプション、メディア、音楽、タグ、メンション、エンゲージメントを取得します。
- TikTok User Videos API — ユーザー名から、プロフィールフィードの公開動画をキャプション、クリエイター、メディア、タイムスタンプ、エンゲージメント、元のアカウント情報とともに取得します。
- TikTok Live Room Info API — ルームIDと配信者IDの組み合わせで既知のライブ配信ルーム1件を検索し、ステータス、配信者情報、カバーメディア、視聴者数を返します。
- TikTok Trending Feed API — 地域ごとの現在の公開動画フィードを取得し、クリエイター、キャプション、カバー、タイムスタンプ、表示中のエンゲージメントの各フィールドを返します。
- TikTok Live Shopping API — ライブ配信のショッピングバッグにある商品を、現在の価格と販売数とともに一覧で取得します。
- TikTok Hashtags API
- TikTok Comments API
- TikTok Search API
- TikTok Comment Replies API
- TikTok Followers List API
- TikTok Following List API
- TikTok Video Transcript API
- TikTok Search Users API
- TikTok Song API
- TikTok Song Videos API
- TikTok Popular Songs API
- TikTok Top Search 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 Fake Views Checker API
- TikTok Comment Keywords API