Ladder data for organizers and analysts

Everything the Patch Clash ladder publishes on screen is also available as data, so an organizer can seed a bracket from it and a balance designer can work in a spreadsheet. These endpoints are public: no sign-in, no key. They are served from https://vespene.gg, and mod defaults to patchclash when you leave it out.

Please be gentle. The seeding and metrics endpoints are cached for about a minute, so polling them faster gains nothing, and the rankings and feed are computed live, so poll those no more often than you need.

Seeding API (for tournament organizers)#

Seeding a Patch Clash event by hand means looking up every entrant's ladder form. This does it in one call.

Endpoint	Returns
GET /api/mod-ladder/seeding	Every player with at least one game on the ladder
GET /api/mod-ladder/seeding?names=Alpha,Bravo%231234	Only the players you name, plus a lookup report (write # as %23 in a URL)
GET /api/mod-ladder/seeding/export?format=csv	The whole list as a CSV download (format=json also works)

Each player row carries:

• seed: their best shown rating across all race books, that book's board rank, the race, and whether it is still in placement.
• books: one entry per race with rating, games, wins, losses, draws, peak, streak and last played.
• ladder: totals, best peak, and form (up to their last ten results, newest first).
• events: completed tournaments played on the mod, with placement, seed, match record, and how many of the event's games were on the mod (so you can judge a mixed event yourself). Hidden ladder matches are never counted as events, and events whose standings are still embargoed are left out.

Rows are ordered by board rank.

How names are matched#

Names are matched exactly (ignoring case) against full battletags, battletag names, display names and usernames of players who have played on the ladder. It never guesses:

Status	Meaning
resolved	Exactly one player matched; their row is included
ambiguous	Several players share that name; the candidates are listed so you can pick
no_book	The account exists but has no games on this ladder
unknown	Nobody by that name

Include the #1234 discriminator to pin a battletag exactly. An all-digit query is read as a Vespene user id. Up to 128 names per request, comma-separated or repeated.

Balance metrics API#

The numbers behind the Ladder stats door (Ladder stats, map pool and balance notes), identical to what the site shows.

Endpoint	Parameters
GET /api/mod-ladder/metrics	window = all, 90d, 30d or 7d; league = one or more of gm, master, diamond, plat, gold, silver, bronze (comma-separated), or all
GET /api/mod-ladder/metrics/export	cut (below), window, league, format = csv or json

Cuts: matchups, races, maps, openings, openings_by_matchup, tiers, durations, timeline, mirrors, vetoes, vetoes_by_matchup.

Rules worth knowing before you build on it:

• A league filter keeps only matches where both players were in the same selected league.
• Win rates come with games, decisive games, a Wilson 95% interval and a thin flag under 30 decisive games.
• Mirrors are excluded from race win rates and published separately; forfeits are excluded entirely; every exclusion is counted by reason.
• Veto cuts ignore window and league, publish in batches over closed days, and are rounded (see Ladder stats, map pool and balance notes for why). If the veto figures are temporarily unavailable the export answers 503 and asks you to retry in a minute.
• CSV files are UTF-8 with a byte-order mark, so they open correctly in Excel.

Other public endpoints#

These power the ladder screens and are handy for community tools:

Endpoint	What it is
GET /api/mod-ladder/mods	The ladder's configuration: map pool, bans, servers, live search window, season and prize split
GET /api/mod-ladder/rankings	The board, paged with limit (up to 500) and offset; order=live or prov
GET /api/mod-ladder/feed	Recent results, newest first (limit up to 100)
GET /api/mod-ladder/watch-reel	Recent matches with public replays (limit up to 30)
GET /api/mod-ladder/maps	The map pool report with bios and per-map stats (window)
GET /api/mod-ladder/balance	The mod's balance notes, structured by race
GET /api/mod-ladder/player/<user id>	One player's card: books, rating series and match history

Player-facing privacy rules apply to the data too: queue joins are never published with names, replay links only appear for public replays, and nothing an unranked player does exposes a hidden rating.