TikTok：検索モニタリングが実際に機能しているか確認する方法

HTTP 200が返っても、日次のTikTokモニタリングで動画を取得できたとは限りません。検索結果はaweme_listまたはsearch_item_list[].aweme_infoに含まれることがあります。最初の配列だけを読み取るスクリプトは、エラーなしで終了して空のレポートを出力する可能性があります。信頼できる検証では、通信とアプリケーションの両方のステータスを確認し、サポートされている2つの構造からデータを抽出したうえで、今回の実行で取得できたユニークな動画の数を記録します。

診断すべき項目

チームが毎朝、複数の検索語句で公開動画を収集し、製品に関する新しい投稿を把握するケースを考えてみましょう。この処理で重要なのは、説明、投稿者、公開日、取得可能な指標を含む、再現可能なレコード一覧を作ることです。レポートが突然空になった場合、原因はJSONの処理、検索結果の変化、既知の動画の再取得、または実際のリクエスト障害かもしれません。たとえばaweme_listの件数だけを見ても、原因を見分けることはできません。

jsonscraper TikTok Scraper APIの検索エンドポイント/searchVideoでは、必須パラメーターkeywordと、追加パラメーターcount、cursor、date_posted、sort_by、regionを受け付けます。エンドポイントのドキュメントではcursorによるページネーションが説明されています。cursorは前回のレスポンスから取得した不透明な値として、そのまま渡してください。countは希望する結果件数を指定するもので、すべての投稿が取得できることを保証するものではありません。

4つのシグナルに分けて確認する

有用な診断は、互いに独立した4つの確認から成ります。1つ目はHTTPリクエストが成功したこと。2つ目はレスポンスの外側のstatusがokで、内側のtiktok.status_codeも成功を示していること。3つ目はtiktokオブジェクトが存在し、ドキュメントに記載された2つのレスポンス箇所からレコードを抽出できること。4つ目は重複を除いた後に、保存に使えるID付きのレコードが残っていることです。ログには重複除去前後の件数を記録してください。件数の差から、正規化の過程で重複が生じたかどうかが分かります。

欠けているフィールドは、作り出した値で埋めず、空のままにします。たとえば、特定のレコードに再生回数が含まれていない場合があります。正規化した行とともに元のJSONを保存しておけば、後から、解析時に情報が失われたのか、元のレスポンスにそもそも存在しなかったのかを確認できます。

Pythonで行う最小限のリクエストと正規化

jsonscraperの仕様書では、ベースURLはhttps://tiktok.evelode.comで、キーはクエリーパラメーターlicense_keyとして渡します。次の例ではドキュメントに記載されたパラメーターを使い、キーは環境変数から読み込み、ログには出力しません。python -m pip install requestsで依存関係をインストールし、環境変数にJSONSCRAPER_TIKTOK_LICENSE_KEYを設定してください。

import json
import os
from datetime import datetime, timezone
from pathlib import Path

import requests

BASE_URL = "https://tiktok.evelode.com/searchVideo"
KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]


def extract_videos(payload):
    """検索レスポンスの既知の2種類の構造から動画を集める。"""
    tiktok = payload.get("tiktok") or {}
    videos = []

    for item in tiktok.get("aweme_list") or []:
        if isinstance(item, dict):
            videos.append(item)

    for item in tiktok.get("search_item_list") or []:
        if isinstance(item, dict):
            aweme = item.get("aweme_info")
            if isinstance(aweme, dict):
                videos.append(aweme)

    return videos


def main():
    params = {
        "license_key": KEY,
        "keyword": "製品に関する検索語句の例",
        "count": 20,
        "region": "US",
    }
    response = requests.get(BASE_URL, params=params, timeout=30)
    response.raise_for_status()
    payload = response.json()

    if payload.get("status") != "ok":
        raise RuntimeError("APIの外部ステータスがokではありません")

    tiktok = payload.get("tiktok")
    if not isinstance(tiktok, dict):
        raise RuntimeError("レスポンスにtiktokオブジェクトがありません")

    if tiktok.get("status_code") != 0:
        raise RuntimeError("内部status_codeが成功を示す0ではありません")

    raw_videos = extract_videos(payload)
    unique = {}
    for video in raw_videos:
        video_id = video.get("aweme_id")
        if video_id:
            unique.setdefault(str(video_id), video)

    snapshot = {
        "collected_at": datetime.now(timezone.utc).isoformat(),
        "keyword": params["keyword"],
        "status": payload.get("status"),
        "status_code": tiktok.get("status_code"),
        "raw_items": len(raw_videos),
        "unique_items": len(unique),
        "has_more": tiktok.get("has_more"),
        "cursor": tiktok.get("cursor"),
        "videos": list(unique.values()),
    }

    Path("snapshots").mkdir(exist_ok=True)
    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
    Path(f"snapshots/{stamp}.json").write_text(
        json.dumps(snapshot, ensure_ascii=False, indent=2),
        encoding="utf-8",
    )

    print({
        "status": snapshot["status"],
        "status_code": snapshot["status_code"],
        "raw_items": snapshot["raw_items"],
        "unique_items": snapshot["unique_items"],
        "has_more": snapshot["has_more"],
    })


if __name__ == "__main__":
    main()

このスクリプトは、まずraise_for_status()で通信レベルを検証し、続いて外部ステータス、tiktokオブジェクトの有無、内部のstatus_codeを確認します。その後、2種類の検索構造からレコードを抽出し、aweme_idで重複を除いて、収集時刻とともにスナップショットを保存します。該当するレコードがなくても、実行に関する情報を含むファイルが作られるため、空の結果が保存されたのか、レポート自体がないのかを区別できます。

スナップショットをチーム向けのシグナルに変える

cron、CI、ワークフロースケジューラーなどを使い、スクリプトを定期実行します。検索語句ごとにスナップショットを分けて保存するか、ファイル名に検索語句を加えてください。状態テーブルには、実行時刻、ステータス、抽出件数とユニーク件数、has_moreフラグを記録すれば十分です。リクエスト例外、必須レスポンス部分の欠落、または抽出件数がこれまでの推移から急変した場合に通知すると便利です。

このような比較でパイプラインの異常は検知できますが、それだけで原因が分かるわけではありません。結果の減少はAPIやパーサーの故障ではなく、現在の検索結果の内容を反映している可能性があります。そのため、元のJSONを保存し、同じパラメーターで比較し、取得したIDを確認するとよいでしょう。通知のしきい値は、汎用的な数値ではなく、実際に監視する検索語句の傾向を基に決めてください。

ページネーションにはレスポンスのcursorを使い、APIが次の結果がないことを示したら処理を終了します。実行を再現できるよう、使用したカーソルとリクエストパラメーターを保存してください。date_postedとsort_byで期間フィルターと並び順を指定できます。比較の再現性が必要なら、実行ごとにこれらを固定してください。

結果の読み方

導入後、チームは実務上の3つの問いに、確認可能な形で答えられるようになります。リクエストは成功したか、JSONのどこに結果があるか、保存したスナップショットにユニークな動画が何件含まれるか、という問いです。これにより、空の表から原因究明までの時間を短縮できます。まずステータスと構造を確認し、次にパラメーター、重複、元のレスポンス内容を調べます。

レスポンスのスキーマや利用可能なフィールドは、レコードによって異なる場合があります。2026年10月25日にjsonscraperで行ったライブ確認では、検索結果にID、説明、投稿者、統計情報のフィールドが含まれていましたが、個々のレコードに値があるとは限りません。実際に得られたデータをそのまま保存し、欠損値をゼロで置き換えないことが、実用的なレポートの基本です。

TikTok Scraper APIのページから始め、正確なエンドポイントとパラメーターはAPI公式ドキュメントで確認できます。モニタリングを開始する前にこの検証を行えば、レポートを診断可能な観測結果として扱えます。