API Leaderboards

Rankings that move while people play, not at the next autosave. Every path starts with /api/v1.

Endpoint	Permission	What it does
GET /aggregates	players:read	Everyone's statistics added up
GET /leaderboards	players:read	The preset leaderboards
GET /leaderboards/{statistic}	players:read	Players ranked by a statistic, ties sharing a place

How ranking works

GET /leaderboards/{statistic} ranks everyone who has played. Tied players share a place, and the next place skips ahead: 1, 1, 3.

Presets

Preset	Counts	Unit
playtime	custom:play_time	hours
diamonds	mined:diamond_ore + mined:deepslate_diamond_ore	ores
advancements	Finished advancements, without recipes and tab roots	advancements
mobs	custom:mob_kills	mobs
travel	Every custom:*_one_cm way of moving	km
deaths	custom:deaths	deaths
blocks	mined:*	blocks
fish	custom:fish_caught	fish
damage	custom:damage_dealt	hearts
netherite	mined:ancient_debris	debris
experience	Experience points gained in total	xp
tamed	Animals tamed	animals

Any vanilla statistic

Name the statistic instead of a preset: custom:jump, killed:zombie, mined:emerald_ore, crafted:*.

Everyone together

GET /aggregates adds everyone up: hours, blocks and the block mined most, mobs and the mob killed most, deaths, advancements, the world's day, and the date of the first join.

Experience and tamed animals

Vanilla keeps neither, so WorldAPI counts them itself.

Experience. Each player starts once from the XpTotal in their playerdata: everyone with a playerdata file when 1.1.1 first started, anyone else when they join. From then on, every orb a player picks up, after other plugins had their say, adds to the total in the database; /xp commands don't count. XpTotal holds only what the player gathered since their last death, so the starting point is a lower bound. If 1.1.0 already counted pickups, the player starts from whichever is larger.

Tamed animals. On the first start of 2.4.0, WorldAPI counted the pets already in the world by their owners: wolves, cats, parrots, horses, donkeys, mules, llamas, camels, and the rest that keep an owner, from the loaded mobs and from the entity files of every world, once. Every taming after that adds one. A pet that died before that first count left no trace, so the board is a lower bound for the oldest players. The log says how many pets it found, and how many chunks it couldn't read, such as LZ4-compressed ones.

Next: Events.