tiktok/
user-live

ユーザー名から公開TikTokアカウントがライブ配信中かどうかを確認し、1回のリクエストで複数アカウントの配信中・オフラインのステータスと取得可能なルームの詳細を返します。

TikTok User Live API

ユーザー名でアカウントを確認
配信中・オフラインの結果
1リクエストで複数アカウント
結果1件あたり0.5クレジット
準備完了
準備完了

パラメータを入力してリクエストを送信してください。タスクのステータスと正規化された結果がここに表示されます。

README

SocQ 編集 · 更新

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. プロフィールやライブ配信ルームのリンクではなく、1つ以上の公開ユーザー名を用意します。アカウントのプロフィールから @ の後ろのハンドルをコピーできます。
  2. 例を実行する前に、$SOCQ_API_KEY をご自身のAPIキーに置き換えるか、その環境変数を設定してください。以下の Authorization ヘッダーを付けてJSON入力を POST /v1/tiktok/user-live に送信し、レスポンスの task_id を保存します。
  3. 保存したIDで GET /v1/tasks/{task_id} を使い、進行状況を確認します。queued は待機中、running は収集中、retrying は再試行中を意味します。succeeded になるまで待ってから結果を読み取ってください。タスクが failed の場合は、error_message で理由を確認します。
  4. タスクが成功したら data.results.items を読み取ります。このリストの各項目は、確認に成功した1つのアカウントのステータスを表します。リストが空の場合は、タスクが完了したもののレコードが返されなかったことを意味します。
  5. 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 を使用してください。

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のデータを、対応する他のソーシャルプラットフォームの公開データと組み合わせられます。

TikTok User Live API — よくある質問

TikTok User Live APIは、ユーザー名のリストを使って公開TikTokアカウントがライブ配信中かどうかを確認するためのプログラムインターフェースです。成功した検索ごとに配信中またはオフラインのステータスを返し、配信中の場合はクリエイター情報と取得可能なルームの詳細も返します。

確認した時点でアカウントが配信していなかったことを意味し、検索に失敗したわけではありません。成功したオフラインのレコードは is_live=false、status=offline となり、ルームのタイトル、視聴者数などのルームフィールドは空になる場合があります。

必要ありません。thejustalex や @thejustalex のようにアカウントのユーザー名を入力してください。room_id と user_id は、別の TikTok Live Room Info の入力項目です。

しません。タスクは実行時にステータスを確認して終了します。ステータスボードを更新したい場合は、ご自身のアプリケーションで改めて確認を実行し、新しい取得日時を保存する必要があります。

いいえ。0 は数値であり、null は数値が欠落していることを意味します。これらは区別して扱い、オフラインのレコードではルームの数値が空になると想定してください。

成功したオフラインの結果も含め、返されたステータス1件につき0.5クレジットで、基本料金はかかりません。たとえば、異なる3つのユーザー名の見積もりは1.5クレジットで、2つのアカウントがオフラインでも、3件のステータスが返されれば1.5クレジットになります。