TikTokクリエイターデータAPI：プロフィールと動画サンプルで一次スクリーニングする

TikTokクリエイターのリストを検討する際、フォロワー数で並べ替えるのが一般的な出発点です。しかし、フォロワーが多くても最近の動画のパフォーマンスが安定しているとは限らず、1本の動画がバズったからといって、すべてのコンテンツで一貫した成果が出ているとも言えません。データセットにユーザー名、フォロワー数、定義のあいまいなエンゲージメント率しか含まれていなければ、そのリストは検証が難しく、アプローチ先としての評価も困難なままです。

TikTokクリエイターデータAPIは、根拠に基づくスクリーニングを支援します。まずアカウントの識別情報とプロフィールの詳細を確認し、範囲を明確に定めた動画サンプルを取得したうえで、コンテンツの適合性評価と人によるレビューを組み合わせます。このガイドでは、EveryInfraのprofileとuser_videosエンドポイントを使ってこのワークフローを実行します。公開エンゲージメントデータを、売上、購買者ペルソナ、ROIの予測にまで拡大解釈することはしません。

パラメータとフィールドの定義は、2026-09-04時点の公開ディレクトリとソースコードに照らして検証しています。以下のリクエストは許可されたシナリオ向けに調整したテンプレートで、今回は実際のアカウントへの呼び出しは行っていません。計算例には合成データを使用しています。

公式認可による表示とデータ取得の区別

TikTok公式のDisplay APIは、ユーザー情報、動画リスト、IDによる動画検索など、クリエイターのプロフィールと動画を提供します。利用にはアプリケーションの申請とユーザー認可フローが必要です。公式ドキュメントにはuser.info.basicとvideo.listの権限が記載されています。ユーザーが自身のTikTokアカウントを連携する場合は、この公式の統合方法から始めてください。

EveryInfraのplatform/action/paramsは、別のリクエスト方式です。公式のDisplay APIとは異なり、公式のアクセストークンを再利用しません。また、このドキュメントで公式APIを参照していても、当該プラットフォームから推奨されていることを意味しません。権限、フィールド、対応範囲は、方式ごとに個別に評価してください。

このガイドで扱うのは、プロフィールとアカウントの動画サンプルのみです。コメント、ハッシュタグ、商品、マーケットプレイスの機能には別のアクションが必要です。プロフィールオブジェクトから商品の売上を導き出したり、商品検索の地域フィルターをクリエイターの国籍として扱ったりしないでください。まず調査範囲を絞り込み、必要なフィールドを特定してください。

ステップ1：調査タスクを2種類のデータ取得に分割

profileエンドポイントは公開プロフィールの詳細を返し、user_videosはそのアカウントの動画レコードを返します。どちらもユーザー名を受け付けますが、レスポンス構造は異なり、前者はオブジェクト、後者は配列を返します。actionパラメータを差し替えるだけで同じパース処理を使うことはできません。

curl -fsS --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/catalog?platform=tiktok' \
  | jq '.capabilities[]
    | select(.action == "profile" or .action == "user_videos")
    | {action, required_params, optional_params, param_meanings,
       mode, returns_list, default_limit, max_limit, response_fields}'

このディレクトリでは、どちらのエンドポイントもusernameが必須で、syncモードを使用します。user_videosのデフォルトは10件、最大50件です。一方、profileは単一のオブジェクトで、リストの件数制限はありません。ユーザー名はアカウントのハンドルを指し、表示用のニックネーム、プロフィールの完全なURL、内部IDではありません。例では、現在の公開ディレクトリに合わせて@記号なしのハンドルを使用しています。

リクエストにはユーザー名を使い、長期的な紐付けには安定したアカウントIDを使います。ハンドルが変わっても、新しいハンドルをまったく別のクリエイターとして扱わないでください。ただし、アバターやニックネームが似ているという理由だけで照合することも避けてください。IDを取得できる場合はIDを優先し、識別情報が競合する場合やIDが欠けている場合は、未検証の状態を維持してください。

ステップ2：スコアリング前のプロフィール取得とオブジェクト確認

サーバーにEVERYINFRA_API_KEYと許可済みのEVERYINFRA_TIKTOK_USERNAMEが設定されていることを前提に、profileリクエストを1回実行し、初期確認のためにHTTPステータスとボディを保持します。APIキーをフロントエンドコードや一般公開される分析シートに含めないでください。

: "${EVERYINFRA_API_KEY:?set the API Key first}"
: "${EVERYINFRA_TIKTOK_USERNAME:?paste the authorized account short name}"
jq -cn --arg username "${EVERYINFRA_TIKTOK_USERNAME}" '{
  platform: "tiktok", action: "profile", params: {username: $username}
}' | curl --silent --show-error --include --max-time 180 \
  'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer ${EVERYINFRA_API_KEY}" \
  -H 'Content-Type: application/json' --data-binary @-

現在の実装では、profileオブジェクトはresults内に格納され、レスポンスにはリクエスト追跡情報と課金メタデータも含まれます。username、user_id、取得元URLが対象と一致することを確認してください。オブジェクトが返されない場合は、値をゼロで埋めたアカウントプロフィールを生成しないでください。アクセスできないコンテンツ、取得の失敗、公開データが実際に存在しないケースを区別してください。

プロフィールのフィールドは、bio、follower_count、following_count、video_count、is_verified、is_privateなど、アカウントの自己紹介や規模を把握するのに役立ちます。ただし、オーディエンスの年齢、購買行動、クリエイターのセンシティブな属性を証明するものではありません。is_privateがtrueの場合、動画にアクセスできると想定したり、回避策を試みたりしないでください。

同じ名前のフィールドを区別してください。profileのlike_countはアカウント単位の指標で、動画のlike_countはその動画固有の値です。両者を区別せず1つの「いいね数」列にまとめたり、アカウントの累計値を最近の動画の再生数で割ったりしないでください。

ステップ3：動画サンプルの取得と選定基準の記録

: "${EVERYINFRA_API_KEY:?set the API Key first}"
: "${EVERYINFRA_TIKTOK_USERNAME:?paste the authorized account short name}"
jq -cn --arg username "${EVERYINFRA_TIKTOK_USERNAME}" '{
  platform: "tiktok",
  action: "user_videos",
  params: {username: $username, limit: 5}
}' | curl --silent --show-error --include --max-time 180 \
  'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer ${EVERYINFRA_API_KEY}" \
  -H 'Content-Type: application/json' --data-binary @-

ここでの5件はフィールドの検証用であり、統計的に代表性のあるサンプルサイズではありません。リクエストはprofileの読み取りとは独立して実行・課金され、profileが成功しても動画リストが成功するとは限りません。両方のリクエストについて、リクエストID、タイムスタンプ、課金データを個別に保存してください。

並べ替えが必要な場合、現在のuser_videosのディレクトリにはnewest、oldest、popularが記載されています。調査目的に合わせて選択してください。popularのサンプルは通常のパフォーマンスではなく、突出したコンテンツを示します。時系列のサンプルでは、固定表示された動画、欠落したエントリ、公開日時、対象期間との整合性を確認する必要があります。

untilパラメータは動画の公開日時の上限を設定するもので、収集日時や検証済みのページネーションカーソルではありません。現在のリストエンドポイントは、全履歴をページ送りで取得できることを保証しません。日付を何度調整しても、取りこぼしがゼロであることの証明にはなりません。最小限の例ではフィルターなしで始め、結果を検証しながら段階的に追加します。

ディレクトリでは、同じパラメータが複数のアクションに登場する場合があります。パラメータが記載されていても、すべての対象に適用できるとは限りません。たとえば、動画の並べ替えはクリエイターのフォロワー数による並べ替えを意味しません。パラメータの効果が確認できていない場合は、調査の結論には用いず、統合テストで検証してください。

インターフェース境界の違いを示す例として、TikTok公式の認可済みユーザー向けvideo/listでは、cursor、has_more、ページあたりのmax_countが規定されています。TikTok公式のページネーションパラメータをEveryInfraのuser_videosに適用しないでください。ページネーションに対応しているかどうかは、対象エンドポイントのドキュメントと実際の結果によってのみ決まります。

ステップ4：アカウント、動画、観測の個別保存

データは3種類のオブジェクトに整理できます。識別情報とプロフィールの観測を扱うアカウントテーブル、動画IDでコンテンツとアカウントを紐付ける動画テーブル、特定のリクエストから得た指標値、条件、タイムスタンプを保存する観測テーブルです。この構造により、動画の再生数が更新されるたびにクリエイターのプロフィールが重複することを防げます。

• アカウントの観測：user_id、リクエストしたハンドル、返されたハンドル、プロフィール参照、取得できたカウント値、観測タイムスタンプ、リクエストID。
• 動画の観測：動画ID、URL、text、投稿者ハンドル、posted_at、エンゲージメント数・再生数、観測タイムスタンプ、リクエストID。
• 派生分析：使用した動画、除外したレコード、指標の計算式バージョン、計算タイムスタンプ、手入力のメモ。

curl -fsS --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/fields?platform=tiktok&action=user_videos' \
  | jq '{fields, undocumented}'

動画ディレクトリにはlike_count、comment_count、share_count、view_countが記載されています。公式の動画ドキュメントでは、いいね、コメント、シェア、再生数について説明されており、用語の確認に役立ちます。ただし、EveryInfraが公式のフィールドをすべて返すことを保証するものではありません。各エンドポイントのレスポンスを、実際の内容に基づいてパースしてください。

null値、フィールドの欠落、0は区別してください。報告されていない再生数を0で埋めることはできず、欠落しているシェア数を暗黙のうちにエンゲージメントの計算に含めるべきではありません。posted_atとobserved_atは異なります。前者は公開日時を示し、後者は観測日時を記録します。

ステップ5：エンゲージメント率の計算前に行う計算式の定義

すべてのチームに当てはまる単一のエンゲージメント率の計算式はありません。説明用のサンプル指標として、「エンゲージメント対再生比率＝条件を満たすサンプルのいいね、コメント、シェアの合計÷同じサンプルの総再生数」と定義します。分子はエンゲージメントイベント、分母は再生数を表し、いずれもユニークユーザー数やコンバージョン率を表すものではありません。

このガイドでは、カウントが有効な非負整数で、再生数が0より大きいレコードを対象とし、不完全なレコードは別途一覧にします。この保守的なルールにより、欠落データが0で隠されるのを防ぎます。独自の定義を用いる場合はルールの調整とバージョン管理が必要です。異なる計算式による結果をまとめて順位付けすることはできません。

function interactionPerView(rows) {
  const seen = new Set();
  let events = 0, views = 0, used = 0;
  const excluded = [];
  for (const row of rows) {
    if (typeof row.id !== "string" || !row.id || seen.has(row.id)) {
      throw new Error("missing or duplicate video id");
    }
    seen.add(row.id);
    const counts = [row.like_count, row.comment_count,
                    row.share_count, row.view_count];
    if (!counts.every(x => Number.isSafeInteger(x) && x >= 0)
        || row.view_count === 0) {
      excluded.push(row.id);
      continue;
    }
    events += row.like_count + row.comment_count + row.share_count;
    views += row.view_count;
    if (!Number.isSafeInteger(events) || !Number.isSafeInteger(views)) {
      throw new Error("aggregate exceeds safe integer range");
    }
    used++;
  }
  return {used, excluded, events, views,
          ratio: views > 0 ? events / views : null};
}

console.log(interactionPerView([
  {id: "synthetic-a", like_count: 8, comment_count: 1,
   share_count: 1, view_count: 100},
  {id: "synthetic-b", like_count: 7, comment_count: 1,
   share_count: 1, view_count: 10},
  {id: "synthetic-c", like_count: null, comment_count: 1,
   share_count: 0, view_count: 20}
]));

3件の合成レコードのうち、最初の2件は計算に含まれ、3件目はいいね数の欠落により除外されます。エンゲージメントの合計は19、総再生数は110で、エンゲージメント対再生比率は約17.27%です。個々の比率を平均すると50%になりますが、これらは異なる問いに答えるものです。前者は再生数で重み付けし、後者は各動画を均等に重み付けします。レポートではどちらを選んだかを明記してください。

この例はクリエイター評価のベンチマークでも業界標準でもありません。アカウントでは、平均的なパフォーマンスの中に突出したコンテンツが含まれることがあります。また、コンテンツの長さ、公開タイミング、選定基準も比較可能性に影響します。単一のパーセンテージよりも、サンプルサイズ、除外件数、総再生数、観測期間を提示するほうが有用です。

ステップ6：スクリーニング結果における人による解釈の余地の確保

公開データは確認すべきアカウントの優先順位付けに役立ちますが、コンテンツの確認に代わるものではありません。動画群を確認する際は、トピックの関連性、ターゲットオーディエンスとの適合性、最近のコンテンツが十分にあるかを確認してください。コンテンツの適性に関する結論には、ブラックボックスのスコアではなく具体的な根拠が必要です。

プロフィール文、名前、アバター、言語から機微な個人属性を推測しないでください。検証済みのオーディエンスデータ、コンバージョン、フルフィルメント指標を必要とする商業的なパートナーシップでは、適切な認可と協業のワークフローを用いてください。そうした根拠がない場合は、モデルを使って完全なプロフィールを捏造するのではなく、フィールドを不明としてマークしてください。

商品リサーチには明確な方法論が必要です。商品への言及、プロフィールリンク、ストア情報だけでは、実際の売上、純収益、ROIを裏付けることはできません。このガイドの2つのアクションは商業的な成果を証明するものではありません。推定GMVをプラットフォームが示す事実として出力テーブルに含めないでください。

ステップ7：反復観測による変化の追跡

プロフィールや動画の単発の呼び出しで得られるのはスナップショットです。成長を分析するには、比較可能な観測が必要です。アカウントの識別情報が一貫していること、フィールド定義が一致していること、観測間隔が明確であること、各実行でデータ取得に成功していることが条件です。後続の取得が失敗しても、フォロワー数や再生数が0に落ちたことを意味するわけではありません。

固定の動画セットとローリングの動画セットは区別してください。固定のグループを追跡すると時間経過によるカウントの変化を捉えられますが、最近の動画群を取得する方法ではコンテンツセット自体が入れ替わります。動画の構成を追跡せずにこれらの系列をつなげて1本の曲線にすると、その曲線は解釈できなくなります。

動画が見えなくなっても削除の証明にはなりません。現在のサンプルの範囲外になっただけの可能性があります。名前の変更、固定表示の変更、タイムスタンプのパース失敗、フィールドの欠落は品質メモに記録してください。データ量が減ったからといって、クリエイターを自動的に異常または信頼できないと判定しないでください。

スクリーニング結果の変化をたどる際は、W3C PROVのエンティティ、アクティビティ、派生の考え方を取り入れ、動画サンプル、ルールのバージョン、生成されたリストを関連付けてください。これは概念上の原則を借用するもので、RDFの導入を義務付けたり、PROVの交換仕様への準拠を主張したりするものではありません。

エラー時に復旧可能なレコードの保持

401、403、クォータの問題については、認証、機能の権限、アカウントの条件をそれぞれ個別に確認してください。パラメータエラーは、失敗するリクエストを繰り返すのではなく、レスポンスのヒントに基づいて修正してください。認識できないレスポンス形式はレビューキューに回し、プロフィールの空オブジェクトと動画リストの空配列を1つの成功状態にまとめないでください。

ネットワークのタイムアウト後でも、サーバー側ではリクエストが完了している場合があります。重複課金が発生しないと決めつけて闇雲にリトライしないでください。呼び出しログを確認する前に、開始・終了タイムスタンプ、アクション、機微でないパラメータの概要、トラッキングIDを保持してください。実際のコストは、最終的なリサーチ結果の行数ではなく、課金と請求書によって決まります。

検証可能なスクリーニングリストの納品

活用できるクリエイターのスクリーニング記録には、選定理由と根拠の範囲が必要です。アカウントの同一性、サンプルの取得元、観測タイムスタンプ、計算ルール、除外項目、コンテンツ確認メモ、パートナーへの確認待ち事項を記録してください。単一のAPIレスポンスを完全なデューデリジェンスとして扱ったり、公開データが閲覧できることを保存・再表示の無制限の許可とみなしたりしないでください。

規模を拡大する前に、権限のあるアカウントでプロフィール、動画、指標を検証してください。データAPIは手作業による収集の手間を減らしますが、スクリーニングの質は、指標を明確に説明し、すべての判断を実際のサンプルに基づいて行うことにかかっています。