Tiers API

The API has 3 routes:

• /tierlists
• /profile/:uuid
• /search_profile/:name
• /all (not available on mctiers)

All routes return JSON objects. The base URL for my public instance is https://api.uku3lig.net/tiers.

Routes

/tierlists

Returns a JSON object of all the gamemodes available via the API. The keys of this object are equal to the keys of the rankings object in a Ranking.

The values are objects containing the following:

1. title: Fancy, capitalized name of the gamemode;
2. info_text: Markdown string containing info about the gamemode, see example;
3. kit_image: A direct link to an image showing an example kit for that gamemode.

/profile/:uuid

The uuid parameter is a v4 UUID without dashes.

This route either returns a 404 without content if there is no matching record, or a 200 with a Ranking object.

/search_profile/:name

The name parameter is the queried player's Minecraft username.

This route either returns a 404 without content if there is no matching record, or a 200 with a Ranking object.

/all

Note

This route does not exist in the upstream mctiers.com api.

This route returns an object with three fields:

• rankings: an array of Ranking objects, containing all recently queried rankings or all of them if your database is small enough,
• unknown: an array of UUID's (serialized as strings) of recently queried players that were not found in the tierlist. This exists to avoid spamming the api with requests of players that do not have a ranking,
• fetch_unknown: a boolean value indicating whether the mod should request tiers for unknown players. see following paragraph.

Ideally, this route should always return 200.

fetch_unknown

Setting fetch_unknown mostly depends on your database size. If you judge that your row count is low enough (such as if you have less than 500 users in your database for example), you can set fetch_unknown to false. This will prevent the client from sending any requests for players that are not found in its internal cache; just make sure you do return all the players you have information on in the rankings field.

Example responses

{
  "rankings": [
    {
      "uuid": "6553509f66d34041875f164236e42e84",
      "name": "uku3lig",
      // ...
    }
  ],
  "unknown": ["0123456789abcdef0123456789abcdef"],
  "fetch_unknown": true
}

{
  "rankings": [
    {
      "uuid": "6553509f66d34041875f164236e42e84",
      "name": "uku3lig",
      // ...
    }
  ],
  // here we intentionally keep unknown empty and set fetch_unknown to false because rankings already has all the players in the database
  "unknown": [],
  "fetch_unknown": false
}

Objects

Ranking

Note

This object is identical to the ranking object returned by the mctiers.com API. If you're querying them, you can return these objects as-is.

{
  // The player's UUID.
  "uuid": "d219c8eed32e4da2b22e0aa69d36c88a",
  // The player's Minecraft username.
  "name": "Marlowww",
  // The player's region.
  "region": "NA",
  // The player's points, calculated from their tier in each gamemode. Higher is better.
  "points": 268,
  // The player's overall rank in points.
  "overall": 2,

  // The player's tier rankings.
  // The key of each object is the gamemode, there are 7 of them: vanilla, smp, sword, pot, neth_pot, uhc, axe.
  "rankings": { 
    "vanilla": {
      "tier": 2, // The tier itself, ranges from 1-5. Lower is better.
      "pos": 0, // 0 for a high tier, 1 for a low tier.
      "peak_tier": 1, // Same as tier, can safely be null.
      "peak_pos": 0, // Same as pos, can safely be null.
      "attained": 1722570158, // Instant when the tier was attained, in seconds since unix epoch.
      "retired": false // Whether or not the player is retired.
    },
    // ...
  },

  // The player's badges. Currently not displayed anywhere on the website.
  // Each object only has title and desc.
  // Can safely be left empty if not needed.
  "badges": [
    {
      "title": "Holding The Crown",
      "desc": "T1 category of 1 gamemode for 30 days or more"
    },
    // ...
  ]
}