Snapchat Spotlight
公開Snapchat Spotlightのレコードには、ソースリンク、キャプション、クリエイターの識別情報、メディア参照、公開日時、再生時間、音源の詳細、表示中のエンゲージメント数が含まれる場合があります。正規化された結果は、取得できたこれらのフィールドを取得日時のタイムスタンプとともに保持し、選定した動画の確認、カタログ情報の補完、特定時点での比較に活用できます。
Snapchat Spotlight API の主な機能
- 既知のSpotlightの照会公開snapchat.comのURLを1件送信すると、フィードを展開することなく、対応する詳細レスポンスを最大1件の標準レコードに変換します。
- クリエイターと動画の情報ソースURLに加え、取得可能なキャプション、投稿者の識別情報、メディア、再生時間、音源、ハッシュタグ、メンション、公開日時を1つの固定された結果形式で保持します。
- 表示中のエンゲージメントのスナップショット取得可能ないいね数、コメント数、シェア数、再生数、閲覧数を collected_at とともに返し、後続の分析で観測時刻を保持できるようにします。
Snapchat Spotlight API のパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
url | 必須 | 必須。ホストがsnapchat.comまたはそのサブドメインである、空でないhttpまたはhttpsのURLです。ランタイムはパス名のルールを課していませんが、/@username/spotlight/{spotlight_id} のような公開Spotlightのリンクを使用してください。 |
Snapchat Spotlight API の使い方
公開Snapchat SpotlightのURLを1件送信して非同期タスクを追跡し、保存された正規化結果を読み取ります。
- snapchat.comまたはそのサブドメイン上の公開Snapchat SpotlightのURLをコピーします。
- URLを url として /v1/snapchat/spotlight に送信し、返された task_id を保存します。
- タスクが成功するか失敗を報告するまで /v1/tasks/{task_id} をポーリングします。
- data.results.items を読み取ります。保存済み結果のレスポンスで has_more が返された場合は、その next_cursor を使って続きを取得します。
curl -X POST "https://api.socq.ai/v1/snapchat/spotlight" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://www.snapchat.com/@queenhaley_13/spotlight/W7_EDlXWTBiXAEEniNoMPwAAYY2pnZnF0bG52AZslQsUdAZslQoRQAAAAAQ"}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items; next_cursor paginates stored results onlySnapchat Spotlight API の主なユースケース
- 選定したSpotlightの確認: 既知の公開リンクを、ソース、キャプション、投稿者、メディア、日時、取得可能なエンゲージメントのフィールドを持つ追跡可能なレコードに変換します。
- コンテンツカタログの情報補完: 既存のURLリストに、正規化された動画の識別情報、クリエイター情報、再生時間、音源、ハッシュタグ、メンション、取得日時を追加します。
- 取得したエンゲージメントの比較: 別々の観測結果を比較する際は、表示中の数値を collected_at と組み合わせ、リアルタイムや完全な値としては扱わないようにします。
Snapchat Spotlight API 活用のヒント
- url にはURLを必ず1件だけ指定してください。このエンドポイントでは配列、results_limit、usernames、callback_url は使用できません。
- 検証ではパス名ではなくSnapchatのホストのみを確認しますが、公開Spotlightのリンクを使用してください。無関係なSnapchatのパスはプロバイダー側で失敗する可能性があります。
- プロバイダーでの照会は最大1件のレコードを返す単一の詳細リクエストのため、タスク結果の next_cursor をソースフィードのページネーションとして扱わないでください。
- 公開レスポンスに含まれない場合に備えて、ID、キャプション、投稿者フィールド、メディア、タイムスタンプ、音源、個々の指標が null になることを許容してください。
- 各測定値が取得日時と結び付いた状態を保つため、エンゲージメント数の横に collected_at を保存してください。
- 成功したタスクごとに0.19クレジットを見込んでください。固定料金のため、返されるフィールドや結果件数によって変わりません。
関連API
Snapchat Spotlight API 以外に別の種類の公開Snapchatデータが必要な場合は、これらのAPIをご利用ください。