Public API for Developers
The MCTIERS API gives you real-time access to comprehensive Minecraft PvP ranking data. Build Discord bots, web dashboards, streaming overlays, and clan management tools—all with public endpoints and zero barriers to entry.
Real-Time Ranking Data
Access live player rankings across all 10 game modes with instant updates.
Fully Public & Free
No authentication required. No rate limits that slow you down. Build what you want.
Developer-Friendly Docs
Clear endpoints, code examples in multiple languages, and active Discord support.
Whether you're building a Discord bot for your clan, a leaderboard widget for your website, or a streaming overlay to showcase rankings live—the MCTIERS API has the data you need, instantly accessible.
View API Documentation
Get Started with the MCTIERS API
Make your first API call in minutes. We've streamlined the setup process so you can start integrating Minecraft ranking data right away.
API Base URL & Structure
All MCTIERS API requests use a consistent base URL structure:
https://api.mctiers.com/v1
Endpoints are organized by resource type and follow RESTful conventions. All responses return JSON data.
Authentication
The MCTIERS API is publicly accessible—no authentication required for most endpoints. However, if you're making high-volume requests, consider including an API key for priority rate limits.
Authorization: Bearer YOUR_API_KEY
Optional header for authenticated requests. Leave it out for public access.
Your First API Call
Here's how to fetch player rankings in just a few lines of code:
// Fetch Overall rankings
const response = await fetch('https://api.mctiers.com/v1/rankings/overall');
const data = await response.json();
console.log(data.players); // Array of ranked players
# Fetch Overall rankings
import requests
response = requests.get('https://api.mctiers.com/v1/rankings/overall')
data = response.json()
curl -X GET 'https://api.mctiers.com/v1/rankings/overall'
Replace overall with any game mode: uhc, vanilla, sword, axe, mace, and more.
Response Format
All successful API responses return JSON with this structure:
{`{`}
"status": "success",
"data": {`{`}
"gameMode": "overall",
"timestamp": "2025-07-14T12:00:00Z",
"players": [
{`{`}
"rank": 1,
"username": "PlayerName",
"tier": "S+",
"region": "US",
"rating": 2850
{`}`}
]
{`}`}
{`}`}
Each player object includes rank, username, tier, region, and a numeric rating for sorting and comparisons.
Common Parameters & Filters
Filter by Region
?region=US
Returns rankings for a specific region (US, EU, ASIA, etc.)
Search by Username
?username=PlayerName
Find a specific player's rank and tier data.
Pagination
?page=1&limit=50
Retrieve paginated results (default: 50 players per page).
Sort & Order
?sort=rating&order=desc
Sort by rating, tier, or rank in ascending/descending order.
Error Handling
The API uses standard HTTP status codes. Here's what to expect:
Success
Request completed successfully.
Bad Request
Invalid parameters or malformed request. Check your syntax.
Rate Limited
Too many requests. Wait before retrying or use an API key.
Server Error
Something went wrong on our end. Check API status or try again.
You're Ready to Build
You now have everything needed to integrate MCTIERS ranking data into your project. Next steps:
- Explore all endpoints in our detailed API reference documentation.
- Try real code examples for Discord bots, web dashboards, and streaming overlays.
- Join our Discord to ask questions, share your builds, and stay updated on API changes.
API Endpoint Reference
Complete documentation for all MCTIERS API endpoints. Each endpoint is documented with its path, HTTP method, required and optional parameters, response schema, and example responses. Use this as your developer reference for integrating Minecraft rankings data into your tools and applications.
Player Endpoints
Get Player
Retrieve detailed player information and their current rankings across all game modes.
Parameters
Minecraft player username
Filter by region (e.g., "US", "EU", "ASIA")
Response
{
"username": "PlayerName",
"uuid": "uuid-string",
"region": "US",
"rankings": {
"overall": 145,
"uhc": 89,
"vanilla": 203
},
"lastUpdated": "2025-07-14T12:30:00Z"
}
Search Players
Search for players by username with optional filters and pagination.
Query Parameters
Search query (username prefix)
Number of results to return (max 50)
Pagination offset
Response
{
"results": [
{
"username": "PlayerName",
"uuid": "uuid-string",
"overallRank": 145
}
],
"total": 42,
"limit": 10,
"offset": 0
}
Ranking Endpoints
Get Rankings by Game Mode
Retrieve ranked leaderboards for a specific game mode with regional filtering and pagination.
Path & Query Parameters
Game mode: overall, uhc, vanilla, sword, axe, mace, pot, nethop, smp, ltm
Filter by region (US, EU, ASIA, GLOBAL)
Number of results (max 100)
Pagination offset
Response
{
"mode": "uhc",
"region": "US",
"rankings": [
{
"rank": 1,
"username": "TopPlayer",
"uuid": "uuid-string",
"elo": 1850,
"wins": 342,
"kills": 4521
}
],
"total": 2847,
"limit": 50,
"offset": 0
}
Get Player Rank in Mode
Get a specific player's ranking position and stats in a given game mode.
Parameters
Game mode identifier
Minecraft player username
Specify region for ranking
Response
{
"username": "PlayerName",
"mode": "sword",
"region": "US",
"rank": 42,
"elo": 1620,
"wins": 187,
"losses": 54,
"winRate": 77.6,
"lastUpdated": "2025-07-14T12:30:00Z"
}
Game Mode Endpoints
List All Game Modes
Get a complete list of all available ranking game modes on MCTIERS.
Parameters
No parameters required. Returns all active game modes.
Response
{
"modes": [
{
"id": "overall",
"name": "Overall",
"description": "Combined ranking",
"playerCount": 12847
},
{
"id": "uhc",
"name": "UHC",
"description": "Ultra Hardcore",
"playerCount": 8942
}
]
}
Get Game Mode Details
Retrieve detailed information about a specific game mode including player count and tier distribution.
Parameters
Game mode identifier
Response
{
"id": "vanilla",
"name": "Vanilla",
"description": "Vanilla PvP",
"totalPlayers": 6234,
"tierDistribution": {
"elite": 312,
"master": 845,
"expert": 1842
},
"lastUpdated": "2025-07-14T12:00:00Z"
}
Regional Endpoints
List Available Regions
Get all regions where player rankings are tracked.
Parameters
No parameters required.
Response
{
"regions": [
{
"id": "US",
"name": "United States",
"playerCount": 4821
},
{
"id": "EU",
"name": "Europe",
"playerCount": 3642
},
{
"id": "ASIA",
"name": "Asia",
"playerCount": 2156
}
]
}
Error Codes & Response Status
HTTP Status Codes
Request successful
Invalid parameters or malformed request
Player, mode, or endpoint not found
Rate limit exceeded (see Rate Limiting below)
Internal server error
Rate Limiting
Standard Tier: 100 requests per minute
Headers: Include X-RateLimit-Remaining and X-RateLimit-Reset
Caching: Responses are cached for 5 minutes. Use the ETag header to optimize requests.
Contact us on Discord for higher rate limits for production applications.
Quick Reference
| Endpoint | Method | Description |
|---|---|---|
| /api/v1/players/{username} | GET | Get player details and all rankings |
| /api/v1/players/search | GET | Search players by username |
| /api/v1/rankings/{mode} | GET | Get rankings leaderboard for game mode |
| /api/v1/rankings/{mode}/player/{username} | GET | Get player's rank in specific mode |
| /api/v1/modes | GET | List all available game modes |
| /api/v1/modes/{mode} | GET | Get game mode details and stats |
| /api/v1/regions | GET | List available regions |
Need Help?
This endpoint reference covers the core MCTIERS API. For code examples, integration guides, and troubleshooting, visit the Getting Started section or join our Discord community for developer support.
Back to Getting StartedCode Examples & Use Cases
Start building with MCTIERS API today. We've compiled ready-to-use code examples and sample projects to accelerate your integration. Whether you're building a Discord bot, web dashboard, or streaming overlay, you'll find everything you need to get started in minutes.
JavaScript / Node.js
Fetch a player's rank and display their tier across all game modes. Perfect for web dashboards and integrations.
// Fetch a player's rank
const fetchPlayerRank = async (username) => {
const response = await fetch(
`https://api.mctiers.com/player/${username}`
);
const data = await response.json();
console.log(`${username}'s Rankings:`);
console.log(`Overall: ${data.overall.tier}`);
console.log(`UHC: ${data.uhc.tier}`);
console.log(`Sword: ${data.sword.tier}`);
return data;
};
// Usage
fetchPlayerRank('PlayerName')
.then(rank => console.log(rank))
.catch(err => console.error(err));Use this pattern to build leaderboard widgets, player stat pages, or real-time rank trackers for your website or app.
Python
Query rankings by game mode and build competitive intelligence tools with Python. Ideal for data analysis and automation.
import requests
import json
def get_rankings(game_mode='overall', limit=50):
"""Fetch top players for a specific game mode"""
url = f"https://api.mctiers.com/rankings/{game_mode}"
params = {'limit': limit}
response = requests.get(url, params=params)
data = response.json()
for player in data['players']:
print(f"{player['rank']}. {player['username']} "
f"- Tier: {player['tier']}")
return data
# Get top 50 UHC players
get_rankings('uhc', 50)
# Get top 25 Sword players
get_rankings('sword', 25)Perfect for building ranking reports, competitive analysis dashboards, or automating clan management workflows.
Discord Bot Integration
Build a Discord bot that lets players check their rank instantly. Engage your community with real-time ranking lookups.
// Discord.js bot example
const { Client, EmbedBuilder } = require('discord.js');
const fetch = require('node-fetch');
client.on('messageCreate', async (message) => {
if (message.content.startsWith('!rank')) {
const username = message.content.split(' ')[1];
try {
const res = await fetch(
`https://api.mctiers.com/player/${username}`
);
const data = await res.json();
const embed = new EmbedBuilder()
.setTitle(`${username}'s Ranks`)
.addFields(
{ name: 'Overall', value: data.overall.tier },
{ name: 'UHC', value: data.uhc.tier },
{ name: 'Sword', value: data.sword.tier }
)
.setColor('#00D4FF');
message.reply({ embeds: [embed] });
} catch (error) {
message.reply('Player not found');
}
}
});Check out our full Discord bot example on GitHub for setup instructions and deployment guides.
Web Dashboard Example
Display clan member rankings and competitive stats in a custom web dashboard. Filter by game mode and track progress over time.
// HTML + Fetch API example
<div id="leaderboard"></div>
<script>
async function loadClanRankings(clanMembers) {
const container = document.getElementById('leaderboard');
for (const member of clanMembers) {
const res = await fetch(
`https://api.mctiers.com/player/${member}`
);
const data = await res.json();
const row = document.createElement('div');
row.innerHTML = `
<div class="flex justify-between p-4">
<span>${member}</span>
<span>${data.overall.tier}</span>
</div>
`;
container.appendChild(row);
}
}
// Usage
loadClanRankings(['Player1', 'Player2', 'Player3']);
</script>Build custom leaderboards, clan dashboards, or tournament tracking tools with minimal setup.
Streaming Overlay Integration
Display live player rankings in your Twitch or YouTube stream. Keep your audience updated with real-time tier data.
// OBS Browser Source HTML
<html>
<head>
<style>
body {
background: transparent;
color: #00D4FF;
font-family: 'Arial', sans-serif;
margin: 0;
}
.rank-display {
padding: 20px;
font-size: 24px;
font-weight: bold;
}
</style>
</head>
<body>
<div class="rank-display" id="rank">Loading...</div>
<script>
const updateRank = async () => {
const res = await fetch(
'https://api.mctiers.com/player/StreamerName'
);
const data = await res.json();
document.getElementById('rank').innerText =
`Overall: ${data.overall.tier}`;
};
updateRank();
setInterval(updateRank, 30000); // Update every 30s
</script>
</body>
</html>Create a custom OBS browser source that fetches your rank in real-time. Perfect for competitive streams and tournaments.
GitHub Sample Projects
Clone ready-to-run sample projects for Discord bots, web dashboards, and streaming overlays. All code is open-source and documented.
API Documentation
Full API reference with endpoint specifications, parameter details, and response schemas. Everything you need for successful integration.
Developer Discord
Join our developer community channel for support, questions, and discussions. Get help from the MCTIERS team and other developers.
API Status & Uptime
Monitor API health in real-time. Check endpoint status, rate limits, and planned maintenance schedules.
Need Help Getting Started?
Our developer community is active and responsive. Whether you're stuck on an integration or need guidance on best practices, we're here to help.
FAQ & Troubleshooting
Common questions, error codes, and solutions for typical integration issues.
Report Issues
Found a bug in the API? Report it on GitHub or Discord for quick resolution.
Feature Requests
Have an idea for a new endpoint or feature? We'd love to hear it from the community.