Skip to main content
GET
/
ranking
Get Players Ranking
curl --request GET \
  --url https://api.example.com/ranking
{
  "position": 123,
  "playerId": "<string>",
  "name": "<string>",
  "wins": 123,
  "losses": 123,
  "score": 123
}
Returns the ranking of players ordered by score (and tie-breakers). This endpoint provides a leaderboard view of all players in the system.

​
Response

The endpoint returns an array of ranking entries, each containing:
​
position
integer
The player’s position in the ranking (1 = first place, 2 = second place, etc.)
​
playerId
string
The unique identifier of the player
​
name
string
The player’s display name
​
wins
integer
The total number of games won by the player
​
losses
integer
The total number of games lost by the player
​
score
integer
The calculated score for the player, used for ranking purposes

​
Ranking Structure

Players are ordered by their score in descending order. The ranking algorithm considers:
  • Primary: Score value (higher is better)
  • Tie-breakers: Applied when players have the same score
The position field indicates the player’s rank, starting from 1 for the top-ranked player.

​
Request Example

curl -X GET https://api.example.com/ranking \
  -H "Content-Type: application/json"

​
Response Example

[
  {
    "position": 1,
    "playerId": "player-001",
    "name": "AceOfSpades",
    "wins": 42,
    "losses": 8,
    "score": 840
  },
  {
    "position": 2,
    "playerId": "player-002",
    "name": "CardShark",
    "wins": 35,
    "losses": 12,
    "score": 700
  },
  {
    "position": 3,
    "playerId": "player-003",
    "name": "LuckyPlayer",
    "wins": 28,
    "losses": 15,
    "score": 560
  },
  {
    "position": 4,
    "playerId": "player-004",
    "name": "BlackjackBob",
    "wins": 22,
    "losses": 18,
    "score": 440
  }
]

Build docs developers (and LLMs) love

Get started for freeTalk to us