Minecraft API

Безкоштовний API для отримання даних про гравців Minecraft

Наш API дозволяє отримувати інформацію про гравців Minecraft: UUID, скіни, аватарки та історію нікнеймів. Всі ендпоінти безкоштовні та не потребують автентифікації.

Base URL https://mc.uwu.org.ua/api/minecraft

GET /api/minecraft/:player

Отримати повну інформацію про гравця: UUID, нікнейм, URL скіна та плаща.

Параметри шляху

player обов'язковий Username або UUID гравця

Приклад запиту

GET /api/minecraft/Hacker_Zaba
GET /api/minecraft/069a79f4-44e9-4726-a5be-fca90e38aaf5

Приклад відповіді

{
  "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
  "username": "Hacker_Zaba",
  "skin": "https://textures.minecraft.net/texture/...",
  "cape": null,
  "model": "default"
}

Поля відповіді

`uuid`	UUID гравця з дефісами
`username`	Поточний нікнейм гравця
`skin`	URL текстури скіна (Mojang CDN)
`cape`	URL текстури плаща або `null`
`model`	`"default"` (Steve) або `"slim"` (Alex)

JavaScript

fetch('/api/minecraft/Hacker_Zaba')
  .then(res => res.json())
  .then(data => console.log(data.uuid));

GET /api/minecraft/head/:player

Отримати аватарку голови гравця як PNG зображення. Повертає бінарні дані зображення.

Параметри шляху

player обов'язковий Username або UUID гравця

Query параметри

`size`	опціональний	Розмір зображення в пікселях (8-512). За замовчуванням: `64`
`overlay`	опціональний	Показувати шар шапки (`true`/`false`). За замовчуванням: `true`

Приклади запитів

GET /api/minecraft/head/Hacker_Zaba
GET /api/minecraft/head/Hacker_Zaba?size=128
GET /api/minecraft/head/Hacker_Zaba?size=256&overlay=false

Візуальні приклади

?size=64 з overlay

?size=128 з overlay

?overlay=false без overlay

HTML використання

<img src="https://mc.uwu.org.ua/api/minecraft/head/Hacker_Zaba?size=64" alt="Avatar" />

<!-- Великий аватар без шапки -->
<img src="https://mc.uwu.org.ua/api/minecraft/head/Hacker_Zaba?size=256&overlay=false" alt="Avatar" />

GET /api/minecraft/history/:player

Отримати історію нікнеймів гравця.

Параметри шляху

player обов'язковий Username або UUID гравця

Приклад запиту

GET /api/minecraft/history/Hacker_Zaba

Приклад відповіді

{
  "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
  "username": "Hacker_Zaba",
  "name_history": [
    { "username": "Hacker_Zaba" },
    { "username": "OldName", "changed_at": "2015-01-15T10:30:00Z" }
  ]
}

Поля відповіді

`uuid`	UUID гравця
`username`	Поточний нікнейм
`name_history`	Масив попередніх нікнеймів з датами зміни

GET /api/minecraft/skin-history/:player

Отримати історію скінів гравця (тільки ті, що були збережені нашим сервером).

Параметри шляху

player обов'язковий Username або UUID гравця

Приклад запиту

GET /api/minecraft/skin-history/Hacker_Zaba

Приклад відповіді

{
  "uuid": "069a79f444e94726a5befca90e38aaf5",
  "count": 3,
  "skins": [
    {
      "timestamp": 1704567890123,
      "date": "06.01.2026, 15:30:45",
      "url": "/api/minecraft/skin-file/069a79f444e94726a5befca90e38aaf5_1704567890123.png"
    },
    {
      "timestamp": 1704456789012,
      "date": "05.01.2026, 10:15:30",
      "url": "/api/minecraft/skin-file/069a79f444e94726a5befca90e38aaf5_1704456789012.png"
    }
  ]
}

Поля відповіді

`uuid`	UUID гравця (без дефісів)
`count`	Кількість збережених скінів
`skins`	Масив скінів від найновішого до найстарішого
`skins[].timestamp`	Unix timestamp (мілісекунди)
`skins[].date`	Дата у форматі UK (dd.mm.yyyy, hh:mm:ss)
`skins[].url`	Шлях до файлу скіна

⚠️ Примітка: Історія скінів накопичується тільки коли гравці використовують наш API. Ми не маємо доступу до повної історії Mojang.

GET /api/minecraft/skin-file/:filename

Отримати конкретний файл скіна з історії. Повертає PNG зображення.

Параметри шляху

filename обов'язковий Назва файлу скіна (отримана з /skin-history)

Приклад запиту

GET /api/minecraft/skin-file/069a79f444e94726a5befca90e38aaf5_1704567890123.png

Відповідь

PNG зображення скіна (64×64 або 64×32 для старих скінів)

HTML використання

<img src="https://mc.uwu.org.ua/api/minecraft/skin-file/uuid_timestamp.png" alt="Skin" />

⚡ Кешування та ліміти

Дані гравця кешуються на 60 секунд
Історія нікнеймів кешується на 5 хвилин
Аватарки кешуються на 5 хвилин
Файли скінів кешуються на 1 рік (immutable)
Немає обмежень на кількість запитів
CORS увімкнено для всіх доменів

📋 Заголовки відповіді

`X-Cache`	`HIT` — дані з кешу, `MISS` — свіжі дані
`Cache-Control`	Рекомендований час кешування для клієнта
`Access-Control-Allow-Origin`	`*` — дозволяє CORS запити

❌ Коди помилок

`400 Bad Request`	Не вказано гравця або невалідні параметри
`404 Not Found`	Гравця або файл не знайдено
`500 Internal Error`	Помилка сервера або Mojang API недоступний

Приклад помилки

{
  "error": "Player not found"
}

💡 Приклади використання

Отримати аватар та ім'я гравця

async function getPlayer(username) {
  const res = await fetch(`/api/minecraft/${username}`);
  const data = await res.json();
  
  return {
    name: data.username,
    avatar: `/api/minecraft/head/${data.uuid}?size=128`,
    isSlim: data.model === 'slim'
  };
}

Показати історію скінів

async function showSkinHistory(username) {
  const res = await fetch(`/api/minecraft/skin-history/${username}`);
  const data = await res.json();
  
  data.skins.forEach(skin => {
    const img = document.createElement('img');
    img.src = skin.url;
    img.title = skin.date;
    container.appendChild(img);
  });
}