TikTok検索の週次レポートは、前回の実行後に今回の取得結果へどの動画が加わったかを示せると便利です。そのためには、すでに見つかった動画のIDを保存し、新しい結果をCSVに追加するだけで十分です。以下では、TikTok Scraper APIを使った再現可能なPythonスクリプトを紹介します。キーワードで動画を検索し、ドキュメントに記載された2種類のレスポンス形式を解析して、IDのローカルデータベースを管理します。
目的:検索結果全体を見直すのではなく、新しい投稿を見つける
サポート担当者、市場調査担当者、コンテンツアナリストは、製品に関する検索語で公開動画を定期的に収集したい場合があります。毎回結果をすべてエクスポートすると、重複する動画で確認に手間がかかり、新しい投稿が処理済みの結果に埋もれてしまいます。IDのログを使えば、各実行結果を比較できます。CSVには、この処理で初めて見つかった動画と、レスポンスに含まれる主要な項目だけが記録されます。
このログで答えられるのは、限定的ながら実用的な問いです。つまり、今回のレスポンスに含まれ、保存済みのIDセットにはなかった項目は何か、ということです。手作業で確認するためのキューや、スプレッドシート、後続の分析へのデータ受け渡しに便利です。この取得結果が表すのは、指定したクエリに対するAPIの結果であり、TikTok上のすべての投稿を網羅するものではありません。
準備するもの
- Python 3.8以降。
- TikTok Scraper APIへのアクセスとライセンスキー。
- 意味を変えずに繰り返し使用できる検索語。たとえば製品名や特定のフレーズ。
キーはスクリプトファイルに書かず、環境変数JSONSCRAPER_TIKTOK_LICENSE_KEYに保存してください。以下の例では、APIの仕様に従って、リクエストパラメーターlicense_keyとしてキーを渡します。実行ログにキーを出力しないでください。
export JSONSCRAPER_TIKTOK_LICENSE_KEY="あなたのキー"
python -m pip install requests
Windows PowerShellでは、次のようにして現在のセッションに変数を設定できます。$env:JSONSCRAPER_TIKTOK_LICENSE_KEY="あなたのキー"。実際のシークレットをGitや共有CSVに追加しないでください。
連携:検索をリクエストしてJSONを正規化する
動画検索には、必須パラメーターkeywordを指定するGETルート/searchVideoがドキュメントに記載されています。リクエストでは、count、地域、並べ替え、期間フィルター、結果をページ送りするカーソルも指定できます。この最小限の例では、キーワード、取得件数、米国の地域設定のみを使用します。TikTok APIのルート一覧でパラメーターの正確な名前を確認できます。
検索レスポンスでは、データ構造に注意が必要です。配列aweme_listが空の場合があり、動画項目がsearch_item_listに含まれ、そのデータがaweme_info内にネストされている場合もあります。そのため、コードは両方の経路を確認してから項目を統合し、aweme_idで重複を除去します。これにより、JSONの解析に成功したのにレポートが誤って空になる事態を防ぎます。
import csv
import json
import os
from pathlib import Path
from datetime import datetime, timezone
import requests
BASE_URL = "https://tiktok.evelode.com/searchVideo"
KEYWORD = "製品名"
REGION = "US"
COUNT = 30
STATE_FILE = Path("seen_video_ids.json")
OUTPUT_FILE = Path("new_tiktok_videos.csv")
license_key = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")
if not license_key:
raise RuntimeError("JSONSCRAPER_TIKTOK_LICENSE_KEYを設定してください")
response = requests.get(
BASE_URL,
params={
"license_key": license_key,
"keyword": KEYWORD,
"count": COUNT,
"region": REGION,
},
timeout=60,
)
response.raise_for_status()
data = response.json()
# レスポンス例には外側のstatusと、ネストされたtiktokオブジェクトが含まれます。
if "status" in data and data["status"] != "ok":
raise RuntimeError("APIがok以外のステータスを返しました")
tiktok = data.get("tiktok") or {}
items = list(tiktok.get("aweme_list") or [])
for entry in tiktok.get("search_item_list") or []:
info = entry.get("aweme_info")
if isinstance(info, dict):
items.append(info)
# 現在のレスポンス内で、順序を保ちながら項目を一意にします。
current = {}
for item in items:
video_id = item.get("aweme_id")
if video_id:
current[str(video_id)] = item
if STATE_FILE.exists():
seen = set(json.loads(STATE_FILE.read_text(encoding="utf-8")))
else:
seen = set()
new_items = [(video_id, item) for video_id, item in current.items()
if video_id not in seen]
run_time = datetime.now(timezone.utc).isoformat()
fields = ["collected_at_utc", "query", "aweme_id", "created_at",
"author", "description", "share_url", "play_count",
"digg_count", "comment_count", "share_count"]
write_header = not OUTPUT_FILE.exists() or OUTPUT_FILE.stat().st_size == 0
with OUTPUT_FILE.open("a", newline="", encoding="utf-8") as f:
writer = csv.DictWriter(f, fieldnames=fields)
if write_header:
writer.writeheader()
for video_id, item in new_items:
author = item.get("author") or {}
stats = item.get("statistics") or {}
writer.writerow({
"collected_at_utc": run_time,
"query": KEYWORD,
"aweme_id": video_id,
"created_at": item.get("create_time"),
"author": author.get("unique_id") or author.get("nickname"),
"description": item.get("desc"),
"share_url": item.get("share_url"),
"play_count": stats.get("play_count"),
"digg_count": stats.get("digg_count"),
"comment_count": stats.get("comment_count"),
"share_count": stats.get("share_count"),
})
seen.update(current.keys())
STATE_FILE.write_text(json.dumps(sorted(seen)), encoding="utf-8")
print(f"レスポンス内の一意な動画:{len(current)}件、新規:{len(new_items)}件")
JSONに値がない項目は空のセルとして記録されます。個々のレコードにフィールドや指標が含まれない場合があるためです。このコードは欠損値をゼロに置き換えず、ゼロをデータ欠損として扱うこともありません。収集時刻と、APIがcreate_timeフィールドで返す投稿時刻は別々に記録されます。
変更の確認方法
- リクエストによって、指定したキーワードの検索結果ページが返されます。
- 正規化処理で、
aweme_listとsearch_item_list[].aweme_infoからレコードを集めます。 - 動画IDを使って、レスポンス内の重複を取り除きます。
- IDをローカルのJSONログと照合します。
- 新しいIDをCSVに追加し、次回実行に備えて見つかったID全体を保存します。


このプロセスを視覚化すると、スクリプトを同僚に引き継ぐ際に役立ちます。CSVは追記型のログ、JSONは重複排除の状態を保持するファイルです。これらはコードとは別に保管し、一緒にバックアップできます。チームでの実行やクラウド実行では、ローカルのJSONファイルを適切な永続ストレージに置き換え、並行実行で状態が上書きされないよう、アトミックな更新を検討してください。
再実行とページネーション
OSのスケジューラー、CIタスク、自動化ワークフローで定期実行できます。クエリの意味を変えずに維持するため、キーワードを変更する場合はそのバージョンを記録してください。異なるクエリは別々の取得結果になるため、同じログに混在させると解釈が難しくなります。簡潔さのため、このスクリプトでは1つのクエリを使用しています。複数のクエリをループで処理する場合は、各行にqueryフィールドを保存できます。
APIは検索結果のページ送りにcursorをサポートしています。ページネーションを追加する場合は、前のレスポンスから得たカーソルを渡し、それを内容を解釈しない不透明な値として保存します。必要なページを取得したら、処理を終了してください。countは要求する項目数を指定しますが、実際のレコード数はレスポンスに基づいて判断します。複数ページを取得しても、それは検索結果のページであり、プラットフォーム全体を網羅する保証にはなりません。
このスクリプトには、テキストの自動分類や「トレンド」の判定を意図的に含めていません。CSVを使えば、新たに見つかったレコードをすばやく特定できます。その後、アナリストがテーマ、意図、質問の種類などで分類し、実例を手作業で確認できます。言語モデルを連携する場合は、必要なテキスト項目だけを渡し、結果を検証して元レコードと結び付けられるよう、元のIDとともにカテゴリを返すよう指定してください。
確認事項とよくあるエラー
- HTTPエラー。
raise_for_status()は、成功範囲外のHTTPステータスコードで処理を停止します。状態ファイルを更新する前に、APIの利用可否、パラメーター、アカウントを確認してください。 - APIステータスが
ok以外。 レスポンスにトップレベルのstatusフィールドがあり、その値が異なる場合、スクリプトは結果の書き込み前に停止します。これにより以前のログが保たれ、エラーレスポンスを空の検索結果と誤認しにくくなります。 aweme_listが空。search_item_listも確認してください。コードは両方の構造に対応しています。- 実行間で動画が重複する。 検索結果ページに重なりがある場合は想定どおりです。IDがすでに保存されていれば、レポートには再度追加されません。
- 指標がない。 セルは空のままになります。計算時には、欠損値と実際のゼロを区別してください。
- 状態ファイルを失った。 スクリプトは返されたIDをすべて新規と判断します。
seen_video_ids.jsonをCSVと一緒にバックアップするか、永続データベースを利用してください。
自動化では、キーを含めずに、実行時刻、HTTPコード、APIステータス、解析したレコード数、新しいID数などの診断情報を保存してください。新しい動画がなかったのか、リクエストが失敗したのかを区別するのに役立ちます。スキーマを後から再確認する必要がある場合は、元の完全なレスポンスを別途アーカイブできます。チームの目的に応じて、アクセスと保存期間を制限してください。
結果
実行後には、ログにまだない動画IDと、説明、リンク、取得できた公開フィールドを含むCSVが作成されます。また、次回実行で照合するためのJSON状態ファイルも作成されます。この結果は、サポート、分析、コンテンツチームが確認するためのコンパクトなキューとして利用できます。APIの説明や利用方法はTikTok Scraper APIのページで確認し、検索パラメーターの正確な内容は公式ルート一覧で確認してください。