tiktok-research

TikTok リサーチ

Crawlora の正規化された REST エンドポイントを使用して、TikTok に関するリサーチの質問に回答します。結果は、返された公開データに基づくものにしてください。フィードや検索のサンプルは全件調査ではなく、指標は動画や広告の成果が良かった理由を示す証拠ではありません。

セットアップとリクエスト

CRAWLORA_API_KEY に crawlora.net から取得したキーを設定し、このスキルに同梱されているヘルパーを実行します。ヘルパーは https://api.crawlora.net/api/v1 に x-api-key を送信します。キーは環境変数に保持し、URL、プロンプト出力、保存ファイルには決して含めないでください。

Set `CRAWLORA_API_KEY` in the environment before running the helper.

scripts/crawlora.sh /tiktok/profile/chatgpt | jq '.'
scripts/crawlora.sh /tiktok/search keyword="ai agents" count=20 | jq '.'
scripts/crawlora.sh /tiktok/post/7444278905264983342 | jq '.'

エンドポイントの一覧と最新のパラメーター名については、reference/endpoints.md を参照してください。HTTP の結果と JSON エンベロープの両方を確認してください。HTTP レスポンスが成功していても、アプリケーションの code がゼロ以外であったり、ネストされた上流エラーが含まれていたり、使用可能な結果がなかったりする場合があります。

ワークフローを選択する

プロフィール、動画、コメント

1. @ を付けずにハンドルを指定して /tiktok/profile/{handler} を呼び出します。
2. プロフィールの動画を取得するには、返された user.secUid をそのまま /tiktok/posts に渡します。数値のユーザー ID や表示名で代用しないでください。sort_type は 0 が最新、1 が人気順、2 が古い順です。
3. 1 本の動画の詳細には /tiktok/post/{id} を使用します。トップレベルのコメントを取得するには、その動画の aweme_id（URL 内の動画 ID）を指定して /tiktok/comments を使用します。
4. カーソルをたどるのは、ユーザーが指定した上限までにしてください。カーソルの型を維持し、has_more／hasMore が false になったら停止します。TikTok のすべてのレスポンスで大文字と小文字の使い方が同じとは限りません。

検索と発見

• /tiktok/search はキーワードで動画を検索します。
• /tiktok/search/hashtag はハッシュタグ／チャレンジの候補を検索します。
• /tiktok/search/user はキーワードでユーザーを検索します。
• /tiktok/hashtag/{name} はハッシュタグを解決して ID を返します。その ID を /tiktok/hashtags に渡すと、該当する動画を取得できます。
• /tiktok/category は Explore のカテゴリを検索します。返されたカテゴリの type を /tiktok/explore/{id} に渡します。

前の呼び出しで返された識別子を使用してください。検索結果やハッシュタグの件数は、TikTok の現在のインデックスに基づく証拠であり、すべての結果が指定したブランドやトピックに関するものだと証明するものではありません。強い帰属を示す前に、返されたプロフィール、キャプション、ソース URL、または詳細レコードで本人・対象を確認してください。

トレンドと Creative Center

• /tiktok/trending は、現在おすすめまたはトレンドになっているフィードを返します。
• /tiktok/creative-center/hashtags は、国と期間を指定して、ランキング形式のハッシュタグを返します。
• /tiktok/creative-center/videos はランキング形式の動画を返します。コンテンツラベルまたは organic_only で絞り込み、views、engagement、six_second_views で並べ替えることもできます。
• /tiktok/popular-trend/country-industry-meta は、Creative Center のコンテキストを説明する必要がある場合に、国と業界のメタデータを提供します。

国、期間、並べ替え／フィルターの選択、取得時刻、サンプルサイズを必ず報告してください。「トレンド」は表示面と時点に左右されます。世界全体または過去のランキングとして提示しないでください。

モバイルアプリの検索

/tiktok/mobile/* ルートでは、Web／Creative Center のルートとは別に、TikTok アプリの各画面を利用できます。

• /tiktok/mobile/feed は、パーソナライズされ、地域に依存する For You のサンプルです。国や過去の期間によるフィルターはなく、グローバルなトレンドランキングではありません。
• /tiktok/mobile/search、/search/music、/search/user は、モバイルアプリの動画、サウンド、ユーザーの各画面を検索します。モバイル検索結果の識別情報とカーソルは、対応するWeb検索結果のものと分けて保持してください。
• /tiktok/mobile/music/trending と /music/pick は、サウンドチャートの画面を返します。返された music_id を /music/posts で使用すると、そのサウンドを使った動画を取得できます。music/posts は互換性のため count を受け付けますが、ページサイズは上流側で決まるため、返されたカーソルを使って続行してください。/music/related は動画の aweme_id を起点とします。
• /tiktok/mobile/music/beats は、ページングフィールドのない、計測済みのサウンドチャートの1ページを返します。count がページサイズを制御することは確認されていません。/music/collections はコレクションフィードの最初のページを返します。表示されるカーソルは再利用できないため、コレクションを網羅的に取得できるとは主張しないでください。
• /tiktok/mobile/trending/categories と /trending/effects は、カーソルページングに対応した、現在のアプリ内検索フィードです。固定されたカテゴリー分類や市場横断のランキングではありません。返された地域／ホストのコンテキストと取得時刻を保持し、件数を Creative Center の指標と同一視しないでください。
• /tiktok/mobile/live/search はキーワードが必須で、LIVE 検索用のルームアンカーを返します。ライブ配信ディレクトリでも、利用可能状況を保証する確認手段でもありません。返されたルーム ID と、確認された視聴者フィールドを保持してください。
• /tiktok/mobile/live/gifts は、LIVE ギフトの完全なカタログと設定／リソースのマップを返します。/tiktok/mobile/live/effects は、エフェクト／ステッカーの全アセットカタログを返します。どちらもフィルターのない、大容量でページングされないスナップショットです。カタログのメタデータには使用できますが、トレンドランキング、現在の利用状況、または diamond_count に基づく実際の価格の主張には使用しないでください。
• モバイルのハッシュタグ詳細には、設定済みのアプリセッションが必要です。セッションがない場合、人気ハッシュタグの投稿が取得できるのは米国からのエグレス経由に限られます。最新の投稿には fresh を使用してください。また、地域外の人気投稿ページが空の場合は、ハッシュタグのアクティビティがゼロなのではなく、対象範囲外で取得できないものとして扱ってください。

scripts/crawlora.sh /tiktok/mobile/music/trending count=10
scripts/crawlora.sh /tiktok/mobile/music/collections
scripts/crawlora.sh /tiktok/mobile/live/search keyword="lofi" count=10
scripts/crawlora.sh /tiktok/mobile/live/gifts
scripts/crawlora.sh /tiktok/mobile/live/effects
scripts/crawlora.sh /tiktok/mobile/trending/categories count=10
scripts/crawlora.sh /tiktok/mobile/trending/effects count=5

Top Ads のインテリジェンス

広告を照合して調査する場合は、まず /tiktok/top-ads/filters を呼び出して、現在の動的な国、業種、目的、言語、パターンラベルの ID を確認してください。比較全体で期間、国、目的、並べ替えを統一してください。続いて：

1. 合意したフィルターと上限を設けた limit を指定して、/tiktok/top-ads/list を検索します。出力には period（7、30、180）と order_by（for_you、impression、ctr、play_2s_rate、play_6s_rate、cvr、like）を明記してください。
2. 返された素材を重複排除し、それぞれの id を material_id として /tiktok/top-ads/detail に渡します。これは Top Ads の素材 ID であり、広告の TikTok 動画 ID ではありません。id と materialId は詳細エンドポイントでは受け付けられません。
3. インタラクティブ時間のチャートとパーセンタイルには、/tiktok/top-ads/analysis を使用します。広告間で metric と period_type を一致させてください。対応している指標は retain_ctr、retain_cvr、click_cnt、convert_cnt、play_retain_cnt です。
4. /tiktok/top-ads/recommend または /tiktok/top-ads/spotlight は、補助的な検索に限って使用してください。これらのピックアップ素材や関連素材を、明示せずに、フィルター条件をそろえたサンプルへ混在させないでください。

競合広告の比較やクリエイティブブリーフを個別に作成する場合は、より対象を絞った tiktok-ad-research スキルを利用できます。このスキルでは、同じ Top Ads エンドポイントを使い、より焦点を絞った成果物を作成します。

解釈と制限事項

• 公開データのみを対象とします。ログインが必要な情報、非公開コンテンツ、非公開の連絡先、オーディエンスの属性情報は含みません。認証バッジがあっても、オーディエンスの真正性が証明されるわけではありません。
• Creative Center に匿名でアクセスできる範囲は限られています。ハッシュタグで取得できるレコードは最大3件、動画は1ページ目の4件のみです。上流の合計件数が表示されていても、これらの上限は変わりません。合計件数はアクセス可能な範囲ではなく、上流から報告された参考情報として扱ってください。
• Creative Center で利用できる動画は国によって異なります。US、JP、ID、VN、TH では、データが含まれるサンプルが安定して取得できています。ほかの市場で有効な空のレスポンスが返る場合、その市場のTikTokに匿名で取得できるデータがないことを意味する可能性があります。際限なく再試行したり、ほかに根拠がないまま障害と判断したりしないでください。
• Creative Center の engagement_rate と six_seconds_vtr は比率であり、パーセンテージではありません。期間を対象とするフィールドと累計フィールドを、同じ期間を示すものとして比較してはいけません。
• Top Ads のパーセンタイルは、CTR/CVR の実数、支出額、コンバージョン数、ROI ではありません。指標名、期間、単位は、返されたとおりに保持してください。
• 署名付きの画像／動画URLは期限切れになることがあります。調査を再現できるよう、安定したTikTokのソースリンクとIDを保持してください。環境で実際にメディアを確認できていない場合は、クリエイティブを視聴または聴取したと主張しないでください。
• 欠損フィールドは不明であり、ゼロではありません。ライブ更新に失敗した場合、明確に古いデータ／データセットに基づく観測として示すことはできますが、暗黙のうちに現在の事実として扱ってはいけません。

出力と信頼性

要求された回答には、ソースURLまたは安定したID、取得時刻、フィルター、サンプルサイズを含めてください。比較する場合は、すべての行で同じ定義と期間を使用してください。観測された事実と解釈を分け、仮説には仮説であることを明記してください。

リクエスト数には上限を設けてください。429 が返った場合は、待機時間を延ばしてから再試行してください。有用な場合は、一時的な 5xx を1回再試行してください。401／403 が返った場合は処理を停止し、アクセス上の制限を報告してください。一部の詳細情報またはコメントの取得に失敗した場合は、明確に部分的な結果であると示してください。また、空またはネストされたレスポンスを有効なデータとして扱う前に、アプリケーションレベルの code を確認してください。