Michael JohnsonコンテンツチームがTikTokの新しいテーマに気づくころには、競合他社がすでに話題にしていることがあります。よくある原因は単純です。検索を手作業で不定期に行い、見つけたリンクを共通の表や収集日、比較可能な指標もないままチャットに貼っているのです。変化をより早く捉えるには、検索語を記録し、取得した動画を定期的に保存し、実際に観測した結果だけを比較する、再現可能なプロセスに変えるのが有効です。
以下では、TikTok Scraper API jsonscraperを使ったPythonによるモニタリングの仕組みを紹介します。たとえば、投稿カレンダーのために複数のテーマに関連する検索語を追跡するエージェンシーや、特定のテーマの公開動画がどの程度の視聴数や反応を得ているか把握したいブランドに役立ちます。APIはTikTokの検索結果を返し、動画の説明、投稿者、投稿日、リンク、取得可能なカウンターを含みます。スクリプトは各レスポンスをアーカイブし、分析用のCSVスナップショットを作成します。
重要なのは、抽象的な「トレンド」を数えるのではなく、独自の観測記録における変化を追うことです。サンプルにどの動画が新たに加わったか、既知の動画の公開カウンターがどう変化したか、説明文にどんな表現が繰り返し現れるかを見ます。この方法なら、コンテンツチームが手動で評価できるテーマ候補を用意でき、各判断の根拠もたどれます。
手作業の検索が不十分なモニタリングになる理由
検索結果は変化するサンプルであり、安定した投稿カタログではありません。今日、あるキーワードで動画を10本見つけ、翌週に検索をやり直したとしても、結果を比較するのは困難です。以前のリンクが見つからなくなっているかもしれませんし、検索結果の構成も異なり、カウンターの値も更新されています。スナップショットを保存していなければ、特定の日にチームが何を見ていたのかを再現できません。
日次で簡単な収集を行うだけでも、問題の一部は解消できます。実行ごとに観測日、検索語、動画ID、投稿者、説明、リンク、取得可能な指標を保存します。次の実行時には動画IDでレコードを照合し、両方のバージョンに対応するフィールドがある場合に、カウンターの差を計算できます。
これらの値は、APIのレスポンスに含まれた動画の公開指標として扱う必要があります。TikTok全体のリーチや人気度を網羅したランキングではありません。検索結果は変わることがあり、フィールドが欠ける場合もあり、指標は収集時点に左右されます。したがって、このパイプラインの目的は再現可能な作業用サンプルを作り、検証候補を見つけることであり、ひとつの数値だけでテーマを普遍的なトレンドと認定することではありません。
仕組みの概要：検索、アーカイブ、比較
パイプラインは、キーワード設定、APIリクエスト、変更せずに保存するJSONアーカイブ、正規化したレコード層、変化をまとめるレポートの5要素で構成されます。こう分ければ、各ステップを個別に確認できます。レスポンスの構造が変わったり、一部のフィールドが欠けたりしても、生のJSONを再処理に利用できます。
- 検索語を決める。 商品、業界、またはオーディエンスの課題に関連する具体的な語句を使います。たとえば、キッチン家電ブランドなら「meal prep」「air fryer recipes」や特定の商品カテゴリー名を追跡できます。検索語の一覧は処理ロジックに直接埋め込まず、設定ファイルに保存します。
- 収集ルールを設定する。 スケジュールと、試験運用に適した少量の結果数を選びます。日付、地域、検索パラメーターを記録します。時系列で比較するには、1回で最大限の結果を集めようとするより、設定を毎回そろえることが重要です。
- 生のレスポンスを保存する。 実行時刻と検索語を添えてJSONを記録します。アーカイブがあれば、元のレコードを復元でき、APIを再度呼び出さずに正規化を修正できます。
- 確認できたフィールドを正規化する。 ID、キャプション、投稿日、投稿者、リンク、取得可能な統計値など、レスポンスに存在するフィールドだけを抽出します。欠損値はゼロで置き換えず、空欄のままにします。
- スナップショットを比較する。 動画をIDで照合し、各観測を個別に保存します。その後、アーカイブに新たに加わった投稿や、観測した指標値の差を確認できます。
最初のテストでは、2～3個の検索語と少数の結果を選びます。説明や投稿者が目的に合っているか、実際にどのフィールドが返されるか、同じ条件で結果がどの程度再現されるかを確認してください。その後で、検索語を増やし、スケジュール実行に移行するのがよいでしょう。
TikTok Scraper APIでリクエストできる内容
jsonscraperの公式ドキュメントでは、ルートGET /searchVideoはキーワードによる動画検索用とされています。必須パラメーターはkeywordです。ドキュメントに記載された任意パラメーターには、count、cursor、date_posted、sort_by、region、cache_timeoutがあります。date_postedにはthis-weekやthis-monthなど、sort_byにはrelevance、most-liked、date-postedなどが記載されています。パラメーターの正確な名前と用途は、TikTok APIのエンドポイントリファレンスで確認できます。
サービスのベースURLはhttps://tiktok.evelode.comで、キーはクエリパラメーターlicense_keyとして渡します。以下の例では、キーを環境変数JSONSCRAPER_TIKTOK_LICENSE_KEYに保存します。こうすれば、ソースコードに秘密情報を直接書き込まず、実行ログに出力することも避けられます。
レスポンスは、ネストされた構造を考慮して解析する必要があります。まず外側のstatusを確認し、次にtiktokオブジェクトを参照します。検索結果の動画リストには2つの形式があります。動画がtiktok.aweme_listに直接含まれる場合と、tiktok.search_item_listの各要素内のaweme_infoに含まれる場合です。検索レスポンスのaweme_listが空でも、search_item_listに動画が含まれることがあります。以下のスクリプトはどちらの形式にも対応しています。
動画オブジェクトには、ドキュメントおよび確認済みのレスポンス例で、aweme_id、desc、create_time、share_url、投稿者情報、statisticsオブジェクトなどのフィールドが示されています。統計には、視聴数、いいね、コメント、シェアのカウンターが含まれる場合があります。具体的なフィールドとその意味はレスポンスごとに確認する必要があり、コードは欠損フィールドを空欄のままにします。エンドポイントの例とドキュメント記載のパラメーターは、TikTok Scraper APIの説明で確認できます。
Pythonの実用例
この例はPython 3.8以降を対象とし、requestsパッケージを使います。python -m pip install requestsを実行してインストールしてください。コードをcollect_tiktok.pyという名前で保存し、環境変数にキーを設定して、検索語を指定してスクリプトを実行します。スクリプトはdataディレクトリを作成し、生のJSONを保存して、正規化した観測データをCSVに追加します。
import csv
import json
import os
import sys
from datetime import datetime, timezone
from pathlib import Path
from urllib.parse import urlparse
import requests
BASE_URL = "https://tiktok.evelode.com"
ARCHIVE = Path("data/raw")
OUT_CSV = Path("data/observations.csv")
def get_videos(tiktok):
"""確認済みのsearchVideoレスポンス形式から動画を集める。"""
videos = []
aweme_list = tiktok.get("aweme_list") or []
if isinstance(aweme_list, list):
videos.extend(item for item in aweme_list if isinstance(item, dict))
search_items = tiktok.get("search_item_list") or []
if isinstance(search_items, list):
for item in search_items:
if not isinstance(item, dict):
continue
aweme_info = item.get("aweme_info")
if isinstance(aweme_info, dict):
videos.append(aweme_info)
# 順序を保ち、IDのないレコードは残して重複を除去する。
result = []
seen = set()
for video in videos:
video_id = video.get("aweme_id")
if video_id and video_id in seen:
continue
if video_id:
seen.add(video_id)
result.append(video)
return result
def fetch(keyword, count=20, region="US"):
license_key = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")
if not license_key:
raise RuntimeError("環境変数にJSONSCRAPER_TIKTOK_LICENSE_KEYを設定してください")
params = {
"license_key": license_key,
"keyword": keyword,
"count": count,
"region": region,
"sort_by": "relevance",
}
response = requests.get(
f"{BASE_URL}/searchVideo", params=params, timeout=60
)
response.raise_for_status()
payload = response.json()
if payload.get("status") != "ok":
raise RuntimeError("TikTok APIがok以外のステータスを返しました")
tiktok = payload.get("tiktok")
if not isinstance(tiktok, dict):
raise RuntimeError("レスポンスにTikTokの結果オブジェクトがありません")
return payload, tiktok
def write_rows(keyword, videos, collected_at):
OUT_CSV.parent.mkdir(parents=True, exist_ok=True)
fields = [
"collected_at", "keyword", "aweme_id", "create_time",
"author_id", "author_name", "author_username", "description",
"share_url", "play_count", "digg_count", "comment_count",
"share_count", "collect_count",
]
write_header = not OUT_CSV.exists()
with OUT_CSV.open("a", newline="", encoding="utf-8") as file:
writer = csv.DictWriter(file, fieldnames=fields)
if write_header:
writer.writeheader()
for video in videos:
author = video.get("author") or {}
stats = video.get("statistics") or {}
writer.writerow({
"collected_at": collected_at,
"keyword": keyword,
"aweme_id": video.get("aweme_id"),
"create_time": video.get("create_time"),
"author_id": author.get("uid"),
"author_name": author.get("nickname"),
"author_username": author.get("unique_id"),
"description": video.get("desc"),
"share_url": video.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"),
"collect_count": stats.get("collect_count"),
})
def main():
if len(sys.argv) キーは環境変数で渡します。Bashのshellで現在のセッションに設定するコマンドは次のとおりです。
export JSONSCRAPER_TIKTOK_LICENSE_KEY="あなたのキー"
python collect_tiktok.py "meal prep"Windows PowerShellでは、$env:JSONSCRAPER_TIKTOK_LICENSE_KEY="あなたのキー"で現在のプロセスに変数を設定し、同じPythonファイルを実行できます。キーをリポジトリ、CSV、レスポンスアーカイブ、エラーメッセージに含めないでください。APIはキーをクエリパラメーターとして受け取るため、リクエストの完全なURLがHTTPクライアントやインフラのログに記録される可能性があります。秘密情報が記録されないよう、ログ設定を行ってください。
コードの読み方と結果の確認
fetch関数は、ドキュメントに記載されたパラメーターを渡し、HTTPステータス、外側のステータス、tiktokオブジェクトの有無を確認します。レスポンス本文が形式上正しいだけで成功とは見なしません。想定外の形式なら、わかりやすいエラーを出して処理を停止します。これにより、検索結果が空だった場合と、アクセスや構造に問題があった場合を区別しやすくなります。
get_videos関数は、直接含まれるaweme_listの要素と、search_item_list[].aweme_info内にあるレコードをまとめます。その後、動画が両方のコレクションに現れる場合に備え、aweme_idで重複を取り除きます。IDがない場合は、作り出した値を補うことなく、そのレコードを残します。これにより、元の結果を調べられます。
正規化では、安全な方法でネストされたオブジェクトを取得します。投稿者や統計情報が欠けていることがあるため、読み取る前に空のオブジェクトを代入します。CSVでは該当するセルが空欄になります。これは重要な区別です。空欄は観測時に値が取得できなかったことを意味し、ゼロはAPIが実際に返した数値を意味します。
アーカイブにはリクエストごとに個別のJSONファイルが保存されます。ファイル名にはUTC時刻と、検索語を安全な形式に変換した文字列が含まれます。CSVは分析用のフラットなレコードを保存し、生のJSONは新しいフィールドの確認や再処理に使う基準データとして残ります。この2種類の形式は、ローカルの試作にも、将来のデータベースやオブジェクトストレージへの移行にも便利です。
初回実行を検証するには、JSONを開き、statusがokであること、tiktokオブジェクトがあること、対応するコレクションの一方または両方に要素が含まれていることを確認します。次に、CSVのいくつかの値を元のオブジェクトと照合します。特に、カウンターが不正な文字列になっていないこと、投稿日が元の値のまま保存されていること、リンクとIDが同じ動画に対応していることを確認してください。
正常なレスポンスに動画が含まれていない場合は、コードの障害ではなく、空の実行結果として記録します。外側のステータスやHTTPレスポンスがエラーを示す場合は、その記録を分析用の観測データに追加しないでください。まず原因を解消してから再実行します。本番運用では、キーや秘密情報を含む完全なURLを除外しつつ、HTTPコード、検索語、時刻、簡潔なエラーメッセージも記録するとよいでしょう。
ページネーションと収集の再現性
検索では、結果を次のページへ進めるためのcursorパラメーターを使えます。次のページを取得する場合は、前のレスポンスのカーソルを取り出し、加工せずに渡してください。カーソルはAPIが管理する不透明な値です。アプリケーション側では、そのまま保存して再送し、行数から計算したりページ番号として解釈したりしてはいけません。
最初のモニタリングでは、キーワードごとに1回のリクエストを行い、同じcountを使うだけで十分な場合があります。解釈が容易で、各実行が検索結果の限定的なスナップショットを保存すると明確になるためです。ページネーションを追加する場合は、各ページとカーソルを保存し、1回の実行で取得するページ数に上限を設定してください。予期しないレスポンスによる無限ループを防げます。
date_postedパラメーターでは、ドキュメントに記載された期間のいずれかに検索を限定できます。sort_byでは、関連度、投稿日、いいね数による並べ替えを選べます。変化を分析する際は、こうした設定も実行記録に残してください。期間や並べ替え設定が異なる検索を比較すると、テーマ自体の変化ではなく、検索条件の違いを反映している可能性があります。
cache_timeoutパラメーターはレスポンスのキャッシュを制御します。ドキュメントには標準のキャッシュ期間として3600秒、キャッシュを無効にする値として0が記載されています。定期モニタリングでは、設定を意識して選び、構成に保存してください。1時間未満の間隔で一連のリクエストを実行し、その期間内のレスポンスを区別する必要がある場合は、結果が繰り返されることを変化がない根拠と見なす前に、キャッシュの動作を別途確認します。
日々の観測を比較する
CSVには、簡単なレポートを作るための基本情報がすでに含まれています。検索語とaweme_idごとに行をグループ化し、collected_at順に並べ、両方の指標値が存在する観測ペアだけを比較します。たとえば、視聴数の差は、最後に観測した値からその前の値を引いて計算できます。結果を正しく理解するには、絶対差だけでなく、2つの元の値と観測間隔も保存してください。
合意した時間間隔がない限り、この差を視聴数の「増加速度」と呼ばないでください。ある実行が朝に行われ、次の実行が数日後なら、その値はその期間に蓄積した変化を表します。比較可能なペースを求めるには、差を実際の観測間隔で割る方法がありますが、その結果は2つのスナップショット間の平均速度であり、連続的なテレメトリーではありません。
シグナルを2種類に分けて集計します。1つ目は、現在の検索結果に現れた新しいIDです。2つ目は、すでに観測した動画の統計値の変化です。新しい動画は現在の視聴数にかかわらず検証候補になり、以前からある動画の伸びは、その投稿が反応を集め続けていることを捉えるのに役立ちます。この2つのシグナルが答える問いは異なり、編集計画でも別々に活用できます。
簡単なデータ品質チェックも加えましょう。IDがある行の割合、説明文がある行の割合、収集日の有無、検索語ごとのユニーク動画数、統計値が欠けている数などです。こうした指標があれば、不完全なファイルをもとにチームが結論を出す前に、パイプラインが通常の構造を取得できなくなったことに気づけます。また、どの検索語が業界に役立つサンプルを返すかもわかります。
最初のレポートは、「検索語、ID、投稿日、投稿者、説明、リンク、現在の視聴数、前回スナップショットの視聴数、差、観測間隔」の列を持つ表で十分です。「アーカイブに新規」というフラグと、編集担当者の評価欄も追加します。担当者はブランドとの関連性、形式の適切さ、他者のアイデアを模倣するリスクなどを記録できます。API自体は、こうした評価を行いません。
動画の人気とテーマの有用性を混同しない
視聴数、いいね、コメント、シェアは、個々の動画に対する公開上の反応を説明するのに役立ちます。コンテンツ計画では、質問の表現、冒頭の訴求、説明の繰り返し使われる形式、デモの種類といったテキストそのものも重要です。したがって、指標だけでなく、リンクと説明も編集担当者に渡してください。ひとつの数字だけでは、その投稿がうまくいった理由を説明できないことがほとんどです。
複数の動画を比較する際、両方のカウンターがあれば、視聴数に対するエンゲージメントの比率を計算できます。たとえば、いいね、コメント、シェアの合計を視聴数で割れば、観測された反応の割合を示す簡単な指標になります。計算式を明記し、欠損値のある動画を混ぜないでください。そうしないと比較可能性が損なわれます。この比率が表すのは、選択した動画における選択された公開カウンターだけです。
同じ動画の指標を、独立した出来事のようにスナップショット間で合算しないでください。同じ動画が5日分の検索結果に含まれていても、各行の視聴数は1つのカウンターが順次変化した状態であり、異なる5つのオーディエンスではありません。ユニークな投稿の合計を出すには、レポート期間において動画ごとに1つの観測時点を選びます。たとえば期間中の最後のスナップショットを使い、その選択ルールを保存してください。
説明文に繰り返し現れる語を調べるのも有用です。簡単なテキスト分析で、あらかじめ定めた辞書を使って投稿を「レシピ」「レビュー」「ビフォーアフター」「失敗」「ヒント」などに分類できます。分類器や言語モデルを使ってカテゴリや短い要約を提案させてもよいですが、編集担当者が動画自体を確認できるよう、元の説明とURLは表に残してください。
スケジュール実行の自動化
手動実行を検証したら、自社サーバーのcron、GitHub Actions、n8n／Makeのワークフローなどのスケジューラーに収集処理を移します。連携処理では、検証済みの同じスクリプトを起動し、秘密情報ストアからキーを渡し、JSONをアーカイブしたうえで、正常終了した場合にのみ通知を送るようにします。スケジューラーの具体的な実装はインフラによって異なりますが、API呼び出しとデータ処理の形式は変わりません。
マシンの時刻で毎日08:15に実行するcronの例：
15 8 * * * cd /srv/tiktok-monitor && /usr/bin/python3 collect_tiktok.py "meal prep" >> logs/collector.log 2>&1この設定を使う前に、cronが実行されるサービスやシェルで環境変数を設定し、ホストのタイムゾーンが正しいことを確認してください。複数の検索語がある場合は、リストをファイルに保存し、スクリプトに検索語を1つずつ渡して実行するのがおすすめです。これなら、1つの検索語でエラーが起きても全体を止めずに済み、アーカイブも比較しやすくなります。
検索語が増えたら、設定をJSONやYAMLに移し、ステータス、取得動画数、アーカイブのパスを含む実行ログを追加します。信頼性を高めるため、一時的なネットワークエラーに対する回数制限付きの再試行、タイムアウト、HTTPエラーの個別処理も用意してください。無制限に再試行してはいけません。次の実行が問題を覆い隠すことのないよう、処理は状態が見える形で終了させます。
結果をGoogle Sheets、データベース、社内ダッシュボードに送る必要がある場合は、アーカイブが確実にできるようになってから連携を追加します。まず生のレスポンスを保存し、それから正規化した行をアップロードします。アップロードに失敗した場合、必ずしもデータ収集を再実行する必要はなく、アーカイブから再アップロードできます。動画IDと収集時刻を使えば、再実行可能な挿入処理を組み立て、古いスナップショットと新しいスナップショットを区別できます。
AIを加えるなら、情報源の代わりではなく整理役として
アーカイブに大量の説明文が蓄積したら、モデルを使って動画をテーマ別にまとめたり、よく使われる表現を見つけたり、編集担当者向けの短い解説を作成したりできます。モデルには、検索語、説明、投稿日、公開カウンターなど、必要最小限のフィールドを渡します。データにない人気の理由を断定させるのではなく、構造化されたカテゴリと簡潔な根拠を返すよう依頼してください。
モデルの出力は、ai_topic、summary、review_statusなどの別列に保存します。元の説明文やAPIの値を上書きしてはいけません。指示文やモデルを変更しても、保存済みレコードを再処理できるようにします。そのため、プロンプトのバージョンと分類日を記録すると便利です。
モデルの実用的な用途のひとつは、「短いレシピ」「機器の比較」「初心者の失敗」といったクラスターを編集担当者に提案することです。その後、分析担当者が各クラスターの例をリンクから確認し、分類語彙を修正します。このhuman-in-the-loopのプロセスでは、AIをデータ群を閲覧するための補助として使いながら、検証可能な元の観測データを参照できます。
少数の検索結果だけをもとに、形式とリーチの因果関係をモデルに独自判断させないでください。そのような結論には、あらかじめ定義した手法、比較可能な投稿、追加データが必要です。実際の編集業務では、確認候補の順位付け、繰り返されるテーマの仮説、手動で分析するためのリンク一覧があれば十分です。
サンプルの品質と結論の限界
このパイプラインが保存するのは、指定した検索語とパラメーターで取得したレスポンスです。これらの観測を比較するのに役立ちますが、検索範囲は検索語、収集時点、設定、サービスのレスポンスによって限られます。そのため、結論は正確に表現してください。「今週、検索語Xの取得結果ではテーマYが比較的多く見られた」と述べ、「TikTok全体がいまYを話題にしている」とは言わないようにします。
同じ条件で設定された一連のデータだけを比較します。地域、並べ替えパラメーター、投稿日フィルター、取得件数をそろえてください。検索語やフィルターを変更した場合は、新しいシリーズとして記録します。季節性やキャンペーンを分析する際には設定のバージョンを保存しないと、入力条件の変化がコンテンツ自体の変化に見えてしまいます。
公開指標はスナップショットの間に更新され、動画によって経過時間が異なることがあります。新しい動画と古い動画は、反応を蓄積している段階が異なります。成果を比較する際は、投稿日と観測期間を考慮してください。投稿からの経過時間が近いもの同士を比較するか、同じIDを連続したスナップショットで追跡します。
プロジェクトが競合他社や投稿者に関係する場合、収集の目的を限定し、必要最小限のデータだけを扱います。センシティブな情報を収集したり、公開指標を投稿者本人の評価に使ったりしないでください。マーケティングチーム向けのレポートで通常必要なのは、リンク、説明、プロフィール名、投稿日、集計済みの指標です。自動化の前に、適用されるプラットフォームの利用条件、組織の要件、データ保存ルールを確認してください。
実行前のチェックリスト
- どのテーマ、形式、投稿を把握したいのか、ビジネス上の問いを明確にする。
- 安定して使える検索語をいくつか選び、表記を固定する。
/searchVideoのルート、必須のkeyword、その他のパラメーターをドキュメントで確認する。- キーは環境変数に保存し、出力、ログ、リポジトリに含めない。
- 外側のレスポンスステータスと、
tiktokオブジェクトの有無を確認する。 aweme_listとsearch_item_list[].aweme_infoの両方を処理する。- 正規化の前に生のJSONを保存する。
- 欠損フィールドは空欄にし、ゼロで置き換えない。
aweme_idで投稿を照合し、カーソルは加工せずに渡す。- 各スナップショットの収集日と検索パラメーターを記録する。
- 結論を出したり、モデルに結果を渡したりする前に、複数の動画を手動で確認する。
最終的に得られるもの
設定が完了すると、チームは再現可能なプロセスを運用できます。検索語の一覧をスケジュールに従って実行し、各レスポンスを生のJSONとして保存し、正規化した観測データをCSVに追加します。分析担当者は、アーカイブに新たに加わった動画を見つけ、リンクと説明を確認し、利用可能な公開カウンターをスナップショット間で比較し、テーマ別のグループを作成できます。
編集担当者が得るのは、「最大のトレンド」を自動で断定する答えではなく、検証可能な候補の短いリストです。新しい投稿、指標が目立って変化した動画、繰り返し現れるテーマの表現などが含まれます。これにより、手作業の検索からテーマの検討までの時間を短縮し、コンテンツ計画に盛り込む価値があるかどうかを判断するための、根拠をたどれる土台を維持できます。
検索語を1つに絞り、毎日ローカルで実行し、CSVファイルに保存するところから始められます。サンプルが目的に合っていると確認できたら、スケジュール実行、データベース、説明文の分類を追加してください。ドキュメントに記載されたパラメーターとエンドポイントの用途はTikTok APIのドキュメントで確認でき、アクセス方法と製品情報はTikTok Scraper API jsonscraperのページで確認できます。