Douyin User Videos
このエンドポイントは、Douyinクリエイター1人の識別情報から、1ページ分の公開動画レコードを生成します。各レコードには、ソースが提供している場合、キャプション、投稿者情報、ソースURL、公開日時と取得日時、メディア、再生時間、表示中の再生数・いいね数・コメント数・シェア数・視聴数が含まれます。
Douyin User Videos API の主な機能
- 2通りのクリエイター指定方法対応するDouyinプロフィールURL、または既知の user_id を送信します。両方のフィールドがある場合は、直接指定された user_id が使用されます。
- 明確な1ページ分の範囲要求する結果件数を1〜20から選べます。デフォルトかつ上限は20で、プロバイダーへのリクエストは常に1ページ目から開始します。
- 動画とクリエイターのコンテキストを一括保持正規化されたキャプション、公開投稿者フィールド、ソースURL、タイムスタンプ、メディア参照、再生時間を各 reel-video レコードに保持します。
- 観測に適したエンゲージメントフィールド取得可能な再生数・いいね数・コメント数・シェア数・視聴数を collected_at とともに保持し、表示中のすべての数値を取得日時に結び付けます。
Douyin User Videos API のパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
url | 必須(いずれか1つ以上) | ホスト名が douyin.com、iesdouyin.com、またはそのサブドメインで、パスに /user/{identifier} を含むDouyinプロフィールの参照です。url または user_id を指定してください。両方がある場合は user_id が優先されます。 |
user_id | 必須(いずれか1つ以上) | ASCIIの英字、数字、コロン、アンダースコア、ハイフンからなる1〜256文字の既知のユーザー識別子です。user_id または url を指定してください。 |
results_limit | 任意 | プロバイダーの1ページ分から要求するレコード数です。1〜20の整数を受け付け、デフォルトは20です。 |
Douyin User Videos API の使い方
公開クリエイターの識別情報を1つ送信して非同期タスクを追跡し、保存された正規化動画レコードを読み取ります。
- /user/{identifier} のパスを含む douyin.com または iesdouyin.com 上のDouyinプロフィールURL、または既知の user_id のどちらかを用意します。
- 識別情報と、任意で1〜20の results_limit を /v1/douyin/user-videos に POST し、task_id を保存します。
- タスクが成功または失敗するまで、/v1/tasks/{task_id} をポーリングします。
- data.results.items を読み取ります。next_cursor は、SocQにすでに保存された追加レコードを読む場合にのみ使用し、プロバイダーの別ページを取得するものではありません。
curl -X POST "https://api.socq.ai/v1/douyin/user-videos" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"'"$DOUYIN_PROFILE_URL"'","results_limit":20}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and use next_cursor only for stored resultsDouyin User Videos API の主なユースケース
- クリエイターフィードのスナップショット: 選んだ観測時点で、クリエイター1人の公開動画を件数を絞って取得日時とともに保存します。
- 動画カタログの補完: 既存のクリエイターレコードに、正規化されたキャプション、投稿者情報、ソースURL、公開日時、再生時間、取得可能なメディアを追加します。
- クリエイティブとフォーマットの確認: 返されたキャプション、再生時間、メディアのフィールドを確認し、取得できた動画をコンテンツの演出やフォーマットごとに整理します。
- スナップショット内のエンゲージメント比較: collected_at を保持したまま、返された動画間で取得可能な再生数・いいね数・コメント数・シェア数・視聴数を比較します。
Douyin User Videos API 活用のヒント
- リクエストごとに識別情報のフィールドは1つにすることをおすすめします。url と user_id の両方を含めた場合、バックエンドは user_id を選択します。
- 送信前にURLのホストと /user/{identifier} のパスを検証してください。一般的なDouyin動画のURLでは、このエンドポイントの条件を満たしません。
- results_limit は、デフォルトの20件より少ない件数で十分な場合にのみ設定してください。値は1〜20の整数である必要があります。
- タスク結果のカーソルをDouyinソースのカーソルとして扱わないでください。ソースへのリクエストは1ページ分のみで、プロバイダーのカーソルは1ページ目に固定されています。
- 任意の投稿者、メディア、再生時間、公開日時、個々の指標が null や空のままになることを許容し、観測結果を保存する際は id と collected_at を組み合わせて使用してください。
関連API
Douyin User Videos API 以外に別の種類の公開Douyinデータが必要な場合は、これらのAPIをご利用ください。
- Douyin Live Room Detail API — 数値のルームIDから既知のDouyinライブ配信ルーム1件を取得し、正規化されたルーム情報、配信者情報、メディア、表示中の視聴者数を返します。
- Douyin User Profile API
- Douyin Video Comments API
- Douyin Video Detail API
- Douyin Video Search API