tiktok/
top-search

キーワードでTikTokの動画とフォトカルーセルを検索し、キャプション、クリエイターの詳細、メディアリンク、エンゲージメント数を1つのJSONリストにまとめて返します。

TikTok Top Search API

動画とフォトカルーセル
キーワード検索
並べ替えと公開期間フィルター
結果1件あたり0.7クレジット
準備完了
準備完了

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

README

SocQ 編集 · 更新

TikTok Top Search

TikTokのトップ検索では、キーワードやフレーズに関連する動画と、複数の画像で構成される投稿であるフォトカルーセルがまとめて表示されます。キャプション、クリエイターのアカウント情報、メディア、反応数を使うと、同じトピックが異なるコンテンツ形式でどのように表れているかを比較できます。

TikTok Top Search API の主な機能

  • 動画と画像投稿を1回の検索で取得同じキーワード検索で動画投稿とフォトカルーセルの両方を取得でき、type フィールドで形式を識別できます。両方を1つのデータセットにまとめることも、確認用に分けることもできます。
  • 並び順と公開期間の選択一致したコンテンツを関連度、公開日、いいね数で並べ替え、公開日時のフィルターを加えて、確認したい種類のコンテンツに絞り込めます。
  • コンテンツをクリエイターや反応数とあわせて確認各結果にはキャプション、クリエイター情報、メディアリンク、取得可能な反応数がまとめて含まれるため、投稿のテーマや形式を投稿したアカウントと関連付けて確認できます。

TikTok Top Search API のパラメータ

パラメータ必須説明
query必須必須。探したい内容を表すキーワードまたはフレーズです(例:coffee、home workout)。TikTok投稿のURLではなく、検索テキストを入力してください。
sort_by任意任意。並び順です。relevance は関連度の高い順、date は公開日順、likes はいいね数順になります。デフォルトは relevance です。
published_within任意任意。公開日時の範囲です。day は昨日、week は今週、month は今月、three_months は過去3か月、six_months は過去6か月を選択します。空欄にすると、公開日時による追加のフィルターは適用されません。
region任意任意。US や GB のような2文字の地域コードで、検索で取得できるコンテンツが変わります。返された投稿やクリエイターがその国に所在することを示すものではありません。
results_limit任意任意。コンテンツレコードの最大数で、1〜2000の範囲で指定します。デフォルトは100です。動画とフォトカルーセルはどちらもこの合計に含まれ、返される件数がこれより少ない場合もあります。

TikTok Top Search API の使い方

リクエストを送るとバックグラウンドの収集タスクが開始されるため、最初のレスポンスでは完成したデータではなくタスクIDが返されます。そのIDを使って進行状況を確認し、結果を取得します。

  1. テーマのキーワードを入力し、relevance、date、likes のうち最も役立つ並び順を選んで結果の上限を設定します。公開期間や region は必要な場合にのみ追加してください。
  2. 例を実行する前に、$SOCQ_API_KEY をご自身のAPIキーに置き換えるか、その環境変数を設定してください。以下の Authorization ヘッダーを付けてJSON入力を POST /v1/tiktok/top-search に送信し、レスポンスの 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/top-search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"coffee","sort_by":"relevance","results_limit":20}'

TikTok Top Search API の主なユースケース

  • トピック別コンテンツコレクションの作成: coffee のようなテーマで検索し、キャプション、クリエイターのハンドル、リンク、コンテンツの種類を、動画と画像投稿の両方の事例を含む確認用の表に保存します。
  • 返された投稿間での反応数の比較: 取得可能ないいね数、コメント数、シェア数を各投稿の形式や公開日時と組み合わせて比較シートを作成します。事例の選定方法がわかるよう、クエリとフィルターも保持してください。

TikTok Top Search API 活用のヒント

  • 結果を表示する際は、まず type と media を確認してください。photo_carousel は画像投稿を意味するため、動画プレーヤーではなく画像ギャラリーで表示してください。
  • 複数のキーワードで収集する場合は、投稿IDで重複する一致を排除し、各収集に対応するキーワードを保持して、同じ投稿を誤って複数回数えないようにしてください。
  • ワークフローが動画しか扱えない場合は TikTok Search を、動画と画像投稿の両方が必要な場合は Top Search を使い、表示側で両方の形式に対応してください。
  • 写真の結果に再生時間や再生数がない場合は、0秒の動画や未視聴の投稿と解釈せず、その数値を空のままにしてください。

TikTok Top Search API 以外に別の種類の公開TikTokデータが必要な場合は、これらのAPIをご利用ください。

  • TikTok Profiles API — ユーザー名から、公開プロフィールのアカウント情報、プロフィール文、アカウント属性、オーディエンス数を取得します。
  • TikTok Hashtags API — 指定したハッシュタグの公開動画、クリエイター、メディア、サウンド、エンゲージメントを取得します。
  • TikTok Comments API — 公開トップレベルコメント、投稿者、エンゲージメント、メンション、クリエイターとのやり取りを示すフラグを取得します。
  • TikTok Videos API — 動画URLから、クリエイター、キャプション、メディア、音楽、タグ、メンション、エンゲージメントを取得します。
  • TikTok Search API — キーワードで公開動画を検索します。対応する並び順と公開日のフィルターを指定できます。
  • TikTok Live Room Info API — ルームIDと配信者IDの組み合わせで既知のライブ配信ルーム1件を検索し、ステータス、配信者情報、カバーメディア、視聴者数を返します。

他のプラットフォームを見る

TikTokのデータを、対応する他のソーシャルプラットフォームの公開データと組み合わせられます。

TikTok Top Search API — よくある質問

TikTok Top Search APIは、キーワードやフレーズから公開TikTok動画とフォトカルーセルを検索するためのプログラムインターフェースです。任意の並べ替えと公開日時フィルターを使って、キャプション、クリエイター、メディアリンク、反応数を返します。

複数の画像を含み、視聴者がスワイプして見られるTikTokの画像投稿です。結果では type=photo_carousel でその形式を識別でき、media に画像の項目が含まれます。

TikTok Search は動画のみを返しますが、Top Search は動画とフォトカルーセルの両方を含めることができます。収集や表示で画像投稿も扱う必要があるかどうかで選んでください。

写真のみを指定する入力フィルターはありません。取得後に type が photo_carousel のレコードを選択してください。結果の上限は独自の形式フィルタリングの前に適用されるため、残る写真の件数は少なくなる場合があります。

なりません。region は検索で取得できるコンテンツを変えるもので、各結果の地理的な発信元を示すものではありません。クリエイターの所在地や投稿地のフィールドの代わりとして使わないでください。

得られるとは限りません。results_limit は返される件数の上限であり、一致するすべてのTikTok投稿が含まれることを保証するものではありません。検索では、リクエストした上限より少ないレコードが返されることがあります。

返されたコンテンツレコード1件につき、動画・フォトカルーセルを問わず0.7クレジットです。基本料金はかかりません。上限を100にした場合の見積もりは70クレジットで、20件のレコードが返された場合は14クレジットです。