리더보드

모든 콘테스트에 대해 순위별 리더보드를 가져옵니다. 바이럴 및 추천 캠페인은 포인트로 순위가 매겨지며, 제휴 캠페인은 획득한 커미션으로 순위가 매겨집니다.

리더보드 가져오기

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

Public or Private API Key

순위가 매겨진 콘테스트 참가자 목록을 반환합니다. 확인된(confirmed) 비실격(disqualified) 참가자만 포함됩니다.

바이럴 / 추천 캠페인: 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의 콘테스트가 존재하지 않습니다