Twitch Profile
公開Twitchプロフィールでは、ユーザー名、表示名、プロフィール文、プロフィール画像、Webサイト、認証・非公開の状態、所在地情報、表示中のアカウント数値が公開されている場合があります。正規化されたアカウントレコードは、クリエイター情報の補完、プロフィールの確認、繰り返し取得できる公開データのスナップショットに活用できますが、チャンネル管理や認証済みアカウントでの操作は提供しません。
Twitch Profile API の主な機能
- ユーザー名による正確な照会使用可能な文字で構成される1〜64文字の必須 username を1件送信します。先頭に @ を1つ付けることもできます。
- 正規化された公開アカウント情報取得可能なプロフィールID、公開URL、ユーザー名、表示名、プロフィール文、アバター、カバー画像、Webサイトを AccountItem 仕様で読み取れます。
- アカウント状態のシグナル取得可能な認証フラグと非公開フラグは null 許容のフィールドとして保持し、提供元が公開していない値を推測で補いません。
- 表示中のプロフィール指標取得可能なフォロワー数・フォロー数・投稿数を、取得時刻にひもづく個別の任意指標として利用できます。
- 非同期タスクの流れユーザー名を送信して task_id を保持し、共通のタスク取得APIをポーリングして、成功後に保存済みの正規化結果を取得します。
- リクエスト単位の固定料金成功したタスクの料金は固定で0.19 SocQクレジットで、任意フィールドの有無には左右されません。
Twitch Profile API のパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
username | 必須 | 必須。Twitchユーザー名です。前後の空白を除去した後、先頭に @ を1つ付けることができ、その後はASCIIの英字、数字、ドット、アンダースコア、ハイフンで構成される1〜64文字である必要があります。 |
Twitch Profile API の使い方
対応するTwitchユーザー名を1件送信して非同期タスクを追跡し、共通のカーソル形式のレスポンスで保存済みのプロフィール結果1件を読み取ります。
- 使用可能な文字のルールに合う公開Twitchユーザー名を1件選びます。
- username を /v1/twitch/profile に POST し、返された task_id を保存します。
- タスクが成功するか失敗を返すまで /v1/tasks/{task_id} をポーリングします。
- data.results.items を読み取ります。プロフィール照会で得られるソースレコードは最大1件ですが、保存済み結果のエンベロープには has_more と next_cursor も含まれます。
curl -X POST "https://api.socq.ai/v1/twitch/profile" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"username":"ninja"}'
# Poll GET /v1/tasks/{task_id}
# Read the normalized account in data.results.itemsTwitch Profile API の主なユースケース
- クリエイターレコードの情報補完: 既知のクリエイターレコードに、取得可能なTwitchのアカウント情報、プロフィール文、画像、Webサイト、アカウントフラグ、公開数値を追加します。
- ユーザー名の確認ワークフロー: 社内のエンティティや調査対象にひもづける前に、送信されたハンドルを正規化された公開プロフィールに照会します。
- 公開アカウントの比較: 個別に送信したユーザー名同士で、同じ AccountItem 形式を使って表示中のフォロワー数・フォロー数・投稿数を比較します。
- プロフィールの変化のモニタリング: null 許容のアカウント情報フィールドと指標を collected_at とともに保存し、後の実行結果を別々の公開スナップショットとして区別できるようにします。
Twitch Profile API 活用のヒント
- TwitchチャンネルのURLではなくユーザー名を送信してください。このエンドポイントでは url と results_limit はリクエストフィールドとして受け付けられません。
- 先頭の @ は任意で1つまでにしてください。空白、スラッシュ、ASCII以外の文字、@ の重複は、実行時のユーザー名ルールで失敗します。
- ソースのプロフィールレコードは0件または1件です。タスク取得APIの limit パラメータを、プロフィールから動画やフォロワーへ展開する手段と解釈しないでください。
- ID、URL、プロフィール文、画像、Webサイト、アカウントフラグ、所在地、各指標は null 許容として扱い、スナップショット比較のために collected_at を保存してください。
- 動画やクリップには、利用可能な場合は別のTwitchコンテンツ用エンドポイントを使用してください。このエンドポイントは読み取り専用のプロフィール照会で、ログイン、配信・投稿、モデレーション、チャンネル管理は行いません。
関連API
Twitch Profile API 以外に別の種類の公開Twitchデータが必要な場合は、これらのAPIをご利用ください。
- Twitch User Videos API
- Twitch Clip Downloader API — クリップURLから公開Twitchクリップを1件取得し、タイトル、再生数、長さ、作成日時、配信者プロフィール、ダウンロードできるMP4リンクとサムネイルを返します。