API Reference · 랭킹

랭킹 목록 조회

캠페인이 종료된 후 확정된 랭킹 스냅샷을 조회합니다. 진행 중인 캠페인은 실시간 랭킹 API 를 사용하세요.

GET/api/v1/campaigns/{campaign_id}/rankings

인증

아래 두 형식을 모두 지원합니다 (영구 호환).

Authorization: Bearer <publisher_secret> (권장)
Authorization: Basic base64(publisher_id:publisher_secret)

요청 파라미터

campaign_id (path, uuid v7, required) — 조회할 캠페인 식별자입니다.
type (query, enum, optional) — 랭킹 집계 기준입니다. 생략 시 캠페인에 설정된 default_ranking_type 이 적용됩니다.
- score: 게임 점수 기준
- point: 적립 포인트 기준
- level: 게임 레벨 기준
- event: 사전에 정의한 게임 미션 이벤트 달성 기준
offset (query, integer, optional, default=0) — 조회 항목 시작 번호입니다.
limit (query, integer, optional, default=100, max=1000) — 한 번에 조회할 항목 수입니다.

요청예시

shell

curl -H "Authorization: Bearer $PUBLISHER_SECRET" \
     "https://added.blomics.net/api/v1/campaigns/$CAMPAIGN_ID/rankings?type=score&offset=0&limit=100"

응답 필드

campaign_id (uuid v7) — 요청한 조회 캠페인 식별자입니다.
ranking_type (enum) — 반영된 타입 (score | point | level | event) 랭킹 집계 유형입니다.
- score: 게임 점수 기준
- point: 적립 포인트 기준
- level: 게임 레벨 기준
- event: 사전에 정의한 게임 미션 이벤트 달성 기준
snapshot_at (ISO 8601 UTC | null) — 스냅샷 생성/갱신 시각이며 조회된 페이지에 행이 없는 경우 null 입니다.
items (array) — 랭킹 목록입니다.
- rank — 랭킹순위입니다.
- value — 랭킹 유형에 따른 기준 값입니다.
- publisher_user_id — 매체사 사용자 식별값입니다.
offset (integer) — 조회 항목 시작 번호를 그대로 반환합니다.
limit (integer) — 한 번에 조회할 항목 수를 그대로 반환합니다.
total (integer) — 전체 항목 수를 반환합니다.

응답예시

json

{
  "campaign_id": "0193...",
  "ranking_type": "score",
  "snapshot_at": "2026-04-20T00:00:00.000Z",
  "items": [
    { "rank": 1, "value": 24800, "publisher_user_id": "p-100" },
    { "rank": 2, "value": 21500, "publisher_user_id": "p-204" }
  ],
  "offset": 0,
  "limit": 100,
  "total": 3580
}

에러처리

400 INVALID_PARAM — 파라미터 형식 오류.
401 UNAUTHORIZED — 인증 실패.
404 NOT_FOUND — 잘못된 캠페인 또는 소유권 위반, 혹은 해당 캠페인의 랭킹 스냅샷이 아직 생성되지 않은 경우.
500 INTERNAL_ERROR — 서버 오류.