DonutStats API

01Getting a key

API keys are coming soon. They will be sold by the month. To be told when they open, send a note through the contact page with what you want to build.

02Making a request

The base address is https://api.donutstats.cc. Send your key in the x-api-key header, or as Authorization: Bearer <key>. All routes are GET unless it says otherwise, and all answers are JSON with an ok field.

curl -H "x-api-key: ds_live_your_key" https://api.donutstats.cc/v1/player/Steve

03A player

GET /v1/player/{name} returns one player. Names are 2 to 16 letters, digits or underscores; Bedrock names start with a dot.

{
  "ok": true,
  "player": {
    "name": "Steve",
    "stats": { "money": "12.4M", "shards": "3.2K", "kills": "412", "deaths": "198",
               "playtime": "21d 4h", "blocks_placed": "88K", "blocks_broken": "140K", "mobs_killed": "9.1K" },
    "num":   { "money": 12400000, "shards": 3200, "kills": 412, "deaths": 198,
               "playtime": 1828800, "blocks_placed": 88000, "blocks_broken": 140000, "mobs_killed": 9100 },
    "online": true,
    "lastSeen": 1794700000000,
    "updatedAt": 1794700000000,
    "ageSec": 42,
    "stale": false,
    "boards": { "money": 128 },
    "ranks": { "money": { "rank": 2210, "of": 68000 } },
    "tracked": false
  }
}

• stats is the text the game shows; num is the same as numbers (playtime in seconds).
• online is true, false, or null when it is not known. lastSeen and updatedAt are times in milliseconds.
• boards is the player's place on the server's own top 200 lists. ranks is their place among the players on DonutStats.
• Answers are saved for 10 minutes. Add ?maxAge=60 to ask for data no older than that many seconds (15 at the least).
• stale: true means you were over your limit and got the saved copy.

04History

GET /v1/player/{name}/history?days=30 returns saved points for charts, oldest first. days can be 1 to 365.

{ "ok": true, "name": "Steve", "days": 30,
  "points": [ { "at": 1794000000000, "money": 11900000, "shards": 3100, "kills": 405, "deaths": 196,
                "playtime": 1790000, "blocks_placed": 87000, "blocks_broken": 139000, "mobs_killed": 9000 } ] }

A point is stored when something changed, so a quiet player has few points.

05Leaderboards

GET /v1/board/{board}?limit=50&offset=0 returns the server's own top 200. board is one of money, deaths, playtime, blocks_placed, blocks_broken, mobs_killed.

{ "ok": true, "board": "money", "total": 200, "updatedAt": 1794700000000, "offset": 0,
  "entries": [ { "rank": 1, "name": "Steve", "value": "5.7T", "n": 5700000000000, "online": true } ] }

• GET /v1/boards lists the boards with how many entries each has and when it was last updated.
• GET /v1/top/{stat}?limit=25&offset=0 ranks the players on DonutStats by any stat, including kills and shards, which the game has no board for. limit is 100 at most.

06Server and search

• GET /v1/counts: players on record, players online now and the 24-hour peak.
• GET /v1/online?hours=24: the player count over time, as [{ at, players }].
• GET /v1/search?q=ste&limit=8: players whose name starts with the text.

07Tracking

A tracked player is updated about every 30 minutes, so their history fills in.

• POST /v1/track/{name} starts tracking.
• DELETE /v1/track/{name} stops it.
• GET /v1/track/{name} says whether the player is tracked.

08Limits

Each key has two limits a minute: requests of any kind, and requests that need new data. An answer from the saved copy does not count towards the second one.

• GET /v1/limits shows both limits and how much is left.
• Player answers carry x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset headers.
• Over the limit you get 429 with retryAfter in seconds and a Retry-After header, or the saved copy marked stale when there is one.

09Errors

An error is { "ok": false, "error": "..." } with one of these codes:

• 400 bad_name, bad_board, bad_stat: the request is not valid.
• 401 invalid_api_key: the key is wrong or has been switched off.
• 403 origin_not_allowed: no key was sent.
• 404 player_not_found: no such player on DonutSMP.
• 429 rate_limited: slow down and try again after retryAfter seconds.
• 503 lookup_unavailable: new data could not be fetched just now. Try again shortly.

10Fair use

Values are rounded the way the game shows them. Say where the data comes from if you show it publicly, and do not resell raw copies of it. DonutStats is not affiliated with DonutSMP or Mojang AB.