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 Search | type で区別される混合の結果 |
| 投稿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_by | relevance、date、likes | 結果の並び順の指定。デフォルトは relevance |
published_within | day、week、month、three_months、six_months | 任意の公開時期フィルター |
region | US などの2文字コード | 検索時にアクセスできるコンテンツ |
results_limit | 1から2000までの整数。デフォルトは100 | 返されるすべてのコンテンツ形式を合わせた上限 |
day は昨日、week は今週、month は今月を選択します。この3つはカレンダー上の期間です。three_months と six_months は、それぞれ直近の3か月と6か月を選択します。
region は、その検索でアクセスできるコンテンツを変えます。region=US はリクエスト条件として保存し、クリエイターの所在地は別の地理的な根拠で確認してください。
たとえば、20件の結果にフォトカルーセルが8件含まれていれば、形式で絞り込むとフォト投稿は8件になります。results_limit は両方の形式を合わせて数えるため、フォト投稿の件数はそのときの収集結果の分布によって決まります。
動画とフォトカルーセルの結果を読み取る
次の動画と5枚構成のカルーセルの例で、各結果フォーマットの読み取り方を示します。
| 確認するフィールド | 動画のレコード | フォトカルーセルのレコード |
|---|---|---|
id | 7678536068550970638 | 7685189869970246926 |
type | video | photo_carousel |
author.username | patrickmcgee62 | coffeewithcandace |
duration_seconds | 5.247 | null |
| メディアエントリ | 動画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は、動画とフォトカルーセルを同じリクエストのワークフローで扱い、標準フィールドで各形式を判別できます。エクスポートのコードは投稿テーブルと順序付きの画像テーブルの両方を作成するので、トピックライブラリやレビュー画面に必要なソースリンクとスライドの位置を用意できます。
よくある質問(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のページを参照してください。