リーダーボード

任意のコンテストのランク付けされたリーダーボードを取得します。バイラルおよび紹介キャンペーンはポイントでランク付けされます。アフィリエイトキャンペーンは獲得コミッションでランク付けされます。

リーダーボードを取得

GET/api/v1/contests/:contestId/leaderboard

Public or Private API Key

ランク付けされたコンテストエントリーのリストを返します。確認済みで失格になっていないエントリーのみが含まれます。

バイラル / 紹介キャンペーン: points の降順で並び替え
アフィリエイトキャンペーン: commission (totalCommissionEarned) の降順で並び替え

レスポンスには、ランキングの基準となる値を示すトップレベルの metric フィールド（"points" または "commission"）が含まれます。

パスパラメータ

contestIdstring required

一意のコンテスト識別子

クエリパラメータ

limitnumber

返却するエントリー数（1〜100）。デフォルト: 25

リクエスト

bash

curl -X GET "https://blitzrocket.com/api/v1/contests/clx1abc123/leaderboard?limit=10" \
  -H "x-api-key: your_api_key_here"

javascript

const contestId = "clx1abc123";
const response = await fetch(
  `https://blitzrocket.com/api/v1/contests/${contestId}/leaderboard?limit=10`,
  {
    headers: { "x-api-key": "your_api_key_here" },
  }
);

const { data } = await response.json();
data.forEach((entry) => {
  console.log(`#${entry.rank} ${entry.name || entry.email}: ${entry.points} pts`);
});

python

import requests

contest_id = "clx1abc123"
response = requests.get(
    f"https://blitzrocket.com/api/v1/contests/{contest_id}/leaderboard",
    headers={"x-api-key": "your_api_key_here"},
    params={"limit": 10}
)

data = response.json()["data"]
for entry in data:
    name = entry.get("name") or entry["email"]
    print(f"#{entry['rank']} {name}: {entry['points']} pts")

レスポンス

json

{
  "success": true,
  "metric": "points",
  "data": [
    {
      "rank": 1,
      "id": "entry_abc123",
      "email": "jane@example.com",
      "name": "Jane Doe",
      "points": 350,
      "commission": 0,
      "referralCode": "REF-XYZ789",
      "referralsCount": 12,
      "joinedAt": "2025-06-01T10:00:00.000Z"
    },
    {
      "rank": 2,
      "id": "entry_def456",
      "email": "john@example.com",
      "name": "John Smith",
      "points": 280,
      "referralCode": "REF-ABC456",
      "referralsCount": 8,
      "joinedAt": "2025-06-02T14:30:00.000Z"
    },
    {
      "rank": 3,
      "id": "entry_ghi789",
      "email": "alex@example.com",
      "name": null,
      "points": 195,
      "referralCode": "REF-DEF123",
      "referralsCount": 3,
      "joinedAt": "2025-06-03T09:15:00.000Z"
    }
  ]
}

レスポンスフィールド

ranknumber

リーダーボード上の順位（1始まり）

idstring

一意のエントリー識別子

emailstring

参加者のメールアドレス

namestring | null

参加者の名前

pointsnumber

獲得した合計ポイント

commissionnumber

獲得した合計コミッション（ドル単位、アフィリエイトキャンペーン）

metricstring

このコンテストのランキング基準：points または commission

referralCodestring | null

参加者の紹介コード

referralsCountnumber

成功した紹介の数

joinedAtstring

参加者が参加した日時の ISO 8601 タイムスタンプ

使用上の注意

emailConfirmed が true で disqualified が false のエントリーのみ返します
結果はキャンペーンモードに応じて points または commission で並び替えられます
limit パラメータは 1 から 100 の値を受け付けます
クライアント側のリーダーボードウィジェットを作成するためにパブリックキーでこのエンドポイントを使用できます

例：リーダーボードウィジェット

javascript

async function renderLeaderboard(contestId, container) {
  const response = await fetch(
    `https://blitzrocket.com/api/v1/contests/${contestId}/leaderboard?limit=10`,
    {
      headers: { "x-api-key": "your_public_key_here" },
    }
  );

  const { data } = await response.json();

  container.innerHTML = data
    .map(
      (entry) => `
      <div class="leaderboard-entry">
        <span class="rank">#${entry.rank}</span>
        <span class="name">${entry.name || "匿名"}</span>
        <span class="points">${entry.points} pts</span>
        <span class="referrals">${entry.referralsCount} 紹介</span>
      </div>
    `
    )
    .join("");
}

エラー応答

ステータス	エラー	説明
`400`	contestIdが不足	contestIdパスパラメータは必須です
`401`	APIキーが無効	APIキーが欠落しているか無効です
`404`	コンテストが見つかりません	指定されたIDのコンテストが存在しません