---
url: https://developers.webzenk.kr/api/leaderboards.md
---
# 랭킹

| | 경로 | 인증 | 설명 |
|---|---|---|---|
| GET | `/v1/leaderboards` | 유저 | 리더보드 목록 |
| POST | `/v1/leaderboards/{code}/scores` | 유저 | 점수 제출 |
| GET | `/v1/leaderboards/{code}/top` | 유저 | 상위 순위 `?limit=100` |
| GET | `/v1/leaderboards/{code}/me` | 유저 | 내 순위와 위아래 `?around=5` |
| GET | `/v1/leaderboards/{code}/seasons/{season}` | 유저 | 끝난 시즌 결과 `?limit=&offset=` |
| GET | `/v1/leaderboards/{code}/seasons/{season}/me` | 유저 | 끝난 시즌 내 순위 |

## 목록

GET `/v1/leaderboards` → `{ "items": [ … ] }`

```json
{ "leaderboard": "weekly", "name": "주간 랭킹", "sort": "desc", "policy": "best",
  "reset_cycle": "weekly", "season": 202647, "season_ends_at": 1795359600 }
```

## 점수 제출

POST `/v1/leaderboards/{code}/scores` — `{ "score": 1530, "meta": { "stage": 3 }? }`

```json
{ "leaderboard": "weekly", "season": 202647, "score": 1530, "submitted": 1530, "updated": true, "rank": 12, "total": 840 }
```

`score`는 저장된 점수입니다(최고 기록 정책이면 더 낮은 점수를 내도 그대로). `updated`는 기록이 바뀌었는지 여부입니다.

## 순위 조회

GET `/v1/leaderboards/{code}/top?limit=50`

```json
{
  "leaderboard": "weekly", "season": 202647, "total": 840,
  "entries": [
    { "rank": 1, "player_id": "2048", "score": 98200, "achieved_at": 1795040000, "profile": { "nick": "wk" } }
  ]
}
```

`profile`은 그 유저가 `profile` 키로 공개 저장한 값입니다(없으면 `null`).

GET `/v1/leaderboards/{code}/me?around=5` → 목록 정보 + `me`(내 항목, 기록이 없으면 `null`) + `entries`(위아래)

## 끝난 시즌

GET `/v1/leaderboards/{code}/seasons/{season}` → `{ "total_ranked", "entries": [ … ] }` — 진행 중인 시즌이면 `404`
GET `/v1/leaderboards/{code}/seasons/{season}/me` → `{ "me": { … } | null }`

시즌 번호: 일간 `YYYYMMDD` · 주간 `YYYYWW`(ISO) · 월간 `YYYYMM` · 수동·계속은 1부터

## 오류

| 오류 | 뜻 |
|---|---|
| `404 NOT_FOUND` | 없는 리더보드 / 진행 중 시즌 조회 |
| `422 SCORE_OUT_OF_RANGE` | 허용 범위 밖 점수 |
| `429 SUBMIT_TOO_FAST` | 제출 간격 제한 |
