Michael Johnsonマーケティングチームは、TikTokに新製品に関する動画が投稿されていることに気づきましたが、毎日いくつものハッシュタグを手作業で確認するのは大変です。投稿や公開されている指標を時系列で比較するには、タイムスタンプを付け、元のレスポンスを保存し、変更を検証できる再現可能な収集方法が必要です。
このようなプロトタイプには、jsonscraperのTikTok Scraper APIが適しています。TikTok Scraper APIの製品ページには、ハッシュタグ、ユーザー、動画、検索向けのエンドポイントが掲載されています。まずPostmanで必要なエンドポイントとレスポンス形式を確認し、その後、検証済みの設定をPythonに移します。実際のレスポンスに存在するフィールドだけを取り出せば、再現可能なワークフローを構築できます。
課題：人気動画を一つ見るのではなく、推移を把握する
再生数の多い投稿一つが注目を集めることはありますが、キャンペーンの計画には、テーマに沿った新しい動画がどれだけ見つかるか、すでに見つかった投稿の公開指標がどう変化するかを把握するほうが役立ちます。たとえば、スポーツ用品のオンラインストアなら、関連するクリエイティブを制作する前に、特定のトレーニング種目に関する動画の投稿数を把握したいと考えるでしょう。
手作業での確認では比較が難しくなります。検索結果は変化し、指標は蓄積され、担当者ごとに記録形式も異なる場合があります。収集時刻と元のJSONを添えて各実行結果を保存すれば、チーム独自の観測履歴を作成でき、分析スキーマが変わったときにもデータを再処理できます。
自動化はいくつかの手順で構成されます。エンドポイントとパラメーターを確認し、スケジュールに従ってデータをリクエストし、レスポンスを保存して、その構造を検証したうえで必要なフィールドを取り出します。得られた表は、グラフやトピック分類、レポートに活用できます。
APIドキュメントで確認できる内容
TikTok Scraper APIのページには、ベースURL https://tiktok.evelode.comと、HashtagカテゴリのエンドポイントとしてGET /getHashtagInfo、GET /getHashtagFeed、GET /getHashtagFeedByIDが記載されています。また、別のエンドポイントにlicense_keyパラメーターを指定するリクエスト例と、Postmanコレクションでキーを設定する方法も示されています。
GET /getHashtagFeedについては、公式のエンドポイント仕様に、必須パラメーターquery（ハッシュタグのURLまたはタグ名）と、任意のcursor、count、region、cache_timeoutが記載されています。フィードのレスポンスではtiktok.aweme_list配列が想定され、各要素のフィールドとしてaweme_id、desc、create_time、share_url、投稿者データ、statisticsなどが列挙されています。個々のフィールドは含まれない場合があるため、処理前に実際のJSONを確認してください。
jsonscraperのPostmanコレクションでテストリクエストを実行し、実際のレスポンスを照合して、後でコードを検証するためのテスト例を取得できます。認証にはlicense_keyを渡します。キーは環境変数に保存し、ログに出力しないでください。
まずPostmanでリクエストを確認する
テスト用のハッシュタグを一つ選ぶところから始めます。コレクションでハッシュタグフィードのエンドポイントを選び、ドキュメントに記載された方法でlicense_keyを設定し、queryにタグ名を渡します。必要に応じてcountや国コードを示すregionを追加します。リクエストを実行し、HTTPステータス、トップレベルのstatusフィールド、tiktok.aweme_listの内容を確認してください。
成功したレスポンスをテスト用JSONファイルとして保存します。そのファイルで、投稿ID、説明、投稿時刻、リンク、統計情報が含まれているかを確認してください。フィールドを分析スキーマに含めるのは、必要な型で返されることを確かめてからにします。
APIキーはソースファイルではなく環境変数に保存してください。キーがURLに含まれる場合は、リクエストをログに記録するときにマスキングし、完全なURLがログに残らないようにします。
リクエストとアーカイブを行うPythonクライアント
以下のエンドポイントとパラメーター名は公開済みの仕様に準拠しています。ハッシュタグにはqueryを使用し、認証にはlicense_keyを渡します。この例はPython 3.8以降に対応し、実行時のメタデータとともに元のレスポンスを保存します。
import json
import os
from datetime import datetime, timezone
from pathlib import Path
import requests
BASE_URL = "https://tiktok.evelode.com"
API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
def fetch_hashtag_feed(hashtag: str) -> dict:
params = {
"license_key": API_KEY,
"query": hashtag,
"count": 20,
}
response = requests.get(
f"{BASE_URL}/getHashtagFeed",
params=params,
timeout=45,
)
response.raise_for_status()
payload = response.json()
if payload.get("status") != "ok":
raise RuntimeError("API returned a status other than ok")
return payload
def archive_response(hashtag: str, payload: dict) -> Path:
collected_at = datetime.now(timezone.utc).isoformat()
safe_tag = hashtag.lstrip("#").replace("/", "_")
output_dir = Path("data/raw") / safe_tag
output_dir.mkdir(parents=True, exist_ok=True)
filename = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ.json")
file_path = output_dir / filename
file_path.write_text(
json.dumps(
{
"hashtag": hashtag,
"collected_at": collected_at,
"response": payload,
},
ensure_ascii=False,
indent=2,
),
encoding="utf-8",
)
return file_path
if __name__ == "__main__":
tag = "#サンプルトピック"
payload = fetch_hashtag_feed(tag)
saved_path = archive_response(tag, payload)
print(f"アーカイブを保存しました: {saved_path}")
実行前に、環境変数JSONSCRAPER_TIKTOK_LICENSE_KEYを設定してください。このリクエストでは、確認済みのqueryを使用し、countで取得対象の数を制限します。外部のHTTPステータスとJSONのステータスを確認し、後の処理に使えるよう実際のデータをアーカイブします。スケジュールや分析を追加する前に、ハッシュタグ一つで動作を確認してください。
壊れやすい前提に頼らず正規化する
フィードのレスポンスについて、ドキュメントではtiktok.aweme_list配列が示されています。変換前に、tiktokがオブジェクトであり、aweme_listがリストであることを確認してください。各要素からは、たとえばaweme_id、desc、create_time、share_urlや、存在する場合はstatistics内の値など、確認済みのフィールドだけを取り出します。
内部テーブルには、検索したハッシュタグ、収集時刻、動画ID、選択した指標を含められます。任意の指標や存在しない指標は空値として保存してください。指標がないことと、測定値がゼロであることは異なります。新たにリクエストせずにテーブルを再構築できるよう、元のレスポンスは別に保存します。
レスポンス形式が変わった場合、型チェックによって不正な処理を停止し、診断メッセージを出すようにします。テスト用JSONをパーサーのテストと一緒に保存しておけば、既知のスキーマを引き続き処理できるか、新しいコードを検証できます。
繰り返しの観測に基づく指標
レスポンスにカウンターが含まれる場合は、観測ごとにタイムスタンプを付けて保存します。一つの投稿について2回の実行時の値を比較すれば、その期間に観測された変化を算出できます。比較には仕様に記載されたaweme_idを使い、各要素に存在するか確認してください。
1日に初めて検出された投稿数は、実行結果を基に算出できます。この指標は、指定したパラメーターとスケジュールでの各リクエストが返した投稿の流れを表します。収集方法を一貫させれば、チーム独自のスナップショットを比較できます。
最小限のレポートには、日ごとに新たに検出された投稿数、利用可能なカウンターの分布、再び見つかった動画の値の変化を表示できます。分析担当者が各レコードの由来を確認できるよう、リクエスト時刻と元ファイル名を加えてください。
スケジュール設定とエラー処理
リクエストとパースを検証したら、cron、GitHub Actions、データオーケストレーターなどを使ってスクリプトを定期実行します。ハッシュタグ一覧は別の設定ファイルに分離し、クライアントの処理を変更せずにテーマを追加・削除できるようにします。
自動実行では、タイムアウトを設定し、一時的なネットワークエラーに対するリトライ回数を制限して、HTTPステータスとリクエスト所要時間を記録します。ログにキーを書き込まないでください。パースに失敗した場合は、安全な診断情報を保存し、担当者に通知します。
仕様では、ハッシュタグフィードのページネーションにcursorパラメーターを使用できます。必要な場合は、レスポンスのカーソルを保存し、変換せずに次のリクエストへ渡してください。返された結果だけを処理し、has_moreが存在する場合はその値を確認します。複数のハッシュタグへのリクエストで同じ投稿が返される場合は、目的に応じて重複排除キーを選びます。投稿をハッシュタグごとに別々に数えるか、一意の動画のみを数えるかを決めてください。
分類とレポートの自動化
検証済みの行を取得した後は、指定したテーマに基づいて動画の説明文を分類できます。descフィールドは要素のスキーマに記載されています。モデルを使って、チュートリアル、レビュー、ユーザー体験などの形式に投稿をグループ分けできます。元のテキスト、ラベル、指示のバージョン、結果を保存し、判断が難しいケースは人による確認に回してください。
数値指標は通常のコードで計算し、実行を繰り返しても再現可能な算術結果が得られるようにします。分類器はテキスト処理に役立ちますが、最終レポートでは、結論を具体的な行と観測日に結び付けてください。
ノーコードのワークフローでは、同じ手順を自動化ツールに組み込めます。スケジュール、検証済み設定によるHTTPリクエスト、レスポンスの確認、JSONの保存、確認済みフィールドの変換、エラー通知をつなぎます。まずPostmanで仕様を確認してから、Python、n8n、Makeに移してください。
期待できる結果と次のステップ
設定後、チームはAPIレスポンスのアーカイブと、選択したハッシュタグの観測データをまとめたテーブルを利用できます。新しい投稿の発見、利用可能な指標の時系列比較、詳しく分析するコンテンツの選定に役立ちます。結果を比較可能にするため、スケジュール、リクエストパラメーター、正規化ルールを統一してください。
まずは一つのエンドポイントと実際のレスポンスから始めます。queryパラメーターを指定して/getHashtagFeedをリクエストし、JSONを保存してから、フィールドの解析とスケジュール設定を追加してください。TikTok Scraper APIのページにはベースURLとエンドポイント一覧が掲載されており、エンドポイント仕様にはクライアント実装に必要なパラメーター名が記載されています。