Boards set up on the dashboard (the project's Leaderboards) or by a service account. Each has an
id the game names it by, which end is the top (desc: highest first, asc: lowest first), and
what a new score does: keepBest keeps it only if it is better, keepLatest always replaces,
aggregate adds it to the player's total.
Reading needs no sign-in: anybody with the project id can read any board.
GET /leaderboards every board and its settings
GET /leaderboards/{id} one board
GET /leaderboards/{id}/scores?offset=0&limit=10 the standings, best first (limit up to 100)
GET /leaderboards/{id}/scores/players/{playerId} one player, with their rank
GET /leaderboards/{id}/scores/players/{playerId}/range?rangeLimit=5 them and up to 5 either side
GET /leaderboards/{id}/scores/players?ids=a,b,c several players: a friends list
{ "version": 3, "bucket": null, "total": 1520, "offset": 0, "limit": 10,
"results": [ { "playerId": "...", "playerName": "Ann", "rank": 0, "score": 9120, "tier": "Gold", "bucket": null,
"metadata": { "car": "red" }, "updatedAt": "..." } ] }
rank starts at 0 for the top, as Unity's does. Ties go to whoever got there first.
Submitting needs a signed-in player, and is always their own score:
POST /leaderboards/{id}/scores/me { "score": 1234, "metadata": { "car": "red" } }
GET /leaderboards/{id}/scores/me my entry and rank
GET /leaderboards/{id}/scores/me/range?rangeLimit=5
GET /leaderboards/{id}/scores/me/bucket?offset=0&limit=10 my bucket's standings
Authorization: Bearer mgds_...
The answer is the player's entry as it now stands, with "updated": false when a keepBest board
kept their earlier, better score. metadata is any JSON up to 2 KB, kept with the score it came
with. No score is judged: what counts as cheating is the game's to decide. A board marked
server only refuses players (403); its scores come from the game's own server, through a
service account (below), after it has checked them.
Buckets
A board with a bucket size groups players as they first score, that many to a bucket, and ranks each
bucket on its own: ranks, pages and ranges are all within the player's bucket. Read a bucket with
?bucket=2; a signed-in player who names none gets their own, and /scores/me/bucket gives it
directly.
Tiers
Named score bands: Bronze from 0, Silver from 1000, Gold from 5000. Each entry carries the best tier
its score reaches - at least the cutoff on a desc board, at most it on an asc one - or null.
Resets and archives
A board can reset daily, weekly or monthly at a UTC time, or by hand. A reset closes the current version, which stays readable, and starts an empty one:
GET /leaderboards/{id}/versions { "current": { "version": 4, "startedAt": "..." }, "archived": [ { "version": 3, "startedAt", "endedAt" } ] }
GET /leaderboards/{id}/versions/{version}/scores?offset=0&limit=10
GET /leaderboards/{id}/scores/players/{playerId}?version=3
A score sent the moment after a reset is due lands in the new version, whether or not anybody has looked at the board since.