ugiDemo#0001
Tactician
- Level
- 214
- Title
- Tactician
- Card
- Example Card
Working examples for every endpoint in cURL, JavaScript, Python and PHP, with real paths, parameters and response fields. Replace the placeholder key with your own from the panel.
Pick a language once: every example on this page switches with it.
01
Every endpoint except /v1/status/{region} needs an API key. The examples below reuse the small ugi() helper defined here.
Authorization: Bearer <key>. X-API-Key works as well; ?api_key= leaks the key into logs.
api_key_missing; a wrong or disabled one returns 401 api_key_invalid.
Request header
api_key_missingapi_key_invalidThe key travels in the Authorization header; the outcome is one of three cases. · Sample view; names and numbers are fictional.
# Recommended: Authorization header
curl "https://api.ugilabs.com/v1/account/ugiDemo/0001" \
-H "Authorization: Bearer UGI-xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx"
# Also accepted
curl "https://api.ugilabs.com/v1/account/ugiDemo/0001" -H "X-API-Key: UGI-xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx"
# Works, but the key ends up in logs and browser history: avoid
curl "https://api.ugilabs.com/v1/account/ugiDemo/0001?api_key=UGI-xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx"02
A complete discord.js v14 bot with a /rank slash command that replies with an embed.
deferReply() so slow lookups do not hit Discord's 3-second limit.
ugiDemo#0001
Rank
Ascendant 1
RR
47
Wins / games
38 / 71
Data: ugiAPI • Today at 19:04
The embed the bot above sends for /rank: rank, RR, wins/games and the rank icon. · Sample view; names and numbers are fictional.
// Node 18+ · npm i discord.js dotenv · node bot.js
// .env next to bot.js: UGI_API_KEY=UGI-xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx DISCORD_TOKEN=your-bot-token (one per line)
require('dotenv').config(); // loads .env into process.env
const { Client, GatewayIntentBits, EmbedBuilder, SlashCommandBuilder, MessageFlags } = require('discord.js');
const API = 'https://api.ugilabs.com';
const REGIONS = ['eu', 'na', 'ap', 'kr', 'br', 'latam'];
const rankCommand = new SlashCommandBuilder()
.setName('rank')
.setDescription("Show a player's current competitive rank")
.addStringOption((o) => o.setName('riot_id').setDescription('Name#Tag').setRequired(true))
.addStringOption((o) => o.setName('region').setDescription('Region (default: eu)')
.addChoices(...REGIONS.map((r) => ({ name: r.toUpperCase(), value: r }))));
const client = new Client({ intents: [GatewayIntentBits.Guilds] });
client.once('ready', async () => {
await client.application.commands.set([rankCommand]); // global commands can take a while to appear
console.log(`Logged in as ${client.user.tag}`);
});
client.on('interactionCreate', async (interaction) => {
if (!interaction.isChatInputCommand() || interaction.commandName !== 'rank') return;
const riotId = interaction.options.getString('riot_id');
const region = interaction.options.getString('region') ?? 'eu';
const i = riotId.lastIndexOf('#');
if (i < 1) return interaction.reply({ content: 'Use the format Name#Tag', flags: MessageFlags.Ephemeral });
const name = riotId.slice(0, i).trim();
const tag = riotId.slice(i + 1).trim();
await interaction.deferReply();
const res = await fetch(`${API}/v1/rank/${region}/${encodeURIComponent(name)}/${encodeURIComponent(tag)}`, {
headers: { Authorization: `Bearer ${process.env.UGI_API_KEY}` },
});
const body = await res.json().catch(() => ({}));
if (res.status === 404) return interaction.editReply(`No player called **${name}#${tag}** in ${region.toUpperCase()}.`);
if (res.status === 429) return interaction.editReply(`Too many lookups, try again in ${res.headers.get('Retry-After') ?? 'a few'} seconds.`);
if (!res.ok) return interaction.editReply(`Lookup failed (${body.code ?? res.status}). Please try again later.`);
const { name: n, tag: t, current_data: rank } = body.data;
const embed = new EmbedBuilder()
.setTitle(`${n}#${t}`)
.setColor(0x10b981)
.addFields(
{ name: 'Rank', value: rank.currenttierpatched, inline: true },
{ name: 'RR', value: String(rank.ranking_in_tier ?? 0), inline: true },
{ name: 'Wins / games', value: `${rank.wins ?? 0} / ${rank.games ?? 0}`, inline: true },
)
.setFooter({ text: 'Data: ugiAPI' });
if (rank.tier_details?.icon) embed.setThumbnail(rank.tier_details.icon);
if (rank.as_of) embed.setTimestamp(new Date(rank.as_of));
return interaction.editReply({ embeds: [embed] });
});
client.login(process.env.DISCORD_TOKEN);The complete bot: save both files in an empty folder, run npm install, then npm start with UGI_API_KEY and DISCORD_TOKEN set. Add GUILD_ID to make /rank appear on that server instantly. 503 and per-minute 429 responses are retried once.
// bot.js: a complete discord.js v14 bot with a /rank slash command (Node.js 18+).
//
// Setup
// 1. Put this file, package.json and .env (the other tabs) in an empty folder.
// 2. https://discord.com/developers/applications -> New Application -> Bot -> Reset Token (copy it).
// Invite the bot with the "bot" and "applications.commands" scopes.
// 3. Fill in .env (your ugiAPI key + bot token; GUILD_ID is optional).
// 4. npm install (installs discord.js and dotenv)
// 5. npm start
// GUILD_ID registers /rank on that server instantly; global commands can take up to an hour to appear.
// Never commit .env to git (add it to .gitignore).
require('dotenv').config(); // loads .env into process.env
const { Client, GatewayIntentBits, EmbedBuilder, SlashCommandBuilder, MessageFlags } = require('discord.js');
for (const name of ['UGI_API_KEY', 'DISCORD_TOKEN']) {
if (!process.env[name]) {
console.error(`Missing ${name}. Add it to the .env file next to bot.js.`);
process.exit(1);
}
}
const API = 'https://api.ugilabs.com';
const REGIONS = ['eu', 'na', 'ap', 'kr', 'br', 'latam'];
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
const rankCommand = new SlashCommandBuilder()
.setName('rank')
.setDescription("Show a player's current competitive rank")
.addStringOption((o) => o.setName('riot_id').setDescription('Name#Tag').setRequired(true))
.addStringOption((o) => o.setName('region').setDescription('Region (default: eu)')
.addChoices(...REGIONS.map((r) => ({ name: r.toUpperCase(), value: r }))));
// GET an ugiAPI endpoint. A 503 or a per-minute 429 is retried once after Retry-After
// (deferReply gives us 15 minutes, so a short wait is fine). Returns { status, body, retryAfter }.
async function ugi(path) {
for (let attempt = 0; ; attempt++) {
const res = await fetch(`${API}${path}`, {
headers: { Authorization: `Bearer ${process.env.UGI_API_KEY}` },
signal: AbortSignal.timeout(15000),
});
const body = await res.json().catch(() => ({}));
const retryAfter = Number(res.headers.get('Retry-After') ?? 5);
const temporary = res.status === 503 || (res.status === 429 && body.code === 'rate_limited');
if (temporary && attempt === 0 && retryAfter <= 30) {
await sleep(retryAfter * 1000);
continue;
}
return { status: res.status, body, retryAfter };
}
}
const client = new Client({ intents: [GatewayIntentBits.Guilds] });
client.once('ready', async () => {
if (process.env.GUILD_ID) {
await client.application.commands.set([rankCommand], process.env.GUILD_ID);
} else {
await client.application.commands.set([rankCommand]);
}
console.log(`Logged in as ${client.user.tag}`);
});
client.on('interactionCreate', async (interaction) => {
if (!interaction.isChatInputCommand() || interaction.commandName !== 'rank') return;
const riotId = interaction.options.getString('riot_id');
const region = interaction.options.getString('region') ?? 'eu';
const i = riotId.lastIndexOf('#');
if (i < 1) return interaction.reply({ content: 'Use the format Name#Tag', flags: MessageFlags.Ephemeral });
const name = riotId.slice(0, i).trim();
const tag = riotId.slice(i + 1).trim();
await interaction.deferReply();
try {
const { status, body, retryAfter } = await ugi(`/v1/rank/${region}/${encodeURIComponent(name)}/${encodeURIComponent(tag)}`);
if (status === 404) return interaction.editReply(`No player called **${name}#${tag}** in ${region.toUpperCase()}.`);
if (status === 429) return interaction.editReply(`Too many lookups, try again in ${retryAfter} seconds.`);
if (status === 503) return interaction.editReply('Rank data is temporarily unavailable, please try again shortly.');
if (status !== 200) return interaction.editReply(`Lookup failed (${body.code ?? status}). Please try again later.`);
const { name: n, tag: t, current_data: rank } = body.data;
const embed = new EmbedBuilder()
.setTitle(`${n}#${t}`)
.setColor(0x10b981)
.addFields(
{ name: 'Rank', value: rank.currenttierpatched, inline: true },
{ name: 'RR', value: String(rank.ranking_in_tier ?? 0), inline: true },
{ name: 'Wins / games', value: `${rank.wins ?? 0} / ${rank.games ?? 0}`, inline: true },
)
.setFooter({ text: 'Data: ugiAPI' });
if (rank.tier_details?.icon) embed.setThumbnail(rank.tier_details.icon);
if (rank.as_of) embed.setTimestamp(new Date(rank.as_of));
return interaction.editReply({ embeds: [embed] });
} catch (err) {
console.error(err);
return interaction.editReply('Lookup failed (network error). Please try again later.');
}
});
client.login(process.env.DISCORD_TOKEN);03
Find a player by Riot ID or PUUID. Names can contain spaces and non-Latin characters, so always URL-encode the name and tag.
?region= (default eu) selects the region; level, card and title come from the player's latest match there.
?enrich=false skips level, card and title and returns only puuid, name and tag; it is faster.
?lang=tr returns card and title names in Turkish.
ugiDemo#0001
Tactician
A profile card built from the card_details, title_details and account_level fields of /v1/account. · Sample view; names and numbers are fictional.
# Riot ID "Sova Main#TR1": URL-encode the name (space -> %20)
curl "https://api.ugilabs.com/v1/account/Sova%20Main/TR1?region=eu" \
-H "Authorization: Bearer UGI-xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx"
# By PUUID, skipping level / card / title enrichment
curl "https://api.ugilabs.com/v1/by-puuid/account/6f1d2c3b-8a4e-4f60-9b7c-1d2e3f4a5b6c?enrich=false" \
-H "Authorization: Bearer UGI-xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx"{
"status": 200,
"data": {
"puuid": "6f1d2c3b-8a4e-4f60-9b7c-1d2e3f4a5b6c",
"name": "Sova Main",
"tag": "TR1",
"account_level": 214,
"card": "3e1f4b2a-9c8d-4e7f-a6b5-c4d3e2f1a0b9",
"title": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"card_details": {
"id": "3e1f4b2a-9c8d-4e7f-a6b5-c4d3e2f1a0b9",
"name": "Example Card",
"small": "https://media.valorant-api.com/playercards/3e1f4b2a-…/smallart.png",
"large": "https://media.valorant-api.com/playercards/3e1f4b2a-…/largeart.png",
"wide": "https://media.valorant-api.com/playercards/3e1f4b2a-…/wideart.png",
"icon": "https://media.valorant-api.com/playercards/3e1f4b2a-…/displayicon.png"
},
"title_details": {
"id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"name": "Tactician Title",
"text": "Tactician"
}
}
}A single file that runs as is. Set the UGI_API_KEY environment variable, then php -S localhost:8000 for PHP or node server.js for Node.js. The request is made on the server, so your key never reaches the browser. On 429 and 503 it waits for Retry-After and retries; other errors show the code and error fields.
<?php
/**
* player-card.php: a Valorant player card from ugiAPI. Single file, PHP 8.0+ with the curl extension.
*
* Run: UGI_API_KEY=your-key php -S localhost:8000
* Open: http://localhost:8000/player-card.php?name=ugiDemo&tag=0001
*
* The API is called here, on the server, so the key never reaches the browser.
*/
const UGI_BASE = 'https://api.ugilabs.com';
define('UGI_KEY', getenv('UGI_API_KEY') ?: 'UGI-xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx'); // or paste your key here
function e($v): string
{
return htmlspecialchars((string)$v, ENT_QUOTES, 'UTF-8');
}
function initials(string $s): string
{
return strtoupper(preg_match('/^.{1,2}/u', $s, $m) ? $m[0] : '?');
}
// GET an ugiAPI endpoint and return its `data`. A 429 from the per-minute window or a 503 is
// retried after Retry-After; anything else becomes an exception carrying the API's `code` and `error`.
function ugi(string $path, array $params = [], int $retries = 2): array
{
$url = UGI_BASE . $path . ($params ? '?' . http_build_query($params) : '');
for ($attempt = 0; ; $attempt++) {
$retryAfter = 5;
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 15,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . UGI_KEY, 'Accept: application/json'],
CURLOPT_HEADERFUNCTION => function ($ch, string $line) use (&$retryAfter): int {
if (stripos($line, 'Retry-After:') === 0) $retryAfter = (int)trim(substr($line, 12));
return strlen($line);
},
]);
$raw = curl_exec($ch);
$status = (int)curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$netError = curl_error($ch);
$body = is_string($raw) ? json_decode($raw, true) : null;
if ($status === 200 && isset($body['data'])) {
return $body['data']; // every success is ['status' => 200, 'data' => [...]]
}
$temporary = $status === 503 || ($status === 429 && ($body['code'] ?? '') === 'rate_limited');
if ($temporary && $attempt < $retries && $retryAfter <= 10) { // long waits (daily quota) are not retried
sleep(max(1, $retryAfter));
continue;
}
if ($status === 0) {
throw new RuntimeException('Network error: ' . $netError);
}
$message = sprintf('%d %s: %s', $status, $body['code'] ?? 'error', $body['error'] ?? 'Request failed');
if ($temporary) $message .= " (try again in {$retryAfter}s)";
throw new RuntimeException($message);
}
}
$name = trim((string)($_GET['name'] ?? 'ugiDemo'));
$tag = trim((string)($_GET['tag'] ?? '0001'));
$account = null;
$error = null;
try {
$account = ugi('/v1/account/' . rawurlencode($name) . '/' . rawurlencode($tag));
} catch (RuntimeException $ex) {
$error = $ex->getMessage();
}
// card_details / title_details are null with enrich=false or when no recent match is found
$card = $account['card_details'] ?? null;
$titleText = $account['title_details']['text'] ?? null;
$level = $account['account_level'] ?? null;
?>
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Player card</title>
<style>
* { box-sizing: border-box; }
body { margin: 0; min-height: 100vh; display: grid; place-items: center; padding: 24px; background: #09090b; color: #e4e4e7; font: 14px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif; }
img { display: block; }
.muted { color: #71717a; }
.up { color: #34d399; }
.down { color: #f87171; }
.error { max-width: 480px; margin: 0; padding: 12px 16px; border: 1px solid rgba(239, 68, 68, .3); border-radius: 8px; background: rgba(239, 68, 68, .06); color: #fca5a5; }
.card { width: min(440px, 100%); overflow: hidden; border: 1px solid #27272a; border-radius: 12px; background: #121826; }
.banner { position: relative; height: 112px; background: linear-gradient(135deg, #065f46, #18181b 60%, #09090b); }
.banner img { width: 100%; height: 100%; object-fit: cover; }
.level { position: absolute; top: 12px; right: 12px; padding: 2px 8px; border-radius: 6px; background: rgba(0, 0, 0, .65); font: 600 11px ui-monospace, monospace; color: #fafafa; }
.head { position: relative; display: flex; align-items: flex-end; gap: 16px; margin-top: -32px; padding: 0 20px 20px; }
.avatar { width: 64px; height: 64px; flex: none; display: grid; place-items: center; overflow: hidden; border: 2px solid #121826; border-radius: 10px; background: #27272a; font-size: 18px; font-weight: 700; color: #6ee7b7; }
.avatar img { width: 100%; height: 100%; object-fit: cover; }
.who { min-width: 0; }
.name { margin: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: 17px; font-weight: 600; color: #fafafa; }
.name span { font-weight: 400; color: #71717a; }
.title { margin: 0; font-size: 12px; color: #34d399; }
dl { display: grid; grid-template-columns: repeat(3, 1fr); margin: 0; border-top: 1px solid #27272a; text-align: center; }
dl div { min-width: 0; padding: 12px 8px; }
dl div + div { border-left: 1px solid #27272a; }
dt { font-size: 10.5px; letter-spacing: .06em; text-transform: uppercase; color: #71717a; }
dd { margin: 2px 0 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-weight: 600; color: #f4f4f5; }
</style>
</head>
<body>
<?php if ($error !== null): ?>
<p class="error"><?= e($error) ?></p>
<?php else: ?>
<article class="card">
<div class="banner">
<?php if (!empty($card['wide'])): ?><img src="<?= e($card['wide']) ?>" alt=""><?php endif; ?>
<?php if ($level !== null): ?><span class="level">Lv <?= e($level) ?></span><?php endif; ?>
</div>
<div class="head">
<div class="avatar">
<?php if (!empty($card['small'])): ?><img src="<?= e($card['small']) ?>" alt=""><?php else: ?><?= e(initials($account['name'])) ?><?php endif; ?>
</div>
<div class="who">
<p class="name"><?= e($account['name']) ?><span>#<?= e($account['tag']) ?></span></p>
<p class="title"><?= e($titleText ?? 'No title') ?></p>
</div>
</div>
<dl>
<div><dt>Level</dt><dd><?= e($level ?? '-') ?></dd></div>
<div><dt>Title</dt><dd><?= e($titleText ?? '-') ?></dd></div>
<div><dt>Card</dt><dd><?= e($card['name'] ?? '-') ?></dd></div>
</dl>
</article>
<?php endif; ?>
</body>
</html>04
current_data holds the tier (0 = Unranked, 27 = Radiant), the RR within the tier and the wins and games of the current act. as_of is the time of the last competitive game.
?size= from 1 to 10 (default 5).
ranked_rating_earned is the RR change of that game; won can be null when the result is unknown. tier_before, ranked_rating_before_update, refunded_rr and was_derank_protected explain promotions, demotions and refunds.
/v1/by-puuid/rank/… and /v1/by-puuid/rank-history/….
Current rank
Ascendant 1
ugiDemo#0001
Current rank and RR come from /v1/rank; the RR change over the last games comes from /v1/rank-history. · Sample view; names and numbers are fictional.
# Current rank
curl "https://api.ugilabs.com/v1/rank/eu/ugiDemo/0001" -H "Authorization: Bearer UGI-xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx"
# Last 10 competitive games (size 1-10, default 5), by PUUID
curl "https://api.ugilabs.com/v1/by-puuid/rank-history/eu/6f1d2c3b-8a4e-4f60-9b7c-1d2e3f4a5b6c?size=10" \
-H "Authorization: Bearer UGI-xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx"{
"status": 200,
"data": {
"name": "ugiDemo",
"tag": "0001",
"puuid": "6f1d2c3b-8a4e-4f60-9b7c-1d2e3f4a5b6c",
"account_level": 214,
"current_data": {
"currenttier": 21,
"currenttierpatched": "Ascendant 1",
"tier_details": {
"name": "ASCENDANT 1",
"icon": "https://media.valorant-api.com/competitivetiers/…/21/largeicon.png"
},
"ranking_in_tier": 47,
"wins": 38,
"games": 71,
"source_match_id": "b2c4e6a8-1d3f-4a5b-9c7e-0f2a4c6e8b1d",
"as_of": "2026-11-16T19:04:37Z"
},
"by_season": [
{
"season_id": "4c4b8cff-43eb-13d3-8f14-96b783c90cd2",
"act": { "name": "ACT III", "episode": "EPISODE 9", "start": "2024-10-22T00:00:00Z", "end": "2025-01-08T00:00:00Z" },
"final_tier": 18,
"final_tier_patched": "Diamond 1",
"final_rr": 47,
"wins": 38,
"games": 71,
"leaderboard_rank": null,
"peak_win_tier": 18,
"wins_by_tier": { "16": 7, "17": 14, "18": 17 }
}
]
}
}A single file that runs as is. Set the UGI_API_KEY environment variable, then php -S localhost:8000 for PHP or node server.js for Node.js. The request is made on the server, so your key never reaches the browser. On 429 and 503 it waits for Retry-After and retries; other errors show the code and error fields.
<?php
/**
* rank-card.php: current rank, RR progress and the last 5 RR changes. Single file, PHP 8.0+ with curl.
*
* Run: UGI_API_KEY=your-key php -S localhost:8000
* Open: http://localhost:8000/rank-card.php?region=eu&name=ugiDemo&tag=0001
*
* Two requests per page view (/v1/rank + /v1/rank-history). The key stays on the server.
*/
const UGI_BASE = 'https://api.ugilabs.com';
define('UGI_KEY', getenv('UGI_API_KEY') ?: 'UGI-xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx'); // or paste your key here
const REGIONS = ['eu', 'na', 'ap', 'kr', 'br', 'latam'];
function e($v): string
{
return htmlspecialchars((string)$v, ENT_QUOTES, 'UTF-8');
}
function initials(string $s): string
{
return strtoupper(preg_match('/^.{1,2}/u', $s, $m) ? $m[0] : '?');
}
// GET an ugiAPI endpoint and return its `data`. A 429 from the per-minute window or a 503 is
// retried after Retry-After; anything else becomes an exception carrying the API's `code` and `error`.
function ugi(string $path, array $params = [], int $retries = 2): array
{
$url = UGI_BASE . $path . ($params ? '?' . http_build_query($params) : '');
for ($attempt = 0; ; $attempt++) {
$retryAfter = 5;
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 15,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . UGI_KEY, 'Accept: application/json'],
CURLOPT_HEADERFUNCTION => function ($ch, string $line) use (&$retryAfter): int {
if (stripos($line, 'Retry-After:') === 0) $retryAfter = (int)trim(substr($line, 12));
return strlen($line);
},
]);
$raw = curl_exec($ch);
$status = (int)curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$netError = curl_error($ch);
$body = is_string($raw) ? json_decode($raw, true) : null;
if ($status === 200 && isset($body['data'])) {
return $body['data']; // every success is ['status' => 200, 'data' => [...]]
}
$temporary = $status === 503 || ($status === 429 && ($body['code'] ?? '') === 'rate_limited');
if ($temporary && $attempt < $retries && $retryAfter <= 10) { // long waits (daily quota) are not retried
sleep(max(1, $retryAfter));
continue;
}
if ($status === 0) {
throw new RuntimeException('Network error: ' . $netError);
}
$message = sprintf('%d %s: %s', $status, $body['code'] ?? 'error', $body['error'] ?? 'Request failed');
if ($temporary) $message .= " (try again in {$retryAfter}s)";
throw new RuntimeException($message);
}
}
$region = in_array($_GET['region'] ?? null, REGIONS, true) ? $_GET['region'] : 'eu';
$name = trim((string)($_GET['name'] ?? 'ugiDemo'));
$tag = trim((string)($_GET['tag'] ?? '0001'));
$player = rawurlencode($name) . '/' . rawurlencode($tag);
$error = null;
try {
$rank = ugi("/v1/rank/$region/$player");
$history = ugi("/v1/rank-history/$region/$player", ['size' => 5])['history'];
} catch (RuntimeException $ex) {
$error = $ex->getMessage();
}
$signed = fn(int $n): string => ($n > 0 ? '+' : '') . $n;
if ($error === null) {
$cur = $rank['current_data'];
$tier = $cur['currenttierpatched'] ?? 'Unranked';
$tierIcon = $cur['tier_details']['icon'] ?? null;
$rr = (int)($cur['ranking_in_tier'] ?? 0);
$capped = (int)($cur['currenttier'] ?? 0) < 24; // Immortal (24+) and Radiant have no 100 RR cap
$wins = (int)($cur['wins'] ?? 0);
$games = (int)($cur['games'] ?? 0);
$winRate = $games > 0 ? round($wins / $games * 100) : 0;
$net = array_sum(array_map(fn($m) => (int)($m['ranked_rating_earned'] ?? 0), $history));
}
?>
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Rank card</title>
<style>
* { box-sizing: border-box; }
body { margin: 0; min-height: 100vh; display: grid; place-items: center; padding: 24px; background: #09090b; color: #e4e4e7; font: 14px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif; }
img { display: block; }
.muted { color: #71717a; }
.up { color: #34d399; }
.down { color: #f87171; }
.error { max-width: 480px; margin: 0; padding: 12px 16px; border: 1px solid rgba(239, 68, 68, .3); border-radius: 8px; background: rgba(239, 68, 68, .06); color: #fca5a5; }
.card { width: min(420px, 100%); overflow: hidden; border: 1px solid #27272a; border-radius: 12px; background: #121826; }
.top { display: flex; align-items: center; gap: 16px; padding: 20px; }
.tier { width: 64px; height: 64px; flex: none; display: grid; place-items: center; overflow: hidden; border-radius: 12px; background: radial-gradient(circle at 30% 30%, #34d399, #065f46 70%); font-size: 18px; font-weight: 800; color: #ecfdf5; }
.tier.has-img { background: none; }
.tier img { width: 100%; height: 100%; object-fit: contain; }
.label { margin: 0; font-size: 10.5px; letter-spacing: .06em; text-transform: uppercase; color: #71717a; }
h1 { margin: 2px 0; font-size: 20px; line-height: 1.2; color: #fafafa; }
.who p { margin: 0; }
.rr { padding: 0 20px 16px; }
.row { display: flex; align-items: baseline; justify-content: space-between; gap: 12px; font-size: 12px; }
.bar { height: 6px; margin-top: 6px; overflow: hidden; border-radius: 999px; background: #27272a; }
.bar span { display: block; height: 100%; border-radius: inherit; background: #10b981; }
dl { display: grid; grid-template-columns: repeat(3, 1fr); margin: 0; border-block: 1px solid #27272a; text-align: center; }
dl div { padding: 12px 8px; }
dl div + div { border-left: 1px solid #27272a; }
dt { font-size: 10.5px; letter-spacing: .06em; text-transform: uppercase; color: #71717a; }
dd { margin: 2px 0 0; font-weight: 600; color: #f4f4f5; }
.history { padding: 16px 20px 20px; }
ul { margin: 10px 0 0; padding: 0; list-style: none; }
li { display: grid; grid-template-columns: 22px 1fr auto 48px; align-items: center; gap: 10px; padding: 6px 0; font-size: 13px; }
li + li { border-top: 1px solid #18181b; }
li.empty { display: block; }
li b { text-align: right; font-family: ui-monospace, monospace; }
.res { display: grid; place-items: center; width: 22px; height: 22px; border-radius: 6px; background: #27272a; font-size: 11px; font-weight: 700; color: #a1a1aa; }
.res.w { background: rgba(16, 185, 129, .15); color: #34d399; }
.res.l { background: rgba(239, 68, 68, .12); color: #f87171; }
</style>
</head>
<body>
<?php if ($error !== null): ?>
<p class="error"><?= e($error) ?></p>
<?php else: ?>
<article class="card">
<header class="top">
<div class="tier<?= $tierIcon ? ' has-img' : '' ?>">
<?php if ($tierIcon): ?><img src="<?= e($tierIcon) ?>" alt=""><?php else: ?><?= e(preg_replace('/^(\S)\S*\s*(\d*)$/', '$1$2', $tier)) ?><?php endif; ?>
</div>
<div class="who">
<p class="label">Current rank</p>
<h1><?= e($tier) ?></h1>
<p class="muted"><?= e($rank['name']) ?>#<?= e($rank['tag']) ?></p>
</div>
</header>
<div class="rr">
<div class="row"><span class="muted">Rank rating</span><b><?= $rr ?><?= $capped ? ' / 100' : '' ?> RR</b></div>
<div class="bar"><span style="width: <?= min(100, max(0, $rr)) ?>%"></span></div>
</div>
<dl>
<div><dt>Wins</dt><dd><?= $wins ?></dd></div>
<div><dt>Games</dt><dd><?= $games ?></dd></div>
<div><dt>Win rate</dt><dd><?= $winRate ?>%</dd></div>
</dl>
<section class="history">
<div class="row">
<span class="label">Last <?= count($history) ?> games</span>
<b class="<?= $net >= 0 ? 'up' : 'down' ?>"><?= $signed($net) ?> RR</b>
</div>
<ul>
<?php foreach ($history as $m): ?>
<?php $won = $m['won'] ?? null; $earned = (int)($m['ranked_rating_earned'] ?? 0); ?>
<li>
<span class="res <?= $won === null ? '' : ($won ? 'w' : 'l') ?>"><?= $won === null ? '-' : ($won ? 'W' : 'L') ?></span>
<span><?= e($m['map_details']['name'] ?? basename((string)$m['map'])) ?></span>
<span class="muted"><?= e($m['tier']) ?></span>
<b class="<?= $earned >= 0 ? 'up' : 'down' ?>"><?= $signed($earned) ?></b>
</li>
<?php endforeach; ?>
<?php if (!$history): ?><li class="empty muted">No competitive games yet</li><?php endif; ?>
</ul>
</section>
</article>
<?php endif; ?>
</body>
</html>05
Match history returns one summary per match from the requested player's point of view; match details return every player, team and round.
?size= is capped by your plan: 5 (Basic), 10 (Advanced), 20 (Premium). ?mode= is applied before size; ?start= with pagination.next_start pages back.
teams is an object keyed by team id (Blue, Red); in match details it is a list with team_id.
?region= on /v1/match/{matchId} is optional; without it every region is tried.
/v1/stored-matches reads only from our match store (no Riot query cost) and adds a summary. The store fills up as matches are fetched, so it can have gaps.
Recent matches
ugiDemo#0001Map, agent, K/D/A, ACS, score and result from /v1/matches; the score is read from the teams field. · Sample view; names and numbers are fictional.
# Recent matches (size is capped by your plan: 5 / 10 / 20)
curl "https://api.ugilabs.com/v1/matches/eu/ugiDemo/0001?size=5" -H "Authorization: Bearer UGI-xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx"
# Only competitive, next page: pass pagination.next_start from the previous response
curl "https://api.ugilabs.com/v1/matches/eu/ugiDemo/0001?size=5&mode=competitive&start=5" -H "Authorization: Bearer UGI-xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx"
# Stored matches with a summary (no Riot query cost): competitive on Ascent, page 1
curl "https://api.ugilabs.com/v1/stored-matches/eu/ugiDemo/0001?mode=competitive&map=Ascent&size=20&page=1" \
-H "Authorization: Bearer UGI-xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx"
# Full match: all players, teams and rounds. region is an optional hint.
curl "https://api.ugilabs.com/v1/match/b2c4e6a8-1d3f-4a5b-9c7e-0f2a4c6e8b1d?region=eu" \
-H "Authorization: Bearer UGI-xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx"{
"status": 200,
"data": {
"name": "ugiDemo",
"tag": "0001",
"puuid": "6f1d2c3b-8a4e-4f60-9b7c-1d2e3f4a5b6c",
"mode": "competitive",
"total_matches": 5,
"pagination": { "start": 0, "size": 5, "returned": 5, "total": 69, "next_start": 5 },
"matches": [
{
"match_id": "b2c4e6a8-1d3f-4a5b-9c7e-0f2a4c6e8b1d",
"map": "/Game/Maps/Ascent/Ascent",
"map_details": { "name": "Ascent", "splash": "https://media.valorant-api.com/maps/…/splash.png", "icon": "https://media.valorant-api.com/maps/…/displayicon.png" },
"game_mode": "competitive",
"game_start": "2026-11-16T19:04:37Z",
"game_length_ms": 2318000,
"player": {
"puuid": "6f1d2c3b-8a4e-4f60-9b7c-1d2e3f4a5b6c",
"team": "Blue",
"character": "add6443a-41bd-e414-f6ad-e58d267f4e95",
"character_details": { "name": "Jett", "portrait": "https://media.valorant-api.com/agents/…/fullportrait.png", "icon": "https://media.valorant-api.com/agents/…/displayicon.png" },
"competitive_tier": 21,
"tier_details": { "name": "ASCENDANT 1", "icon": "https://media.valorant-api.com/competitivetiers/…/21/largeicon.png" },
"stats": { "score": 5412, "kills": 22, "deaths": 15, "assists": 4, "rounds_played": 22 },
"combat": {
"shots": { "head": 24, "body": 51, "leg": 4 },
"headshot_pct": 30.4,
"damage": { "made": 3190, "received": 2410 },
"adr": 145,
"first_kills": 5,
"first_deaths": 3,
"economy": { "spent_total": 68400, "spent_avg": 3109, "loadout_value_avg": 3980 }
}
},
"teams": {
"Blue": { "won": true, "rounds_won": 13, "rounds_played": 22 },
"Red": { "won": false, "rounds_won": 9, "rounds_played": 22 }
}
}
]
}
}A single file that runs as is. Set the UGI_API_KEY environment variable, then php -S localhost:8000 for PHP or node server.js for Node.js. The request is made on the server, so your key never reaches the browser. On 429 and 503 it waits for Retry-After and retries; other errors show the code and error fields.
<?php
/**
* recent-matches.php: the last 5 matches of a player with map, agent, K/D/A, ACS and result.
* Single file, PHP 8.0+ with curl.
*
* Run: UGI_API_KEY=your-key php -S localhost:8000
* Open: http://localhost:8000/recent-matches.php?region=eu&name=ugiDemo&tag=0001
*/
const UGI_BASE = 'https://api.ugilabs.com';
define('UGI_KEY', getenv('UGI_API_KEY') ?: 'UGI-xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx'); // or paste your key here
const REGIONS = ['eu', 'na', 'ap', 'kr', 'br', 'latam'];
function e($v): string
{
return htmlspecialchars((string)$v, ENT_QUOTES, 'UTF-8');
}
function initials(string $s): string
{
return strtoupper(preg_match('/^.{1,2}/u', $s, $m) ? $m[0] : '?');
}
// GET an ugiAPI endpoint and return its `data`. A 429 from the per-minute window or a 503 is
// retried after Retry-After; anything else becomes an exception carrying the API's `code` and `error`.
function ugi(string $path, array $params = [], int $retries = 2): array
{
$url = UGI_BASE . $path . ($params ? '?' . http_build_query($params) : '');
for ($attempt = 0; ; $attempt++) {
$retryAfter = 5;
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 15,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . UGI_KEY, 'Accept: application/json'],
CURLOPT_HEADERFUNCTION => function ($ch, string $line) use (&$retryAfter): int {
if (stripos($line, 'Retry-After:') === 0) $retryAfter = (int)trim(substr($line, 12));
return strlen($line);
},
]);
$raw = curl_exec($ch);
$status = (int)curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$netError = curl_error($ch);
$body = is_string($raw) ? json_decode($raw, true) : null;
if ($status === 200 && isset($body['data'])) {
return $body['data']; // every success is ['status' => 200, 'data' => [...]]
}
$temporary = $status === 503 || ($status === 429 && ($body['code'] ?? '') === 'rate_limited');
if ($temporary && $attempt < $retries && $retryAfter <= 10) { // long waits (daily quota) are not retried
sleep(max(1, $retryAfter));
continue;
}
if ($status === 0) {
throw new RuntimeException('Network error: ' . $netError);
}
$message = sprintf('%d %s: %s', $status, $body['code'] ?? 'error', $body['error'] ?? 'Request failed');
if ($temporary) $message .= " (try again in {$retryAfter}s)";
throw new RuntimeException($message);
}
}
$region = in_array($_GET['region'] ?? null, REGIONS, true) ? $_GET['region'] : 'eu';
$name = trim((string)($_GET['name'] ?? 'ugiDemo'));
$tag = trim((string)($_GET['tag'] ?? '0001'));
$error = null;
$rows = [];
try {
// size is capped by your plan (5 / 10 / 20)
$data = ugi("/v1/matches/$region/" . rawurlencode($name) . '/' . rawurlencode($tag), ['size' => 5]);
foreach ($data['matches'] as $m) {
$p = $m['player'] ?? null;
if (!$p) continue;
$s = $p['stats'];
$mine = $m['teams'][$p['team']] ?? []; // teams is keyed by team id ("Blue" / "Red")
$enemy = [];
foreach ($m['teams'] as $teamId => $team) {
if ($teamId !== $p['team']) { $enemy = $team; break; }
}
$rows[] = [
'map' => $m['map_details']['name'] ?? basename((string)$m['map']),
'splash' => $m['map_details']['splash'] ?? null,
'mode' => $m['game_mode'] ?? '',
'agent' => $p['character_details']['name'] ?? '?',
'icon' => $p['character_details']['icon'] ?? null,
'kda' => "{$s['kills']} / {$s['deaths']} / {$s['assists']}",
'acs' => (int)round($s['score'] / max(1, $s['rounds_played'])),
'won' => !empty($mine['won']),
'score' => ($mine['rounds_won'] ?? 0) . ' - ' . ($enemy['rounds_won'] ?? 0),
];
}
} catch (RuntimeException $ex) {
$error = $ex->getMessage();
}
?>
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Recent matches</title>
<style>
* { box-sizing: border-box; }
body { margin: 0; min-height: 100vh; display: grid; place-items: center; padding: 24px; background: #09090b; color: #e4e4e7; font: 14px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif; }
img { display: block; }
.muted { color: #71717a; }
.up { color: #34d399; }
.down { color: #f87171; }
.error { max-width: 480px; margin: 0; padding: 12px 16px; border: 1px solid rgba(239, 68, 68, .3); border-radius: 8px; background: rgba(239, 68, 68, .06); color: #fca5a5; }
.list { width: min(600px, 100%); overflow: hidden; border: 1px solid #27272a; border-radius: 12px; background: #121826; }
.list header { display: flex; align-items: baseline; justify-content: space-between; gap: 12px; padding: 14px 18px; border-bottom: 1px solid #27272a; }
h1 { margin: 0; font-size: 15px; color: #fafafa; }
ul { margin: 0; padding: 0; list-style: none; }
li { display: grid; grid-template-columns: 56px minmax(0, 1fr) minmax(0, 1fr) auto auto; align-items: center; gap: 14px; padding: 10px 18px 10px 14px; border-left: 3px solid #f87171; }
li.win { border-left-color: #10b981; }
li + li { border-top: 1px solid #18181b; }
li.empty { display: block; }
.thumb { width: 56px; height: 36px; overflow: hidden; border-radius: 6px; background: linear-gradient(135deg, #3f3f46, #18181b); }
.thumb img { width: 100%; height: 100%; object-fit: cover; }
.cell { min-width: 0; }
.cell b, .cell small { display: block; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
.cell b { font-size: 13px; color: #f4f4f5; }
.cell small { font-size: 11px; color: #71717a; }
.agent { display: flex; align-items: center; gap: 8px; min-width: 0; font-size: 13px; }
.ico { width: 26px; height: 26px; flex: none; display: grid; place-items: center; overflow: hidden; border-radius: 999px; background: #27272a; font-size: 10px; font-weight: 700; color: #a1a1aa; }
.ico img { width: 100%; height: 100%; }
.num { text-align: right; font-family: ui-monospace, monospace; }
.badge { display: inline-block; padding: 1px 8px; border-radius: 999px; background: rgba(239, 68, 68, .12); font-size: 11px; font-weight: 700; color: #f87171; }
.win .badge { background: rgba(16, 185, 129, .15); color: #34d399; }
@media (max-width: 520px) { li { grid-template-columns: minmax(0, 1fr) auto auto; } .thumb, .agent { display: none; } }
</style>
</head>
<body>
<?php if ($error !== null): ?>
<p class="error"><?= e($error) ?></p>
<?php else: ?>
<section class="list">
<header>
<h1>Recent matches</h1>
<span class="muted"><?= e($data['name']) ?>#<?= e($data['tag']) ?></span>
</header>
<ul>
<?php foreach ($rows as $r): ?>
<li class="<?= $r['won'] ? 'win' : 'loss' ?>">
<div class="thumb"><?php if ($r['splash']): ?><img src="<?= e($r['splash']) ?>" alt=""><?php endif; ?></div>
<div class="cell"><b><?= e($r['map']) ?></b><small><?= e($r['mode']) ?></small></div>
<div class="agent">
<span class="ico"><?php if ($r['icon']): ?><img src="<?= e($r['icon']) ?>" alt=""><?php else: ?><?= e(initials($r['agent'])) ?><?php endif; ?></span>
<span><?= e($r['agent']) ?></span>
</div>
<div class="cell num"><b><?= e($r['kda']) ?></b><small><?= $r['acs'] ?> ACS</small></div>
<div class="cell num"><span class="badge"><?= $r['won'] ? 'WIN' : 'LOSS' ?></span><small><?= e($r['score']) ?></small></div>
</li>
<?php endforeach; ?>
<?php if (!$rows): ?><li class="empty muted">No recent matches</li><?php endif; ?>
</ul>
</section>
<?php endif; ?>
</body>
</html>06
The ranked leaderboard of the active act. Pass actId (from /v1/content) for a past act.
size is 1–200 (default 50); start is an offset rounded down to a multiple of size, up to 10,000.
search filters the returned page by name; it does not search the whole leaderboard.
Secret Agent with an empty tag_line and puuid: null.
Leaderboard · EU
21,873 ranked players| # | Player | RR | Wins |
|---|---|---|---|
| 1 |
ugiDemo#0001
|
1043 | 187 |
| 2 |
Secret Agent
hidden
|
1012 | 164 |
| 3 |
NightOwl#EUW
|
998 | 201 |
| 4 |
Kestrel#7777
|
976 | 152 |
| 5 |
ugiTester#0002
|
961 | 173 |
| 6 |
Lumen#TR1
|
949 | 140 |
| 7 |
AimDuck#404
|
931 | 166 |
| 8 |
Polaris#EU5
|
918 | 149 |
| 9 |
VoidStep#0420
|
902 | 158 |
| 10 |
Mirage#9001
|
887 | 131 |
The top 10 players from /v1/leaderboard. Players who hide their profile come back as Secret Agent with an empty tag and puuid: null. · Sample view; names and numbers are fictional.
# Top 10 of the active act
curl "https://api.ugilabs.com/v1/leaderboard/eu?size=10" -H "Authorization: Bearer UGI-xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx"
# Page 3 with 50 players per page (start = 100), filtered by name
curl "https://api.ugilabs.com/v1/leaderboard/eu?size=50&start=100&search=demo" -H "Authorization: Bearer UGI-xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx"{
"status": 200,
"data": {
"act_id": "4c4b8cff-43eb-13d3-8f14-96b7c4d2a1f0",
"total_players": 21873,
"shard": "eu",
"players": [
{
"puuid": "6f1d2c3b-8a4e-4f60-9b7c-1d2e3f4a5b6c",
"game_name": "ugiDemo",
"tag_line": "0001",
"leaderboard_rank": 1,
"ranked_rating": 1043,
"number_of_wins": 187,
"competitive_tier": 27,
"tier_details": { "name": "RADIANT", "icon": "https://media.valorant-api.com/competitivetiers/…/27/largeicon.png" }
},
{
"puuid": null,
"game_name": "Secret Agent",
"tag_line": "",
"leaderboard_rank": 2,
"ranked_rating": 1012,
"number_of_wins": 164,
"competitive_tier": 27,
"tier_details": { "name": "RADIANT", "icon": "…" }
}
]
}
}A single file that runs as is. Set the UGI_API_KEY environment variable, then php -S localhost:8000 for PHP or node server.js for Node.js. The request is made on the server, so your key never reaches the browser. On 429 and 503 it waits for Retry-After and retries; other errors show the code and error fields.
<?php
/**
* leaderboard.php: top 10 of the active act, cached on disk for 10 minutes so page views don't spend your quota.
* Single file, PHP 8.0+ with curl.
*
* Run: UGI_API_KEY=your-key php -S localhost:8000
* Open: http://localhost:8000/leaderboard.php?region=eu
*/
const UGI_BASE = 'https://api.ugilabs.com';
define('UGI_KEY', getenv('UGI_API_KEY') ?: 'UGI-xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx'); // or paste your key here
const REGIONS = ['eu', 'na', 'ap', 'kr', 'br', 'latam'];
function e($v): string
{
return htmlspecialchars((string)$v, ENT_QUOTES, 'UTF-8');
}
function initials(string $s): string
{
return strtoupper(preg_match('/^.{1,2}/u', $s, $m) ? $m[0] : '?');
}
// GET an ugiAPI endpoint and return its `data`. A 429 from the per-minute window or a 503 is
// retried after Retry-After; anything else becomes an exception carrying the API's `code` and `error`.
function ugi(string $path, array $params = [], int $retries = 2): array
{
$url = UGI_BASE . $path . ($params ? '?' . http_build_query($params) : '');
for ($attempt = 0; ; $attempt++) {
$retryAfter = 5;
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 15,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . UGI_KEY, 'Accept: application/json'],
CURLOPT_HEADERFUNCTION => function ($ch, string $line) use (&$retryAfter): int {
if (stripos($line, 'Retry-After:') === 0) $retryAfter = (int)trim(substr($line, 12));
return strlen($line);
},
]);
$raw = curl_exec($ch);
$status = (int)curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$netError = curl_error($ch);
$body = is_string($raw) ? json_decode($raw, true) : null;
if ($status === 200 && isset($body['data'])) {
return $body['data']; // every success is ['status' => 200, 'data' => [...]]
}
$temporary = $status === 503 || ($status === 429 && ($body['code'] ?? '') === 'rate_limited');
if ($temporary && $attempt < $retries && $retryAfter <= 10) { // long waits (daily quota) are not retried
sleep(max(1, $retryAfter));
continue;
}
if ($status === 0) {
throw new RuntimeException('Network error: ' . $netError);
}
$message = sprintf('%d %s: %s', $status, $body['code'] ?? 'error', $body['error'] ?? 'Request failed');
if ($temporary) $message .= " (try again in {$retryAfter}s)";
throw new RuntimeException($message);
}
}
$region = in_array($_GET['region'] ?? null, REGIONS, true) ? $_GET['region'] : 'eu';
$cacheFile = sys_get_temp_dir() . "/ugi_leaderboard_{$region}.json";
$board = null;
$error = null;
if (is_file($cacheFile) && time() - filemtime($cacheFile) < 600) {
$board = json_decode((string)file_get_contents($cacheFile), true);
}
if (!$board) {
try {
$board = ugi("/v1/leaderboard/$region", ['size' => 10]);
file_put_contents($cacheFile, json_encode($board), LOCK_EX);
} catch (RuntimeException $ex) {
$error = $ex->getMessage();
}
}
?>
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Leaderboard</title>
<style>
* { box-sizing: border-box; }
body { margin: 0; min-height: 100vh; display: grid; place-items: center; padding: 24px; background: #09090b; color: #e4e4e7; font: 14px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif; }
img { display: block; }
.muted { color: #71717a; }
.up { color: #34d399; }
.down { color: #f87171; }
.error { max-width: 480px; margin: 0; padding: 12px 16px; border: 1px solid rgba(239, 68, 68, .3); border-radius: 8px; background: rgba(239, 68, 68, .06); color: #fca5a5; }
.board { width: min(560px, 100%); overflow: hidden; border: 1px solid #27272a; border-radius: 12px; background: #121826; }
.board header { display: flex; align-items: baseline; justify-content: space-between; gap: 12px; padding: 14px 18px; border-bottom: 1px solid #27272a; }
h1 { margin: 0; font-size: 15px; color: #fafafa; }
table { width: 100%; border-collapse: collapse; font-size: 13px; }
th { padding: 8px 18px; text-align: left; font-size: 10.5px; font-weight: 600; letter-spacing: .06em; text-transform: uppercase; color: #71717a; }
td { padding: 8px 18px; border-top: 1px solid #18181b; }
.num { text-align: right; font-family: ui-monospace, monospace; }
.pos { width: 40px; font-family: ui-monospace, monospace; color: #a1a1aa; }
tr.top3 .pos { color: #34d399; font-weight: 700; }
.player { display: flex; align-items: center; gap: 10px; min-width: 0; }
.tier { width: 24px; height: 24px; flex: none; border-radius: 6px; background: linear-gradient(135deg, #fde68a, #f59e0b); }
.tier.has-img { background: none; }
.tier img { width: 100%; height: 100%; object-fit: contain; }
.anon { font-style: italic; color: #a1a1aa; }
.tag { padding: 0 6px; border: 1px solid #3f3f46; border-radius: 999px; font-size: 10.5px; color: #a1a1aa; }
</style>
</head>
<body>
<?php if ($error !== null): ?>
<p class="error"><?= e($error) ?></p>
<?php else: ?>
<section class="board">
<header>
<h1>Leaderboard · <?= e(strtoupper($region)) ?></h1>
<span class="muted"><?= number_format((int)$board['total_players']) ?> ranked players</span>
</header>
<table>
<thead><tr><th>#</th><th>Player</th><th class="num">RR</th><th class="num">Wins</th></tr></thead>
<tbody>
<?php foreach ($board['players'] as $p): ?>
<?php
// Players with a hidden profile come back as "Secret Agent" with puuid null and an empty tag_line
$hidden = $p['puuid'] === null || $p['tag_line'] === '';
$icon = $p['tier_details']['icon'] ?? null;
?>
<tr class="<?= $p['leaderboard_rank'] <= 3 ? 'top3' : '' ?>">
<td class="pos"><?= (int)$p['leaderboard_rank'] ?></td>
<td>
<div class="player">
<span class="tier<?= $icon ? ' has-img' : '' ?>"><?php if ($icon): ?><img src="<?= e($icon) ?>" alt=""><?php endif; ?></span>
<?php if ($hidden): ?>
<span class="anon"><?= e($p['game_name'] ?: 'Secret Agent') ?></span><span class="tag">hidden</span>
<?php else: ?>
<span><?= e($p['game_name']) ?><span class="muted">#<?= e($p['tag_line']) ?></span></span>
<?php endif; ?>
</div>
</td>
<td class="num"><?= (int)$p['ranked_rating'] ?></td>
<td class="num"><?= (int)$p['number_of_wins'] ?></td>
</tr>
<?php endforeach; ?>
</tbody>
</table>
</section>
<?php endif; ?>
</body>
</html>07
Content lists agents, maps, weapon skins, game modes, seasons, player cards and titles. Use it to map ids to names and to find the active act.
locale accepts en-US and tr-TR; anything else returns 400 invalid_locale.
/v1/status/{region} needs no key and is limited to 60 requests per minute per IP. The status page has the full picture.
Game content
release-11.10Agents
Maps
/v1/content gives agents, maps and the active act; /v1/status gives region health. · Sample view; names and numbers are fictional.
# Game content in Turkish (locale: en-US or tr-TR)
curl "https://api.ugilabs.com/v1/content?locale=tr-TR" -H "Authorization: Bearer UGI-xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx"
# Public status: no key needed (limited to 60 requests/minute per IP)
curl "https://api.ugilabs.com/v1/status/eu"{
"status": 200,
"data": {
"version": "release-11.10-shipping-…",
"agents": [
{ "name": "Jett", "id": "add6443a-41bd-e414-f6ad-e58d267f4e95", "asset_name": "…" }
],
"maps": [
{ "name": "Ascent", "id": "7eaecc1b-4337-bbf6-6ab9-04b8f06b3319", "asset_name": "…", "asset_path": "/Game/Maps/Ascent/Ascent" }
],
"weapon_skins": [ { "name": "…", "id": "…", "asset_name": "…" } ],
"game_modes": [ { "name": "Standard", "id": "…", "asset_name": "…" } ],
"seasons": [
{ "name": "ACT III", "id": "4c4b8cff-43eb-13d3-8f14-96b7c4d2a1f0", "is_active": true, "type": "act" }
],
"player_cards": [ { "name": "…", "id": "…", "asset_name": "…" } ],
"player_titles": [ { "name": "…", "id": "…" } ]
}
}08
Errors always have the shape {status, error, code, request_id}, sometimes with details. Branch on code, not on the message text.
rate_limited (429) and 503, and wait Retry-After seconds first.
request_id (also in the X-Request-Id header) when you report a problem.
missing_parameters The path is incomplete. details.usage shows the correct form.
invalid_regioninvalid_name +7 Fix the parameter; retrying will not help.
api_key_missingapi_key_invalid Send a valid, active key.
ip_not_allowedorigin_not_allowed The request came from an IP or origin that is not on the key's allowlist.
player_not_foundnot_found +1 Do not retry; cache the miss for a while.
rate_limited Minute limit reached. Wait Retry-After seconds.
daily_quota_exceededuser_daily_quota_exceeded Daily quota used up. Stop until X-RateLimit-Daily-Reset (00:00 UTC).
upstream_budget_exceeded Data query budget used up. Cached data still works; try new lookups after Retry-After.
service_unavailablemaintenance Temporary. Retry after Retry-After seconds.
Every error carries a code; the retryable ones are marked green. · Sample view; names and numbers are fictional.
# --retry retries 429 / 503 and honours Retry-After; -i prints the headers
curl -i --retry 3 --retry-max-time 60 \
-H "Authorization: Bearer UGI-xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx" \
"https://api.ugilabs.com/v1/rank/eu/ugiDemo/0001"HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1794925920
X-RateLimit-Daily-Limit: 2000
X-RateLimit-Daily-Remaining: 1712
X-RateLimit-Daily-Reset: 1794960000
X-Request-Id: 9f2c4e1a7b3d5f60
{
"status": 429,
"error": "Rate limit exceeded. Try again later.",
"code": "rate_limited",
"request_id": "9f2c4e1a7b3d5f60"
}09
Every 200 response carries an ETag. Send it back in If-None-Match: if the data has not changed you get 304 Not Modified with an empty body.
X-Cache: HIT means the response came from the shared server cache; Age is how many seconds ago it was stored and X-Cache-TTL how many more seconds it counts as fresh for your plan (current values per plan are in the docs).
BASE, API_KEY and session from the Authentication section.
ETag: "3b7f0c2d…"
Response body2.4 KB
If-None-Match: "3b7f0c2d…"
Response body0 B
The second request sends the same ETag; if nothing changed the body comes back empty. · Sample view; names and numbers are fictional.
# 1) First request: note the ETag (and X-Cache / Age / X-Cache-TTL from the server cache)
curl -si "https://api.ugilabs.com/v1/rank/eu/ugiDemo/0001" -H "Authorization: Bearer UGI-xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx" \
| grep -iE '^(etag|x-cache|age|x-cache-ttl):'
# ETag: "9a0364b9e99bb480dd25e1f0284c8555"
# X-Cache: HIT
# Age: 128
# X-Cache-TTL: 172 (Basic: fresh for 300 s, so 300 - 128)
# 2) Revalidate: 304 Not Modified with an empty body if nothing changed
curl -si "https://api.ugilabs.com/v1/rank/eu/ugiDemo/0001" -H "Authorization: Bearer UGI-xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx" \
-H 'If-None-Match: "9a0364b9e99bb480dd25e1f0284c8555"' | head -n 1
# HTTP/1.1 304 Not Modified
# 3) Premium keys only: skip the cache for live data (max once per 10 s per player and endpoint)
curl -s "https://api.ugilabs.com/v1/rank/eu/ugiDemo/0001?force=true" -H "Authorization: Bearer UGI-xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx"10
When a player you track plays a new match, ugiAPI sends a signed POST to your server. These receivers verify X-UGI-Signature, drop duplicates and act on the event type.
sha256= + HMAC-SHA256(secret, timestamp + "." + raw_body); use the raw body and reject X-UGI-Timestamp values older than 5 minutes.
2xx within 5 seconds; otherwise the delivery is retried after 1, 5 and 30 minutes with the same X-UGI-Delivery.
changes object. The panel's "Send test" button sends webhook.test.
ugiDemo#0001
Gold 1 · 50 → 71 RR +21
When a match ends a signed POST reaches your server, with the changed fields and fresh data. · Sample view; names and numbers are fictional.
// Node 18+ · npm i express · UGI_WEBHOOK_SECRET=whsec_... node webhook.js
// Run it behind HTTPS (reverse proxy or tunnel); the webhook URL must be https.
const crypto = require('crypto');
const express = require('express');
const SECRET = process.env.UGI_WEBHOOK_SECRET; // Panel → Webhooks → Secret
const TOLERANCE_S = 300; // reject deliveries older than 5 minutes
const seen = new Set(); // handled delivery ids (use Redis or a DB table in production)
function verify(req) {
const ts = req.get('X-UGI-Timestamp') ?? '';
const sig = req.get('X-UGI-Signature') ?? '';
if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > TOLERANCE_S) return false;
const expected = 'sha256=' + crypto.createHmac('sha256', SECRET)
.update(ts + '.')
.update(req.body) // the raw Buffer, exactly as received
.digest('hex');
const a = Buffer.from(expected);
const b = Buffer.from(sig);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
const app = express();
// express.raw() keeps the exact bytes; express.json() would re-serialize them and break the signature
app.post('/ugi/webhook', express.raw({ type: 'application/json' }), (req, res) => {
if (!verify(req)) return res.status(401).send('invalid signature');
const deliveryId = req.get('X-UGI-Delivery');
if (seen.has(deliveryId)) return res.sendStatus(200); // a retry of something already handled
seen.add(deliveryId);
res.sendStatus(204); // answer within 5 s, then do the slow work
const event = JSON.parse(req.body.toString('utf8'));
const who = event.data.account ? `${event.data.account.name}#${event.data.account.tag}` : '';
switch (event.event) {
case 'match.new': {
const m = event.data.last_match;
console.log(`${who} ${m.won ? 'won' : 'lost'} a ${m.queue} match: ${m.kills}/${m.deaths}/${m.assists}`);
break;
}
case 'rank.changed':
console.log(`${who} is now ${event.data.rank.tier_name} (${event.data.rank.rr} RR)`, event.changes.rr ?? '');
break;
case 'account.level_changed':
console.log(`${who} reached level ${event.changes.account_level.to}`);
break;
case 'webhook.test':
console.log('Test delivery:', event.data.message);
break;
}
});
app.listen(3000, () => console.log('Listening on :3000'));{
"event": "match.new",
"delivery_id": "3f2a9c1e7b4d4f0a8e6b2c5d1a9f7e3b",
"puuid": "44444444-4444-4444-8444-444444444444",
"region": "eu",
"label": "Main account",
"changes": {
"last_match": { "from": "a1f0c2d4-5b6e-4f70-8a9b-0c1d2e3f4a5b", "to": "b7e3d9f1-2a4c-4e6b-9d8f-1a3c5e7b9d0f" },
"account_level": { "from": 40, "to": 41 },
"rr": { "from": 50, "to": 71 }
},
"data": {
"account": {
"puuid": "44444444-4444-4444-8444-444444444444",
"name": "ugiDemo",
"tag": "0001",
"account_level": 41,
"card": "3e1f4b2a-9c8d-4e7f-a6b5-c4d3e2f1a0b9",
"title": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
},
"rank": { "tier": 12, "tier_name": "Gold 1", "rr": 71 },
"last_match": {
"match_id": "b7e3d9f1-2a4c-4e6b-9d8f-1a3c5e7b9d0f",
"queue": "competitive",
"started_at": "2026-11-17T19:42:10Z",
"map_id": "/Game/Maps/Ascent/Ascent",
"agent_id": "320b2a48-4d9b-a075-30f1-1f93a9b638fa",
"won": true,
"kills": 20,
"deaths": 10,
"assists": 5,
"score": 5000
}
},
"sent_at": "2026-11-17T20:15:03Z"
}Get a key, paste it into an example and you have data in a minute. The docs list every parameter and include an interactive playground.