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を使って進行状況を確認し、結果を取得します。
- テーマのキーワードを入力し、relevance、date、likes のうち最も役立つ並び順を選んで結果の上限を設定します。公開期間や region は必要な場合にのみ追加してください。
- 例を実行する前に、$SOCQ_API_KEY をご自身のAPIキーに置き換えるか、その環境変数を設定してください。以下の Authorization ヘッダーを付けてJSON入力を POST /v1/tiktok/top-search に送信し、レスポンスの 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/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秒の動画や未視聴の投稿と解釈せず、その数値を空のままにしてください。
関連API
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 Comment Replies API
- TikTok Followers List API
- TikTok Following List API
- TikTok User Videos API
- TikTok Trending Feed API
- TikTok Video Transcript API
- TikTok Search Users 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