TikTokの公開ページは、ユーザー名、動画、コメントスレッドと、一見シンプルです。しかし、収集の仕様はそうではありません。プロフィールは動画フィードではありません。コメントは返信ツリーの全体ではありません。検索は動画のみが対象です。ライブ配信ルームの照会では、ライブ配信を探し出すことはできません。
このチュートリアルでは、SocQ TikTok APIを使って、保守しやすい公開データのワークフローを構築します。エンドポイントの選び方、入力の整形、非同期タスク、正規化されたレコード、更新頻度、責任ある利用までを扱います。

ひとことで言うと: 公開されている入力ごとに
POST /v1/tiktok/{resource}へ振り分け、返されたタスクIDを保存し、完了するまで/v1/tasks/{id}をポーリングします。プロフィールのユーザー名を動画のエンドポイントに送らないでください。また、公開されていないフィールドを0として扱わないでください。
TikTok公式APIか、公開データAPIか
TikTokの公式のResearch、Display、Content Postingの各製品は、承認済みのリサーチ用アプリケーションがある場合、ログインで認可されたクリエイターや広告主のワークフローがある場合、投稿の公開が必要な場合に適した選択肢です。これらの製品では、アプリケーションの審査、OAuth、契約上のスコープが使われます。公開されている任意の動画を広く収集するためのものではありません。
このチュートリアルで使うSocQのエンドポイントは、既知の公開ユーザー名、動画URL、クエリ、ハッシュタグを受け付け、読み取り専用で収集します。TikTokのユーザーとして認証することはなく、返されたメディアを再利用する権利も付与せず、公式の投稿製品やリサーチ製品の代わりにもなりません。まずアクセスモデルを選んでください。認可済みまたは承認済みの業務には公式API、範囲を絞った公開データの読み取りには、対応している公開データAPIを使います。
コマースの出品は別の領域です。商品検索とレビューには、以下のソーシャル向けエンドポイントではなく、TikTok Shop APIを使ってください。
適切なTikTokエンドポイントを選ぶ
SocQは現在、12のTikTokリソースを提供しています。このチュートリアルでは、最も一般的な6つの収集ジョブに絞ります。残りも用意されているので、必要なときは明示的に振り分けてください。
| リソース | エンドポイント | 受け付ける公開入力 | 主な用途 |
|---|---|---|---|
| プロフィール | /v1/tiktok/profiles | ユーザー名(@ の有無は問わない) | アイデンティティ、プロフィール文、表示されている数値 |
| 動画 | /v1/tiktok/videos | 動画の直接URL | 既知の1本の動画とその指標 |
| ユーザーの動画 | /v1/tiktok/user-videos | ユーザー名 | クリエイターの公開フィードの一定範囲 |
| コメント | /v1/tiktok/comments | 動画URL | トップレベルのコメントのみ |
| 検索 | /v1/tiktok/search | クエリ | 動画のみの検索 |
| ハッシュタグ | /v1/tiktok/hashtags | タグ(# の有無は問わない) | ハッシュタグの動画の一定範囲 |
次のものも利用できますが、推測で使うと誤用しやすいので注意してください。
video-transcript:解決可能な公開動画URL向け。comment-replies:1つの動画URLと、既知のcomment_id向け。trending-feed:必須のregion向け。followers-listとfollowing-list:公開ユーザー名向け。live-room-info:既知のroom_idとuser_id向け。ライブ配信ルームを探し出したり、アカウントが配信を始めるのを待ったりすることはできません。
これらはいずれも公開データの読み取り操作です。実装ではなくベンダー選定が目的の場合は、TikTokスクレイパーAPIとTikTok APIの代替サービスでプロバイダーのモデルを比較してください。
リクエストを消費する前に入力を正規化する
生の入力は出所情報として保存し、コピーを正規の形に整えます。
- ユーザー名の先頭の
@とハッシュタグの先頭の#は取り除くか、そのままにします。どちらの形式も受け付けられますが、自社のレジストリでは1つの正規の形に統一してください。 - 空白を削除し、空の値は拒否します。
- プロフィールURLは、入力レイヤーでユーザー名に変換します。共有用やモバイル用のホストのURLは、動画IDがある場合に
www.tiktok.com/@user/video/{id}の形式に変換します。 - ユーザー名は大文字小文字を区別せずに、URLは正規のパスで重複を排除します。
- エンティティの種類で振り分けます。ユーザー名は動画URLではありません。ハッシュタグは検索クエリではありません。
results_limitは、完全性の保証ではなく、リクエストの上限として扱います。
user-videos は、20から2000までの results_limit、latest または popular の sort_by、任意の region を受け付けます。検索は動画のみが対象で、relevance、date、likes のいずれかの sort_by と、day、week、month、three_months、six_months のいずれかの published_within を受け付けます。
収集タスクを送信する
公開プロフィールを収集する:
curl -X POST "https://api.socq.ai/v1/tiktok/profiles" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"usernames":["tiktok","@natgeo"]}'
既知の動画を収集する:
curl -X POST "https://api.socq.ai/v1/tiktok/videos" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.tiktok.com/@tiktok/video/7234567890123456789"]}'
クリエイターのフィードの一定範囲を収集する:
curl -X POST "https://api.socq.ai/v1/tiktok/user-videos" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"usernames":["@tiktok"],"results_limit":20,"sort_by":"latest","region":"US"}'
トップレベルのコメントを収集し、コメントIDがすでにある場合に限って返信を収集する:
curl -X POST "https://api.socq.ai/v1/tiktok/comments" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.tiktok.com/@tiktok/video/7234567890123456789"],"results_limit":100}'
curl -X POST "https://api.socq.ai/v1/tiktok/comment-replies" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://www.tiktok.com/@scout2015/video/6718335390845095173","comment_id":"6718335906996502534","results_limit":20}'
検索とハッシュタグの探索も、同じ認証とタスクの形式を使います。
curl -X POST "https://api.socq.ai/v1/tiktok/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"python tutorial","results_limit":50,"sort_by":"relevance","published_within":"month"}'
レスポンスとして、非同期タスクが作成されます。そのIDは、社内のバッチIDや入力と一緒に保存してください。
重複を作らずにタスクをポーリングする
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
queued と running は想定された状態として扱います。指数バックオフと最大待ち時間を設定してポーリングします。成功したタスクでは data.results.items を処理し、has_more がtrueの場合は next_cursor を使って続けます。
ジョブのテーブルには、次の項目を記録してください。
- 社内のバッチIDとSocQのタスクID。
- リソースの種類と正規化した入力。
- 送信、最後のポーリング、完了の各タイムスタンプ。
- 終了状態と、正規化したエラーのカテゴリ。
- 最後にコミットした結果のカーソル。
ワーカーが再起動したというだけの理由で再送信しないでください。まず、保存してあるタスクの状態から再開します。
返されるフィールドを理解する
すべてのレコードは、id、platform、resource、type、url、created_at、collected_at、extra といった、正規化されたID関連のフィールドを共有します。リソース固有のフィールドは、明示的に分かれたままです。
プロフィールには、username、name、description、avatar_url、is_verified、is_private、表示されている指標が含まれます。そのクリエイターの動画の一覧ではありません。
動画には、caption、author、表示されている再生・いいね・コメント・シェアの指標、media、duration_seconds、hashtags、mentions、公開されている場合は music が含まれます。メディアのURLはソースへの参照であり、恒久的なダウンロード先ではありません。
コメントには、text、author、metrics.likes_count が含まれ、多くの場合 metrics.replies_count も含まれます。返信数は返信の本文ではありません。返信の本文を取得するには、comment-repliesと、同じ動画の comment_id が必要です。
検索とハッシュタグの結果は、動画と同じ形を再利用します。これらはランキングや期間で絞り込まれた探索結果であり、網羅的なアーカイブではありません。
取得できないデータは、null のままにするか、存在しないものとして扱ってください。非表示の再生数は0ではありません。取得できない文字起こしは、「発話なし」と扱ってよい空文字列ではありません。
複数種類のTikTok入力を扱うPythonワーカー
import time
import requests
BASE = "https://api.socq.ai/v1"
HEADERS = {
"Authorization": f"Bearer {SOCQ_API_KEY}",
"Content-Type": "application/json",
}
def collect(resource, payload):
created = requests.post(
f"{BASE}/tiktok/{resource}",
headers=HEADERS,
json=payload,
timeout=30,
)
created.raise_for_status()
task_id = created.json()["data"]["task_id"]
delay = 2
while True:
response = requests.get(
f"{BASE}/tasks/{task_id}",
headers=HEADERS,
timeout=30,
)
response.raise_for_status()
task = response.json()["data"]
if task["status"] == "succeeded":
return task["results"]["items"]
if task["status"] in {"failed", "cancelled"}:
raise RuntimeError(task)
time.sleep(delay)
delay = min(delay * 1.5, 15)
profiles = collect("profiles", {"usernames": ["tiktok"]})
videos = collect("user-videos", {
"usernames": ["tiktok"],
"results_limit": 20,
"sort_by": "latest",
})
本番では、ポーリングの前にタスクを保存し、next_cursor でページネーションを行い、一時的な失敗だけをリトライしてください。
エンティティとスナップショットを分けてモデル化する
プロフィールの変化はゆるやかです。動画の指標とコメントの量は、すばやく変化します。
tiktok_entity
platform_id
resource
canonical_url_or_username
stable public fields
first_seen_at
last_seen_at
tiktok_snapshot
platform_id
collected_at
visible metrics
mutable public fields
source_task_id
IDがある場合は、resource + id でエンティティをアップサートします。ない場合は、正規のURLまたはユーザー名で代用し、あとからIDが判明したときのためにマージの経路を残してください。スナップショットを追加するのは、収集が成功し、スキーマの検証を通過したあとだけです。
どちらかのスナップショットに指標がない場合は、増加を計算しないでください。非表示の数値は0ではありません。
本番に取り込む前に検証する
最低限、次の点を確認してください。
platformがtiktokであること。resourceが、使用したエンドポイントと一致すること。- プロフィールのレコードが、動画フィードとして扱われていないこと。
comment-repliesから取得したものを除き、コメントのレコードがトップレベルであること。- 検索結果が、ユーザーやサウンドではなく動画であること。
- 数値が存在する場合は、負でないこと。
created_atとcollected_atが、タイムスタンプとして解析できること。- すべてのレコードを、入力とタスクまで遡れること。
無効なレコードを黙って変換せず、隔離してください。生のレスポンス、検証エラー、収集時刻を残します。
エンティティごとに更新スケジュールを選ぶ
| エンティティ | 開始時の妥当な頻度 | 理由 |
|---|---|---|
| プロフィール | 週次または月次 | 公開されているプロフィール文やアイデンティティのフィールドは、ゆるやかにしか変わらない |
| 既知の動画 | 公開中は1時間ごとから1日ごと | 公開直後はエンゲージメントが急速に動く |
| ユーザーの動画の一定範囲 | モニタリングなら1日ごと | フィードはランキングされており、不完全である |
| コメント | 動画が活発な間は1時間ごとから1日ごと | 新しいトップレベルのコメントは、まとまって届く |
| 検索・ハッシュタグ | 1日ごと、または必要なとき | ランキングと期間が変化する |
| フォロワー・フォロー中 | 週次 | 関係の一覧は大きく、一部しか取得できない |
| ライブ配信ルーム | すでにルームが分かっている間だけ | このエンドポイントはライブ配信を探し出さない |
業務上の必要性とデータの最小化の考え方に基づいて、不要な収集を減らしてください。
よくある失敗パターン
エンドポイントがアイテムを返さない
ユーザー名またはURLが公開されていて、まだ利用可能で、正しいリソースに振り分けられているかを確認してください。非公開または削除された動画は、空のプロフィールではなく、入力レベルのエラーのままにします。
プロフィールに動画が「ない」ように見える
これは想定どおりです。profilesが返すのは、プロフィールのレコードだけです。フィードの一定範囲には、user-videosを使ってください。
コメントに返信数はあるが、返信の本文がない
コメントのエンドポイントが収集するのは、トップレベルのコメントです。返信の本文は、url と comment_id で取得してください。返信のエンドポイントは、動画URLだけから comment_id を探し出すことはできません。
検索でサウンドやユーザーが見つからなかった
検索は動画のみが対象です。ユーザー、サウンド、LIVEのディレクトリとして扱わないでください。
指標がブラウザの表示と一致しない
数値は収集時点のスナップショットであり、丸められていたり、非表示だったり、キャッシュされていたり、リクエストの間に更新されたりすることがあります。タイムスタンプとフィールドの定義を比べてください。
メディアのURLがあとで失敗する
動画、カバー、アバターのURLは、一時的なソースへの参照として扱ってください。更新するのは、ユースケースと利用規約が許す場合に限ります。
TikTokデータの責任ある利用
正当な目的に必要な公開フィールドだけを収集してください。ログインの壁、非公開アカウント、年齢制限、技術的な制限を回避してはいけません。センシティブな推論や、適切な保護措置なしに人に重大な影響を与えうる自動化された判断は避けてください。
TikTokのデータは個人データにあたる場合があります。必要な場合は適法な根拠を確立し、保持と削除の手順を定め、APIキーと保存したレコードを安全に管理し、適用される権利に対応し、TikTokの最新の利用規約と現地の法律を、資格のある法律の専門家と確認してください。公開データAPIは、音楽、肖像、動画ファイルに対する追加の権利を付与するものではありません。
TikTokが多数あるソースの1つである場合の、同じカタログのパターンは、ソーシャルメディア統合APIのガイドで説明しています。
よくある質問(FAQ)
TikTokのスクレイピングは合法ですか?
一律の答えはありません。法域、データ、アクセス方法、目的、契約、保護措置によって異なります。このチュートリアルは法的助言ではありません。
TikTokの公式APIは無料ですか?
公式のResearch、Display、Content Postingへのアクセスは、申請制または許可制です。このチュートリアルは公開データの読み取りのワークフローであり、それらの製品の代わりにはなりません。
非公開または削除された動画をスクレイピングできますか?
いいえ。プライバシーやアクセスの制御を回避してはいけません。削除済みや非公開の入力は、きちんと失敗させてください。
コメントのエンドポイントは返信の本文を返しますか?
いいえ。返すのはトップレベルのコメントです。返信数が含まれる場合はあります。返信の本文には、comment-repliesと comment_id が必要です。
動画のエンドポイントにプロフィールのURLを送れますか?
いいえ。動画のエンドポイントが受け付けるのは、動画の直接URLです。プロフィールとuser-videosは、ユーザー名を受け付けます。
検索はユーザーやサウンドを返しますか?
いいえ。現在の検索は、動画のみが対象です。
重複排除には、どのキーを使えばよいですか?
resource + id を優先してください。公開IDがない場合は、正規化した正規のURLまたはユーザー名で代用します。