TikTokTikTok Search APITikTok Top Search APITikTok Photo Carousel APIキーワード検索

TikTok Search API:動画とフォトカルーセルを検索する方法

SocQでTikTokの動画とフォトカルーセルをまとめてリサーチ。キャプション、クリエイター、メディア、エンゲージメント数を取得し、フィルターやJSON・CSVエクスポートのコードも紹介します。

SocQ2026年10月16日更新約8分で読めます

SocQを使えば、TikTokの動画とフォトカルーセルをまとめてリサーチできます。1つのキーワードに関するキャプション、クリエイター、メディアのリンク、エンゲージメント数を取得し、動画のデモ、レシピカード、画像ガイドを同じトピックのデータセットに整理できます。

SocQ TikTok Top Search APIは、キーワードで公開されている動画とフォトカルーセルを検索します。このガイドでは、リクエスト、結果フォーマットの扱い方、投稿と順序付きの画像リンクのエクスポートを説明します。

結論: 必須の query を指定して POST /v1/tiktok/top-search にリクエストを送ります。タスクが成功したら data.results.items を読み取ります。動画には type=video、画像投稿には type=photo_carousel を使います。カルーセルの画像エントリは media に入っています。

コンテンツ形式に合った検索エンドポイントを選ぶ

起点SocQのエンドポイント結果の範囲
キーワード、動画のみTikTok Search動画検索ワークフロー
キーワード、動画と画像投稿TikTok Top Searchtype で区別される混合の結果
投稿URLが分かっているTikTok Videos指定したコンテンツを取得
サウンドIDが分かっているTikTok Song Videosそのサウンドに関連する動画を検索

Top Searchは、キーワードに該当する既存の投稿を返します。フォト投稿を扱うには、結果から type=photo_carousel を選び、media にある画像を読み取ります。

キーワードでTikTokを検索する

SOCQ_API_KEY を設定し、上限を20件にした検索を送信します。

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}'

data.task_id を TASK_ID として保存し、そのタスクを照会します。

curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
  -H "Authorization: Bearer $SOCQ_API_KEY"

ステータスが queued、running、retrying の間は、間隔を空けて確認を続けます。succeeded になったら data.results.items を読み取り、failed の場合は data.error_message を確認します。結果が has_more=true なら、next_cursor をたどって保存済みの残りのページを読み取ります。

タスク結果のカーソルは、保存済みのレコードを読み取るためのものです。収集の上限は、送信した results_limit で決まります。クライアント側でタイムアウトした場合は、既存のタスクIDで照会を再開してください。

ソート、公開期間フィルター、リージョンを設定する

パラメータ指定できる値または範囲意味
query必須。空でないキーワードまたはフレーズ検索対象
sort_byrelevance、date、likes結果の並び順の指定。デフォルトは relevance
published_withinday、week、month、three_months、six_months任意の公開時期フィルター
regionUS などの2文字コード検索時にアクセスできるコンテンツ
results_limit1から2000までの整数。デフォルトは100返されるすべてのコンテンツ形式を合わせた上限

day は昨日、week は今週、month は今月を選択します。この3つはカレンダー上の期間です。three_months と six_months は、それぞれ直近の3か月と6か月を選択します。

region は、その検索でアクセスできるコンテンツを変えます。region=US はリクエスト条件として保存し、クリエイターの所在地は別の地理的な根拠で確認してください。

たとえば、20件の結果にフォトカルーセルが8件含まれていれば、形式で絞り込むとフォト投稿は8件になります。results_limit は両方の形式を合わせて数えるため、フォト投稿の件数はそのときの収集結果の分布によって決まります。

動画とフォトカルーセルの結果を読み取る

次の動画と5枚構成のカルーセルの例で、各結果フォーマットの読み取り方を示します。

確認するフィールド動画のレコードフォトカルーセルのレコード
id76785360685509706387685189869970246926
typevideophoto_carousel
author.usernamepatrickmcgee62coffeewithcandace
duration_seconds5.247null
メディアエントリ動画1本画像5枚

標準のレコードでは、キャプションは text、メディアは media、サウンド情報は audio、エンゲージメント数は metrics に格納されます。以降の照会では、それぞれのタスクが返したレコードを使って処理してください。

カルーセルの画像は、返されたメディアの順序どおりに読み取ります。duration_seconds がnullなら再生時間が提供されていないことを、指標がnullなら計測値が提供されていないことを意味します。返された0はそのまま保持し、再生数と閲覧数はそれぞれのフィールドで分けて扱ってください。

Pythonで検索結果とカルーセル画像をエクスポートする

次の標準ライブラリのみのヘルパーを socq_collect.py として保存します。

import json
import os
import time
from urllib.parse import urlencode
from urllib.request import Request, urlopen

BASE = "https://api.socq.ai/v1"
PENDING = {"queued", "running", "retrying"}

def api(method, path, payload=None):
    body = json.dumps(payload).encode("utf-8") if payload is not None else None
    request = Request(
        BASE + path, data=body, method=method,
        headers={
            "Authorization": "Bearer " + os.environ["SOCQ_API_KEY"],
            "Content-Type": "application/json",
        },
    )
    with urlopen(request, timeout=60) as response:
        result = json.load(response)
    if result.get("code") != 200:
        raise RuntimeError(result)
    return result["data"]

def collect(endpoint, payload):
    task_id = api("POST", "/" + endpoint, payload)["task_id"]
    print("Task:", task_id, flush=True)
    path = "/tasks/" + task_id
    deadline = time.monotonic() + 600
    data = api("GET", path + "?limit=100")
    while data["status"] in PENDING:
        if time.monotonic() >= deadline:
            raise TimeoutError("Resume GET " + path + "; do not resubmit automatically")
        time.sleep(2)
        data = api("GET", path + "?limit=100")
    if data["status"] != "succeeded":
        raise RuntimeError(data.get("error_message") or data["status"])

    items, seen_cursors = [], set()
    while True:
        if time.monotonic() >= deadline:
            raise TimeoutError("Resume pagination for " + task_id)
        page = data["results"]
        items.extend(page["items"])
        if not page["has_more"]:
            return task_id, items
        cursor = page.get("next_cursor")
        if not cursor or cursor in seen_cursors:
            raise RuntimeError("Missing or repeated result cursor")
        seen_cursors.add(cursor)
        data = api("GET", path + "?" + urlencode({"limit": 100, "cursor": cursor}))
        if data["status"] != "succeeded":
            raise RuntimeError("Task is not ready for result pagination")

次のコードを、同じディレクトリに export_search.py として保存します。

import csv
import json
from socq_collect import collect

payload = {"query": "coffee", "sort_by": "relevance", "results_limit": 20}
task_id, records = collect("tiktok/top-search", payload)
with open("tiktok-search.json", "w", encoding="utf-8") as f:
    json.dump({"task_id": task_id, "input": payload, "items": records},
              f, ensure_ascii=False, indent=2)

def csv_cell(value):
    if value is None:
        return ""
    if isinstance(value, str) and value.lstrip().startswith(("=", "+", "-", "@")):
        return "'" + value
    return value

def write_csv(path, fields, rows):
    with open(path, "w", encoding="utf-8-sig", newline="") as f:
        writer = csv.DictWriter(f, fieldnames=fields)
        writer.writeheader()
        writer.writerows({k: csv_cell(v) for k, v in row.items()} for row in rows)

posts, images, seen_ids = [], [], set()
for item in records:
    post_id = item.get("id")
    if post_id is not None:
        if str(post_id) in seen_ids:
            continue
        seen_ids.add(str(post_id))
    metrics = item.get("metrics") or {}
    posts.append({"post_id": post_id, "type": item.get("type"),
                  "text": item.get("text"), "url": item.get("url"),
                  "username": (item.get("author") or {}).get("username"),
                  "published_at": item.get("published_at"),
                  "likes_count": metrics.get("likes_count"),
                  "views_count": metrics.get("views_count"),
                  "collected_at": item.get("collected_at")})
    if item.get("type") == "photo_carousel":
        for position, media in enumerate(item.get("media") or [], start=1):
            if media.get("type") == "image":
                images.append({"post_id": post_id, "media_position": position,
                               "image_url": media.get("url"),
                               "width": media.get("width"), "height": media.get("height")})

write_csv("tiktok-search.csv", ["post_id", "type", "text", "url", "username",
          "published_at", "likes_count", "views_count", "collected_at"], posts)
write_csv("tiktok-carousel-images.csv", ["post_id", "media_position", "image_url",
          "width", "height"], images)
python3 export_search.py

JSONには、収集したすべてのレコードが保持されます。投稿のCSVはIDで投稿を重複排除し、画像のCSVには投稿IDとメディアの位置を保存するため、カルーセルの順序を復元できます。IDのないレコードは別に保持されます。他のデータセットと結合する前に、元の投稿を確認してください。

元の投稿を開き、そのメディアにアクセスするため、投稿URLとメディアURLの両方を保存しておいてください。画像のアドレスがない場合は、空の値のまま保持します。CSVでは、数式のように見える公開テキストをエスケープしています。すべての桁を保持するため、投稿IDはテキストとしてインポートしてください。

収集した投稿をトピックレビューに活用する

コーヒーレシピのレビューであれば、収集した投稿を画像カードと動画デモに分類します。トピックを割り当てる際は、キャプションとメディアの両方を確認してください。画像内に表示されている全文を抽出するには、別途テキスト認識のステップが必要です。

比較ごとに、クエリ、フィルター、収集時刻を記録しておきます。ローカルでいいね順に並べ替えた結果は「このサンプル内のいいねランキング」と表記し、サンプルのサイズと収集範囲を併記してください。

音声を起点にした探索については、TikTokミュージックチャートのチュートリアルを参照してください。プロフィール、特定の動画、コメントのワークフローについては、TikTokスクレイピングガイドをご覧ください。

動画と画像を1つのリサーチデータセットにまとめる

SocQのTop Searchは、動画とフォトカルーセルを同じリクエストのワークフローで扱い、標準フィールドで各形式を判別できます。エクスポートのコードは投稿テーブルと順序付きの画像テーブルの両方を作成するので、トピックライブラリやレビュー画面に必要なソースリンクとスライドの位置を用意できます。

Top Searchを開いてキーワードを試す。

よくある質問(FAQ)

TikTok Search APIでフォトカルーセルを取得できますか?

Top Searchは動画とフォトカルーセルを返し、type で区別します。メディアは media に入っています。別のTikTok Searchエンドポイントは、動画検索用です。

TikTokのフォトだけを検索できますか?

結果を収集してから、type=photo_carousel を選択します。フォトの絞り込みはアプリケーション側で行い、収集の上限は両方の形式を合わせて数えられます。

Top Searchは検索キーワードのランキングや検索ボリュームを返しますか?

Top Searchは指定したキーワードを受け取り、投稿のレコードを返します。キーワードの検索ボリュームやトレンドクエリのリストは別のデータ種別で、このレスポンスには含まれません。

regionはクリエイターの居住地を示しますか?

region は、その検索でアクセスできるコンテンツを調整するものです。クリエイターの居住地や投稿場所は、別途確認してください。

キーワードに一致するすべての投稿を取得できますか?

エンドポイントは、その検索で選ばれた投稿を results_limit を上限として返します。すべての結果ページを読み取れば、そのタスクの保存済みの結果セット全体を取得できます。トピックのカバー範囲は、それらのレコードによって決まります。

フォト投稿に再生時間や再生数がないのはなぜですか?

フォトカルーセルは画像エントリとして読み取ってください。再生時間や再生数の計測値がない場合はnullのまま保持し、ソースが0を返した場合は0のまま保持します。

このAPIでカルーセルを投稿できますか?

Top Searchは、既存の公開コンテンツを取得するものです。カルーセルの投稿には、別の投稿用ワークフローを使います。このエンドポイントの入力、フィールド、課金については、Top Search APIのページを参照してください。

TIKTOK API

公開TikTokのURLでワークフローを試す

公開データの入力を送信すると、取得元をたどれるコンテキスト付きの正規化レコードを受け取れます。

TikTokのAPIを見る