REST APIAPI anahtarı yokCORSJSON · PNG · HTML

MCAPI.TR Geliştirici Platformu

API Dokümantasyonu

Minecraft Java, Legacy ve Bedrock sunucularını sorgulamak; ikon, banner, widget, trend ve platform istatistiklerini kullanmak için eksiksiz MCAPI.TR geliştirici rehberi.

OpenAPI JSON Canlı dene

Temel URLhttps://mcapi.tr/api/v1

01 — Hızlı başlangıç

İlk yanıtını saniyeler içinde al

Kurulum veya anahtar yok. Bir araç seç, örneği kopyala ve çalıştır.

curl

curl "https://mcapi.tr/api/v1/status/mc.hypixel.net"

02 — API Deneme Alanı

Tarayıcıdan canlı istek gönder

İstek doğrudan MCAPI.TR API'sine gider; sonuç aşağıda biçimlendirilir.

03 — Uç Referansı

Tüm herkese açık uçlar

Bir kartı açarak parametreleri, önbellek davranışını ve çalıştırılabilir örnekleri görebilirsin.

GET/api/v1/status

API sağlık kontrolü

Servisin ayakta olduğunu, sürümünü ve sunucu saatini doğrular. İzleme sistemleri için hafif uçtur.

application/json

Kimlik doğrulama

API anahtarı gerektirmez

Önbellek

Yok

Content-Type

application/json

Örnek istek

bash

curl "https://mcapi.tr/api/v1/status"

Örnek yanıt

json

{
  "status": "OK",
  "timestamp": "2026-09-08T20:12:00.000Z",
  "service": "mcapi.tr-engine",
  "version": "0.1.0"
}

GET/api/v1/status/:address

Minecraft sunucu durumu

Java, Legacy Java veya Bedrock sunucusunun çevrimiçi durumunu; oyuncu, sürüm, MOTD, ikon ve gecikme bilgileriyle döndürür.

application/json

Kimlik doğrulama

API anahtarı gerektirmez

Önbellek

Varsayılan 60 saniye

Content-Type

application/json

Parametreler

Parametre	Konum	Tip	Varsayılan	Açıklama
`address`*	path	string	—	Alan adı veya IP; isteğe bağlı port eklenebilir: play.example.net:25565
`legacy`	query	boolean	false	1.7.2 öncesi Java ping protokolünü zorlar.
`bedrock`	query	boolean	false	Bedrock Edition sorgusu yapar; varsayılan port 19132 olur.

Örnek istek

bash

curl "https://mcapi.tr/api/v1/status/mc.hypixel.net"
curl "https://mcapi.tr/api/v1/status/bedrock.example.net:19132?bedrock=true"

Örnek yanıt

json

{
  "query": {
    "host": "mc.hypixel.net",
    "port": 25565,
    "legacy": false,
    "bedrock": false
  },
  "server_id": "f17d4f75-...",
  "ip_address": "209.222.115.11",
  "icmp": true,
  "online": true,
  "stale": false,
  "error": null,
  "checked_at": "2026-09-12T15:59:36.430Z",
  "version": { "name": "Requires MC 1.8 / 1.21", "protocol": 47 },
  "players": { "online": 52184, "max": 200000, "sample": [] },
  "motd": {
    "raw": "§aHypixel Network",
    "clean": "Hypixel Network",
    "html": "<span style=\"color:#55FF55\">Hypixel Network</span>",
    "raw_lines": ["§aHypixel Network"],
    "clean_lines": ["Hypixel Network"]
  },
  "favicon": "data:image/png;base64,...",
  "srvRecord": null,
  "roundTripLatency": 18
}

GET/api/v1/trends

Trend sunucular

Trend puanına göre sıralanmış sunucuları cursor tabanlı sayfalama bilgisiyle döndürür.

application/json

Kimlik doğrulama

API anahtarı gerektirmez

Önbellek

5 min

Content-Type

application/json

Parametreler

Parametre	Konum	Tip	Varsayılan	Açıklama
`limit`	query	integer	10	Sayfa boyutu; 1 ile 50 arasında sınırlandırılır.
`cursor`	query	UUID	—	Önceki yanıttaki meta.nextCursor değeri.

Örnek istek

bash

curl "https://mcapi.tr/api/v1/trends?limit=10"

Örnek yanıt

json

{
  "success": true,
  "data": [
    {
      "server_id": "f17d4f75-...",
      "hostname": "mc.hypixel.net",
      "address": "mc.hypixel.net",
      "port": 25565,
      "edition": "java",
      "trend_score": 842,
      "daily_growth": 14.6,
      "is_online": true,
      "stale": false,
      "checked_at": "2026-09-12T15:59:36.430Z",
      "players_online": 52184,
      "players_max": 200000,
      "version": "Requires MC 1.8 / 1.21",
      "favicon": "21aa8597...",
      "record_players": 74312,
      "uptime_percentage": 99.8
    }
  ],
  "meta": { "nextCursor": "f17d4f75-...", "hasNext": true, "limit": 10 }
}

GET/api/v1/stats

Genel platform istatistikleri

Toplam istek, kontrol edilen sunucu, çevrimiçi oranı, aktif oyuncu ve son kontrol özetlerini verir.

application/json

Kimlik doğrulama

API anahtarı gerektirmez

Önbellek

60 sec

Content-Type

application/json

Örnek istek

bash

curl "https://mcapi.tr/api/v1/stats"

Örnek yanıt

json

{
  "totalRequests": 1284502,
  "apiRequests": 612340,
  "serverQueries": 672162,
  "totalChecks": 672162,
  "onlineServers": 428,
  "offlineServers": 91,
  "activePlayers": 184205,
  "recentChecks": [],
  "onlineRate": 82.5
}

GET/api/v1/icon/dynamic

Sunucu ikonu

Sunucu favicon'unu döndürür; ikon yoksa MCAPI.TR varsayılan görselini kullanır.

image/png | image/webp

Kimlik doğrulama

API anahtarı gerektirmez

Önbellek

Tarayıcı 1 gün, CDN 7 gün

Content-Type

image/png | image/webp

Parametreler

Parametre	Konum	Tip	Varsayılan	Açıklama
`address`*	query	string	—	Sunucu adresi. server da geriye dönük takma ad olarak kabul edilir.
`size`	query	integer	80	WebP dönüşüm boyutu; 16–256 piksel.
`format`	query	png \| webp	png	webp seçildiğinde optimize edilmiş kare görsel üretir.

Örnek istek

bash

curl "https://mcapi.tr/api/v1/icon/dynamic?address=mc.hypixel.net&size=128&format=webp" --output server.webp

GET/api/v1/icon/sharp

Yuvarlatılmış sunucu ikonu

Sunucu ikonunu yumuşak köşeli, yeniden boyutlandırılmış PNG olarak üretir.

image/png

Kimlik doğrulama

API anahtarı gerektirmez

Önbellek

Tarayıcı 1 gün, CDN 7 gün

Content-Type

image/png

Parametreler

Parametre	Konum	Tip	Varsayılan	Açıklama
`address`*	query	string	—	Sunucu alan adı veya IP adresi.
`size`	query	integer	128	32–512 piksel arası çıktı boyutu.

Örnek istek

bash

curl "https://mcapi.tr/api/v1/icon/sharp?address=mc.hypixel.net&size=256" --output icon.png

GET/api/v1/banner/:address

Sunucu durum banner'ı

Sunucu adı, oyuncu sayısı, MOTD, ping ve favicon ile paylaşılabilir PNG banner oluşturur.

image/png

Kimlik doğrulama

API anahtarı gerektirmez

Önbellek

Sunucu/CDN politikasına bağlı

Content-Type

image/png

Parametreler

Parametre	Konum	Tip	Varsayılan	Açıklama
`address`*	path	string	—	Banner'ı üretilecek sunucu.
`size`	query	small \| normal \| large	normal	Çıktı ölçüsü: 400×130, 600×180 veya 800×240.
`style`	query	modern \| classic	modern	Banner görünümü.
`textColor`	query	hex color	#FFFFFF	Ana metin rengi.
`accentColor`	query	hex color	#10B981	Oyuncu sayısı vurgu rengi.
`showFavicon / showMotd / showPing`	query	boolean	true	İkon, MOTD ve gecikme alanlarını ayrı ayrı açıp kapatır.
`borderRadius`	query	number	0.5	Köşe yuvarlaklığı çarpanı.

Örnek istek

bash

curl "https://mcapi.tr/api/v1/banner/mc.hypixel.net?size=large&accentColor=%2310B981" --output banner.png

GET/api/v1/banner/motd

MOTD metin banner'ı

Minecraft renk kodlu MOTD metnini, bir sunucu sorgulamadan 800×180 PNG görsele dönüştürür.

image/png

Kimlik doğrulama

API anahtarı gerektirmez

Önbellek

Uygulama önbelleği yok

Content-Type

image/png

Parametreler

Parametre	Konum	Tip	Varsayılan	Açıklama
`motd`*	query	string	—	En fazla 300 karakter MOTD metni.
`textColor`	query	hex color	#FFFFFF	Varsayılan metin rengi.
`accentColor`	query	hex color	#10B981	Arka plan vurgu rengi.

Örnek istek

bash

curl "https://mcapi.tr/api/v1/banner/motd?motd=%C2%A7aWelcome" --output motd.png

GET/api/v1/widget/:size/:address

Gömülebilir HTML widget

Web siteleri ve paneller için özelleştirilebilir, canlı sunucu durumu HTML'i döndürür.

text/html

Kimlik doğrulama

API anahtarı gerektirmez

Önbellek

60 sec + stale-while-revalidate

Content-Type

text/html

Parametreler

Parametre	Konum	Tip	Varsayılan	Açıklama
`size`*	path	small \| normal \| large	—	Widget yerleşimi ve varsayılan yüksekliği.
`address`*	path	string	—	Sunucu adresi; önizleme için demo kullanılabilir.
`theme`	query	dark \| light	dark	Temel renk teması.
`showPlayers / showVersion / showMotd`	query	boolean	true	Ana bilgi alanlarını ayrı ayrı açıp kapatır.
`showLatency / showFavicon`	query	boolean	true	Ping ve favicon görünürlüğü.
`showProtocol / showBorder`	query	boolean	false	Protokol ve kenarlığı isteğe bağlı gösterir.
`bgColor / textColor`	query	hex color	—	Widget arka planı ve metin rengi.
`onlineColor / offlineColor`	query	hex color	#10b981 / #ef4444	Çevrimiçi ve çevrimdışı durum renkleri.
`gradientBg / gradientFrom / gradientTo`	query	boolean / hex	false	Gradyan arka plan seçenekleri.
`statusIndicator`	query	dot \| text \| badge \| none	dot	Durum gösterge biçimi.
`iconSize`	query	small \| medium \| large	medium	Favicon boyutu.
`font`	query	Inter \| Roboto \| Poppins \| Montserrat \| Outfit	—	Google Fonts yazı tipi.
`textAlign`	query	left \| center \| right	left	Metin hizası.
`customHeight`	query	CSS px	—	50–600 piksel arası özel yükseklik.
`borderRadius / borderWidth`	query	number	0.75 / 1	Köşe ve kenarlık ölçüleri.
`hoverEffect / glowEffect / boxShadow`	query	boolean	false	Görsel efektleri etkinleştirir.
`playerBarStyle`	query	default \| gradient \| striped \| animated	default	Oyuncu doluluk çubuğu görünümü.

Örnek istek

bash

curl "https://mcapi.tr/api/v1/widget/normal/mc.hypixel.net?theme=dark&showFavicon=true"

04 — Şema

Sunucu yanıt alanları

Alan	Tip	Açıklama
`query`	object	Çözümlenen host, port ve sorgu modu.
`server_id`	UUID	MCAPI.TR içindeki kararlı sunucu kimliği.
`online`	boolean	Minecraft ping işleminin başarılı olup olmadığı.
`stale`	boolean	Yanıtın yeni bir sorgu yerine son başarılı kontrolden gelip gelmediği.
`checked_at`	ISO 8601	Bu yanıtta gösterilen sunucu kontrolünün UTC zamanı.
`icmp`	boolean	Hedef IP'nin ICMP ping yanıtı.
`version`	object \| null	Sunucunun sürüm adı ve protokol numarası.
`players`	object \| null	Çevrimiçi, kapasite ve isteğe bağlı örnek oyuncular.
`motd`	object \| null	Ham, temizlenmiş ve HTML MOTD biçimleri ile satır dizileri.
`favicon`	data URL \| null	Base64 kodlu sunucu ikonu.
`srvRecord`	object \| null	Keşif kullanıldıysa çözümlenen Minecraft SRV kaydı ayrıntıları.
`roundTripLatency`	number \| null	Milisaniye cinsinden Minecraft sorgu gecikmesi.
`error`	string \| null	Başarısız sorgunun güvenli hata özeti.

HTTP

Durum kodları

200İstek başarılı.

400Adres veya sorgu parametresi geçersiz.

404Sunucu çevrimdışı ya da ulaşılamıyor.

429Dakikalık istek limiti aşıldı.

500Beklenmeyen sunucu hatası.

503Bakım modu etkin.

Politikalar

Limitler ve önbellek

status:IP başına dakikada 120 istek.
default:Genel uçlarda varsayılan dakikada 300 istek.
media:İkon, banner ve widget uçlarında dakikada 5.000 isteğe kadar.
cors:Herkese açık API uçlarında tüm tarayıcı origin'lerine açıktır.
privacy:İstek profillemesinde ham IP ve kullanıcı aracısı saklanmaz.

Resmî SDK'lar

API'yi Node.js ve Python ile kullan

Resmî ve sıfır bağımlılıklı istemciler API anahtarı istemeden tipli sunucu sorguları, keşif, istatistik ve medya yardımcıları sunar.

Node.js

mcapitr

npm ↗

Eksiksiz TypeScript tanımları ve üretilen medya için Buffer yardımcıları bulunan Promise tabanlı Node.js istemcisi.

bash

npm install mcapitr

Node.js 18+TypeScriptPromise API

Python

mcapitr

PyPI ↗

Tipli hatalar, sayfalama ve bayt indirmeleri sunan eşzamanlı ve asenkron Python istemcileri.

bash

pip install mcapitr

Python 3.9+TypedSync + Async

İlk yanıtını saniyeler içinde al

Tarayıcıdan canlı istek gönder

Tüm herkese açık uçlar

API sağlık kontrolü

Örnek istek

Örnek yanıt

Minecraft sunucu durumu

Parametreler

Örnek istek

Örnek yanıt

Trend sunucular

Parametreler

Örnek istek

Örnek yanıt

Genel platform istatistikleri

Örnek istek

Örnek yanıt

Sunucu ikonu

Parametreler

Örnek istek

Yuvarlatılmış sunucu ikonu

Parametreler

Örnek istek

Sunucu durum banner'ı

Parametreler

Örnek istek

MOTD metin banner'ı

Parametreler

Örnek istek

Gömülebilir HTML widget

Parametreler

Örnek istek

Sunucu yanıt alanları

Durum kodları

Limitler ve önbellek

API'yi Node.js ve Python ile kullan

mcapitr

mcapitr

Gizlilik Politikası

Kişisel Verilerinizin Korunması

Toplanan Veriler

Çerezler

Veri Güvenliği

İletişim

Kullanım Koşulları

Hizmet Koşulları

Hizmet Tanımı

Kullanım Sınırlamaları

Sorumluluk Reddi

Fikri Mülkiyet Hakları

Değişiklikler

İletişim