API v2 Documentation

Read player tiers and rankings from Python, Java, JavaScript, Discord bots, Minecraft plugins, and external tier display tools.

Base URL
https://mcrank.lt3prac.net/api/v2

GET only Read-only JSON No API key currently required

Endpoints

Gamemode keys: uhc, sword, mace, vanilla, netherite_pot, smp, axe_shield, diamond_smp.

Profile response

{
  "data": {
    "username": "ExamplePlayer",
    "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "location": "ASIA",
    "rank": 1,
    "points": {"overall": 60, "sword": 60, "uhc": 0},
    "modes": {
      "sword": {
        "current": {"tier":"HT1","level":1,"kind":"HT","points":60,"label":"High Tier 1"},
        "peak": {"tier":"HT1","level":1,"kind":"HT","points":60,"label":"High Tier 1"},
        "previous": {"tier":"LT1","level":1,"kind":"LT","points":45,"label":"Low Tier 1"},
        "points": 60
      }
    }
  }
}

The actual response includes all eight gamemode keys. Tier codes are HT1–HT5, LT1–LT5, or UNTIER.

Tier board response

{
  "data": {
    "mode": {"key":"sword","name":"Sword"},
    "tiers": {
      "tier1": {"ht": [], "lt": []},
      "tier2": {"ht": [], "lt": []},
      "tier3": {"ht": [], "lt": []},
      "tier4": {"ht": [], "lt": []},
      "tier5": {"ht": [], "lt": []}
    }
  }
}

Each entry contains the player username, UUID, stored region, and current/peak/previous tier metadata.

Python example

import requests

BASE = "https://mcrank.lt3prac.net/api/v2"
r = requests.get(f"{BASE}/players/ExamplePlayer", timeout=10)
r.raise_for_status()
profile = r.json()["data"]
print(profile["username"], profile["location"])
print(profile["modes"]["sword"]["current"]["tier"])

Java example (Java 11+)

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder(URI.create(
    "https://mcrank.lt3prac.net/api/v2/players/ExamplePlayer"
)).GET().build();
HttpResponse<String> response = client.send(
    request, HttpResponse.BodyHandlers.ofString()
);
if (response.statusCode() == 200) {
    System.out.println(response.body()); // Parse JSON with Gson or Jackson
}

Imports: java.net.URI, java.net.http.HttpClient, java.net.http.HttpRequest, and java.net.http.HttpResponse.

JavaScript / Node.js example

const response = await fetch(
  "https://mcrank.lt3prac.net/api/v2/players/ExamplePlayer"
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const { data: profile } = await response.json();
console.log(profile.username, profile.modes.sword.current.tier);

Region values

The location property is the stored player region, not the combined Discord waitlist channel group. Canonical values are NORTH_AMERICA, EUROPE, ASIA, AUSTRALIA, and SOUTH_AMERICA. Display abbreviations may be NA, EU, AS, AU, and SA.

Errors

{"error":{"code":"player_not_found","message":"Player not found."}}

Clients should set timeouts and handle non-200 responses. The API does not expose SQL details in error messages.

OpenAPI schema

View or download the OpenAPI 3.0 JSON specification.

Full examples and endpoint details are also available in API.md in the source archive.