REST API

Τεκμηρίωση API

Ενσωματώστε ζωντανά δεδομένα διακομιστή Minecraft, player, skin και κοινότητας από το mcstat.org στις δικές σας εφαρμογές, bots και πίνακες ελέγχου.

Βασική διεύθυνση URL

Όλα τα αιτήματα API ξεκινούν με αυτό το βασικό URL

https://mcstat.org/api/v1

Προβολή ως Markdown

Ακατέργαστη τεκμηρίωση Markdown για AI, bots και εργαλεία

Κλειδιά API

Διαχειριστείτε και παρακολουθήστε τα κλειδιά API σας

Δημιουργήστε, περιστρέψτε και προβάλετε αναλυτικά στοιχεία για τα κλειδιά API στον πίνακα εργαλείων.

Ανοίξτε τον πίνακα ελέγχου κλειδιού API

Περιβάλλον Δοκιμών API

Δοκιμάστε τα τελικά σημεία απευθείας στο πρόγραμμα περιήγησης

Έλεγχος Bot

Αυτό το περιβάλλον δοκιμών δεν απαιτεί κλειδί API· απαιτείται ανθρώπινη επαλήθευση για μείωση της κατάχρησης.

Τελικό σημείο

GET

/api/v1/servers

Παράμετροι ερωτήματος

page

integer

limit

integer

sort

string

search

string

country

string

version

string

tag

string

mode

string

minPlayers

integer

maxPlayers

integer

minUptime

number

minVotes

integer

minRating

number

onlineOnly

boolean

Αίτημα URL

https://mcstat.org/api/v1/servers

Εκτελέστε ένα αίτημα για να δείτε την απάντηση

Έλεγχος ταυτότητας

Όλα τα τεκμηριωμένα δημόσια τελικά σημεία API απαιτούν κλειδί API. Στείλτε το κλειδί σας στην κεφαλίδα X-API-Key.

Κεφαλίδα αιτήματος

Προσθέστε αυτήν την κεφαλίδα για έλεγχο ταυτότητας

X-API-Key: mcs_your_key_here

Ή ως παράμετρος ερωτήματος

Ή περάστε ως παράμετρος ερωτήματος

?api_key=mcs_your_key_here

Όρια ποσοστών

Τα αιτήματα επαληθεύονται με κλειδί API. Ένα κλειδί που λείπει ή δεν είναι έγκυρο επιστρέφει το HTTP 401, ένα απενεργοποιημένο κλειδί επιστρέφει το HTTP 403 και το υπέρβαση του ορίου επιστρέφει το HTTP 429.

Χωρίς κλειδί API

Δεν επιτρέπεται

Με κλειδί API

60 αιτήματα ανά λεπτό, 1.000 την ημέρα και 30.000 το μήνα από προεπιλογή. Η υπέρβαση ενός ορίου επιστρέφει το HTTP 429 με τις κεφαλίδες X-RateLimit-* που δείχνουν τα όριά σας και ένα Retry-After που σας ενημερώνει πότε γίνεται επαναφορά του παραθύρου. Μπορούν να χορηγηθούν υψηλότερα όρια ανά κλειδί κατόπιν αιτήματος.

Κεφαλίδες ορίου ποσοστού:Μια απόκριση 429 περιλαμβάνει X-RateLimit-Limit-Minute, X-RateLimit-Limit-Day, X-RateLimit-Remaining-Day, X-RateLimit-Limit-Month, X-RateLimit-Remaining-Month και Retry-After. Οι επιτυχείς αποκρίσεις έχουν μια κεφαλίδα Cache-Control, ώστε να μπορείτε να αποθηκεύετε με ασφάλεια τα αποτελέσματα από την πλευρά του πελάτη.

Μορφή απάντησης

Κάθε επιτυχημένη απάντηση είναι JSON με ένα δυαδικό όριο και ένα αντικείμενο . Τα σφάλματα χρησιμοποιούν τον ίδιο φάκελο με το : false.

Απόκριση επιτυχίας

JSON

{
  "success": true,
  "data": {
    "resource": {
      "id": "...",
      "name": "Example"
    }
  }
}

Απόκριση σφάλματος

JSON

{
  "success": false,
  "error": "Too many requests"
}

Σφάλματα

Χρησιμοποιούνται τυπικοί κωδικοί κατάστασης HTTP. Συνήθεις περιπτώσεις:

Κωδικός	Σημασία
`400`	Κακό αίτημα — μη έγκυρες παράμετροι
`401`	Μη εξουσιοδοτημένο — λείπει ή δεν είναι έγκυρο κλειδί API
`403`	Απαγορευμένο — Το κλειδί API είναι απενεργοποιημένο
`404`	Δεν βρέθηκε — ο πόρος δεν υπάρχει
`429`	Πάρα πολλά αιτήματα — Υπέρβαση του ορίου τιμής
`500`	Σφάλμα εσωτερικού διακομιστή — δοκιμάστε ξανά αργότερα

Τελικά σημεία διακομιστή

Περιηγηθείτε, φιλτράρετε και επιθεωρήστε διακομιστές Minecraft που παρακολουθούνται από το mcstat.org.

GET

/api/v1/servers

Διακομιστές λίστας

Σελιδοποιημένη λίστα δημόσιων διακομιστών με πλούσια φίλτρα.

Παράδειγμα αιτήματος

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers"

Παράμετροι ερωτήματος

Όνομα	Τύπος	απαιτείται	προεπιλογή	Περιγραφή
`page`	`integer`	Όχι	`1`	Αριθμός σελίδας, από 1.
`limit`	`integer`	Όχι	`20`	Στοιχεία ανά σελίδα.
`sort`	`string`	Όχι	`recent`	Σειρά ταξινόμησης.
`search`	`string`	Όχι	`—`	Ερώτημα ελεύθερου κειμένου.
`country`	`string`	Όχι	`—`	Φίλτρο ονόματος χώρας ISO.
`version`	`string`	Όχι	`—`	Φίλτρο έκδοσης Minecraft.
`tag`	`string`	Όχι	`—`	Φιλτράρισμα ανά ετικέτα.
`mode`	`string`	Όχι	`—`	Φίλτρο λειτουργίας παιχνιδιού.
`minPlayers`	`integer`	Όχι	`—`	Ελάχιστος τρέχων αριθμός παικτών.
`maxPlayers`	`integer`	Όχι	`—`	Μέγιστος τρέχων αριθμός παικτών.
`minUptime`	`number`	Όχι	`—`	Ελάχιστο ποσοστό χρόνου λειτουργίας.
`minVotes`	`integer`	Όχι	`—`	Ελάχιστη συνολική καταμέτρηση ψήφων.
`minRating`	`number`	Όχι	`—`	Ελάχιστη βαθμολογία (1–5).
`onlineOnly`	`boolean`	Όχι	`—`	Συμπεριλάβετε μόνο διακομιστές που υποβάλλουν αναφορές στο διαδίκτυο.

Παράδειγμα απάντησης

JSON

{
  "success": true,
  "data": {
    "servers": [
      {
        "id": "JS6o0w88QP6oZHDj",
        "slug": "mchypixelnet",
        "name": "Hypixel Network",
        "shortDescription": "Home of over 35 unique games…",
        "ip": "mc.hypixel.net",
        "port": 25565,
        "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp",
        "bannerUrl": "https://mcstat.org/media/banners/mchypixelnet.webp",
        "motdImageUrl": "https://mcstat.org/images/server-motd/mchypixelnet.svg",
        "motd": "Hypixel Network",
        "website": null,
        "discordUrl": null,
        "visibility": "PUBLIC",
        "isOnline": true,
        "currentPlayers": 48230,
        "maxPlayers": 200000,
        "version": "Requires MC 1.8 / 1.21",
        "latency": 42,
        "lastPing": "2026-05-24T22:00:00Z",
        "country": "United States",
        "tags": [
          "bedwars",
          "pvp",
          "skyblock"
        ],
        "gameMode": null,
        "uptime": 100,
        "trend": 3.4,
        "totalVotes": 12345,
        "rating": 4.6,
        "createdAt": "2026-04-28T05:44:26Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 24,
      "total": 1240,
      "totalPages": 52
    }
  }
}

GET

/api/v1/servers/{slug}

Λεπτομέρεια διακομιστή

Πλήρες προφίλ διακομιστή: ιστορικό στατιστικών, χρόνος λειτουργίας, διάγραμμα ψηφοφορίας, βαθμολογίες.

Παράδειγμα αιτήματος

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/hypixel-net"

Παράμετροι ερωτήματος

Όνομα	Τύπος	απαιτείται	προεπιλογή	Περιγραφή
`slug`	`string`	Ναι	`—`	Slug διακομιστή (από τη λίστα /servers).
`period`	`string`	Όχι	`24h`	Χρονικό παράθυρο: 24h, 7d, 30d, 90d, all-time.

Παράδειγμα απάντησης

JSON

{
  "success": true,
  "data": {
    "server": {
      "id": "JS6o0w88QP6oZHDj",
      "slug": "mchypixelnet",
      "name": "Hypixel Network",
      "ip": "mc.hypixel.net",
      "port": 25565,
      "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp",
      "bannerUrl": "https://mcstat.org/media/banners/mchypixelnet.webp",
      "motd": "Hypixel Network",
      "motdRaw": "§aHypixel §7Network",
      "motdImageUrl": "https://mcstat.org/images/server-motd/mchypixelnet.svg",
      "website": null,
      "discordUrl": null,
      "storeUrl": null,
      "youtubeUrl": null,
      "currentPlayers": 48230,
      "maxPlayers": 200000,
      "isOnline": true,
      "country": "United States",
      "version": "Requires MC 1.8 / 1.21",
      "protocol": 767,
      "uptime": 100,
      "rating": 4.6,
      "totalVotes": 12345,
      "tags": [
        "bedwars",
        "pvp"
      ],
      "owner": null,
      "latestStats": {
        "onlinePlayers": 48230,
        "tps": 20,
        "timestamp": "2026-05-24T22:00:00Z"
      },
      "statsHistory": [
        {
          "timestamp": "2026-05-24T21:00:00Z",
          "onlinePlayers": 47000
        }
      ],
      "periodStats": {
        "24h": {
          "avgPlayers": 46500,
          "peakPlayers": 49100,
          "minPlayers": 42000,
          "uptimePct": 99.95
        }
      },
      "voteStats": {
        "24h": 412,
        "7d": 2890,
        "30d": 11200,
        "90d": 30150
      },
      "dailyVotes": [
        {
          "day": "2026-05-23",
          "votes": 405
        }
      ]
    }
  }
}

GET

/api/v1/servers/{slug}/voters

Διακομιστές ψηφοφόροι

Πρόσφατοι ψηφοφόροι (επαληθευμένοι και ανώνυμοι) για τον συγκεκριμένο διακομιστή.

Παράδειγμα αιτήματος

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/hypixel-net/voters"

Παράμετροι ερωτήματος

Όνομα	Τύπος	απαιτείται	προεπιλογή	Περιγραφή
`slug`	`string`	Ναι	`—`	Slug διακομιστή (από τη λίστα /servers).
`page`	`integer`	Όχι	`1`	Αριθμός σελίδας, από 1.
`limit`	`integer`	Όχι	`7`	Στοιχεία ανά σελίδα.

Παράδειγμα απάντησης

JSON

{
  "success": true,
  "data": {
    "voters": [
      {
        "id": "TanfrbogDfzGdrgD",
        "minecraftUsername": "Notch",
        "votedAt": "2026-05-24 22:10:06.544",
        "type": "auth",
        "playerId": "xq5-Lw8xk7pEdKyn",
        "minecraftUuid": "069a79f4-3e42-4b0c-8f1a-9c2b1d5e6f70",
        "skinUrl": "http://textures.minecraft.net/texture/cbea0a15a5ce…",
        "linkedSkinPngPath": "https://mcstat.org/media/skins/published/player-skin-notch.png",
        "skinModel": "classic",
        "siteUsername": "notch"
      }
    ],
    "total": 12345,
    "page": 1,
    "totalPages": 515,
    "latestVoteAt": "2026-05-24 22:10:06.544"
  }
}

GET

/api/v1/servers/{slug}/reviews

Κριτικές διακομιστή

Σελιδοποιημένες κριτικές και βαθμολογίες παικτών για έναν διακομιστή.

Παράδειγμα αιτήματος

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/hypixel-net/reviews"

Παράμετροι ερωτήματος

Όνομα	Τύπος	απαιτείται	προεπιλογή	Περιγραφή
`slug`	`string`	Ναι	`—`	Slug διακομιστή (από τη λίστα /servers).
`page`	`integer`	Όχι	`1`	Αριθμός σελίδας, από 1.
`limit`	`integer`	Όχι	`5`	Στοιχεία ανά σελίδα.

Παράδειγμα απάντησης

JSON

{
  "success": true,
  "data": {
    "reviews": [
      {
        "id": "5g4VgYUiN4n28qcX",
        "serverId": "JS6o0w88QP6oZHDj",
        "userId": null,
        "minecraftUsername": "chibibara",
        "rating": 3,
        "content": "Great community!",
        "createdAt": "2026-05-24T22:00:00Z",
        "updatedAt": "2026-05-24T22:00:00Z",
        "user": {
          "id": null,
          "username": "chibibara",
          "avatar": null,
          "role": "USER"
        },
        "playerId": "suTEw8opOK2bGP-L",
        "playerMainNickname": "chibibara",
        "playerMinecraftUuid": "019f1b29-fcbe-705b-8efb-8c08b4e0fd9c",
        "playerSkinUrl": null,
        "playerSkinModel": "classic",
        "playerLinkedSkinPngPath": "https://mcstat.org/media/skins/published/default-steve.png"
      }
    ],
    "total": 128,
    "page": 1,
    "totalPages": 26,
    "avgRating": 4.2,
    "latestReviewAt": "2026-05-24T22:00:00Z"
  }
}

GET

/api/v1/servers/{slug}/updates

Ενημερώσεις διακομιστή

Εγκεκριμένες αναρτήσεις νέων και ενημερώσεων για έναν διακομιστή.

Παράδειγμα αιτήματος

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/hypixel-net/updates"

Παράμετροι ερωτήματος

Όνομα	Τύπος	απαιτείται	προεπιλογή	Περιγραφή
`slug`	`string`	Ναι	`—`	Slug διακομιστή (από τη λίστα /servers).
`page`	`integer`	Όχι	`1`	Αριθμός σελίδας, από 1.
`limit`	`integer`	Όχι	`3`	Στοιχεία ανά σελίδα.

Παράδειγμα απάντησης

JSON

{
  "success": true,
  "data": {
    "updates": [
      {
        "id": "Xk3pQ2mNbV8zR1sd",
        "serverId": "JS6o0w88QP6oZHDj",
        "userId": "Nf3kPq8sT2wVxJ7b",
        "title": "Season 5 is live!",
        "content": "New map, new kits, double XP weekend.",
        "status": "APPROVED",
        "createdAt": "2026-05-24T22:00:00Z",
        "updatedAt": "2026-05-24T22:00:00Z"
      }
    ],
    "total": 12,
    "page": 1,
    "totalPages": 4,
    "latestUpdateAt": "2026-05-24T22:00:00Z"
  }
}

GET

/api/v1/servers/top

Κορυφαίοι διακομιστές

Λίστα τάσεων βελτιστοποιημένη για χρήση αρχικής σελίδας/γραφικού στοιχείου.

Παράδειγμα αιτήματος

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/top"

Παράμετροι ερωτήματος

Όνομα	Τύπος	απαιτείται	προεπιλογή	Περιγραφή
`sort`	`string`	Όχι	`votes`	Σειρά ταξινόμησης.
`limit`	`integer`	Όχι	`10`	Στοιχεία ανά σελίδα.
`country`	`string`	Όχι	`—`	Φίλτρο ονόματος χώρας ISO.
`gameMode`	`string`	Όχι	`—`	Φίλτρο λειτουργίας παιχνιδιού.

Παράδειγμα απάντησης

JSON

{
  "success": true,
  "data": {
    "servers": [
      {
        "id": "JS6o0w88QP6oZHDj",
        "slug": "mchypixelnet",
        "name": "Hypixel Network",
        "ip": "mc.hypixel.net",
        "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp",
        "bannerUrl": "https://mcstat.org/media/banners/mchypixelnet.webp",
        "motdImageUrl": "https://mcstat.org/images/server-motd/mchypixelnet.svg",
        "currentPlayers": 48230,
        "maxPlayers": 200000,
        "isOnline": true,
        "country": "United States",
        "totalVotes": 12345,
        "uptime": 100,
        "trend": 3.4,
        "recentVotes": 412,
        "hotScore": 9821
      }
    ],
    "total": 1240,
    "sort": "hot"
  }
}

GET

/api/v1/servers/countries

Χώρες διακομιστή

Συγκεντρωτικό πλήθος διακομιστών ομαδοποιημένο ανά χώρα.

Παράδειγμα αιτήματος

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/countries"

Παράμετροι ερωτήματος

Δεν υπάρχουν παράμετροι

Παράδειγμα απάντησης

JSON

{
  "success": true,
  "data": {
    "countries": [
      {
        "country": "United States",
        "serverCount": 2840
      }
    ]
  }
}

GET

/api/v1/servers/versions

Εκδόσεις διακομιστή

Συγκεντρωτικό πλήθος διακομιστών ομαδοποιημένο ανά έκδοση Minecraft.

Παράδειγμα αιτήματος

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/servers/versions"

Παράμετροι ερωτήματος

Δεν υπάρχουν παράμετροι

Παράδειγμα απάντησης

JSON

{
  "success": true,
  "data": {
    "versions": [
      {
        "version": "Paper 1.21.11",
        "serverCount": 980
      }
    ]
  }
}

Τελικά σημεία παίκτη

Αναζητήστε προφίλ παικτών, περιόδους σύνδεσης, επίπεδα και ιστορικό.

GET

/api/v1/players

Λίστα παικτών

Σελιδωμένος δημόσιος κατάλογος προγράμματος αναπαραγωγής.

Παράδειγμα αιτήματος

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/players"

Παράμετροι ερωτήματος

Όνομα	Τύπος	απαιτείται	προεπιλογή	Περιγραφή
`page`	`integer`	Όχι	`1`	Αριθμός σελίδας, από 1.
`limit`	`integer`	Όχι	`—`	Στοιχεία ανά σελίδα.
`sort`	`string`	Όχι	`recent`	Σειρά ταξινόμησης.
`search`	`string`	Όχι	`—`	Ερώτημα ελεύθερου κειμένου.

Παράδειγμα απάντησης

JSON

{
  "success": true,
  "data": {
    "players": [
      {
        "id": "h6tC6lGfBEDulI8o",
        "minecraftUuid": "069a79f4-3e42-4b0c-8f1a-9c2b1d5e6f70",
        "mainNickname": "Notch",
        "skinUrl": "http://textures.minecraft.net/texture/98d4f27b450d…",
        "linkedSkinPngPath": "https://mcstat.org/media/skins/published/player-skin-notch.png",
        "skinModel": "classic",
        "country": "United States",
        "tierOverall": "HT1",
        "tierPoints": 9820,
        "tierRank": 12,
        "lastTierSyncAt": "2026-05-24T20:00:00Z",
        "createdAt": "2026-04-01T10:00:00Z",
        "totalPlayTime": 184320,
        "sessionCount": 412
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 24,
      "total": 1240,
      "totalPages": 52
    }
  }
}

GET

/api/v1/players/{id}

Λεπτομέρεια παίκτη

Προφίλ, πρόσφατες συνεδρίες, διακομιστές που παίχτηκαν, K/D, επιτεύγματα.

Παράδειγμα αιτήματος

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/players/069a79f4-44e9-4726-a5be-fca90e38aaf5"

Παράμετροι ερωτήματος

Όνομα	Τύπος	απαιτείται	προεπιλογή	Περιγραφή
`id`	`string`	Ναι	`—`	Αναγνωριστικό παίκτη, UUID ή ψευδώνυμο.

Παράδειγμα απάντησης

JSON

{
  "success": true,
  "data": {
    "player": {
      "id": "h6tC6lGfBEDulI8o",
      "minecraftUuid": "069a79f4-3e42-4b0c-8f1a-9c2b1d5e6f70",
      "mainNickname": "Notch",
      "nicknameHistory": [
        "Notch"
      ],
      "country": null,
      "skinModel": "classic",
      "skinUrl": "http://textures.minecraft.net/texture/98d4f27b450d…",
      "linkedSkinId": "Wi_n1dUvFqgJs0aP",
      "linkedSkinPngPath": "https://mcstat.org/media/skins/published/player-skin-notch.png",
      "linkedSkin": {
        "id": "Wi_n1dUvFqgJs0aP",
        "slug": "player-skin-notch",
        "pngPath": "https://mcstat.org/media/skins/published/player-skin-notch.png",
        "model": "classic",
        "name": "Notch's Skin"
      },
      "tierOverall": "MCStat Mythic",
      "tierPoints": 9820,
      "tierRank": 12,
      "createdAt": "2026-04-01T10:00:00Z",
      "updatedAt": "2026-05-24T22:00:00Z",
      "totalPlayTime": 184320,
      "sessionCount": 412,
      "rankScore": 9820,
      "rank": 12,
      "recentSessions": [
        {
          "id": "oWZiF6jq_UnEs7Y3",
          "server": {
            "id": "JS6o0w88QP6oZHDj",
            "slug": "mchypixelnet",
            "name": "Hypixel Network",
            "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp"
          },
          "joinedAt": "2026-05-24T20:00:00Z",
          "leftAt": "2026-05-24T21:00:00Z",
          "totalPlayTime": 3600
        }
      ],
      "serversPlayed": [
        {
          "id": "JS6o0w88QP6oZHDj",
          "slug": "mchypixelnet",
          "name": "Hypixel Network",
          "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp"
        }
      ],
      "latestStats": {
        "statsJson": {
          "kills": 18230,
          "deaths": 9850,
          "wins": 1240
        },
        "timestamp": "2026-05-24T21:00:00Z",
        "server": {
          "slug": "mchypixelnet",
          "name": "Hypixel Network"
        }
      },
      "statsHistory": [
        {
          "statsJson": {
            "kills": 18000,
            "deaths": 9700
          },
          "timestamp": "2026-05-24T20:00:00Z",
          "serverName": "Hypixel Network"
        }
      ],
      "kdRatio": 1.85,
      "totalKills": 18230,
      "totalDeaths": 9850,
      "totalWins": 1240,
      "activityData": [
        {
          "date": "2026-05-24",
          "count": 3
        }
      ],
      "achievements": {
        "earned": [
          {
            "id": "top10",
            "label": "Top 10",
            "labelTr": "İlk 10",
            "labelRu": "Топ 10",
            "icon": "medal"
          }
        ],
        "nextGoals": [
          {
            "id": "explorer_25",
            "label": "Globe Trotter",
            "labelTr": "Dünya Gezgini",
            "labelRu": "Путешественник",
            "icon": "plane"
          }
        ]
      },
      "votedServers": [
        {
          "serverId": "JS6o0w88QP6oZHDj",
          "serverSlug": "mchypixelnet",
          "serverName": "Hypixel Network",
          "serverIconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp",
          "votedAt": "2026-05-24T22:10:00Z"
        }
      ],
      "reviews": [
        {
          "id": "Rv8xKp2mNq7wTz1a",
          "rating": 5,
          "content": "Great server!",
          "createdAt": "2026-05-20T10:00:00Z",
          "server": {
            "id": "JS6o0w88QP6oZHDj",
            "slug": "mchypixelnet",
            "name": "Hypixel Network",
            "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp"
          }
        }
      ]
    }
  }
}

Αναζήτηση

Ενοποιημένη αναζήτηση σε διακομιστές και παίκτες.

GET

/api/v1/search

Παγκόσμια αναζήτηση

Αναζητήστε διακομιστές και παίκτες σε μία κλήση.

Παράδειγμα αιτήματος

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/search"

Παράμετροι ερωτήματος

Όνομα	Τύπος	απαιτείται	προεπιλογή	Περιγραφή
`q`	`string`	Ναι	`—`	Ερώτημα αναζήτησης (2–100 χαρακτήρες).
`type`	`string`	Όχι	`all`	Τύπος αποτελέσματος: all, servers, players.
`limit`	`integer`	Όχι	`10`	Στοιχεία ανά σελίδα.

Παράδειγμα απάντησης

JSON

{
  "success": true,
  "data": {
    "results": {
      "servers": [
        {
          "id": "JS6o0w88QP6oZHDj",
          "slug": "mchypixelnet",
          "name": "Hypixel Network",
          "iconUrl": "https://mcstat.org/images/server-icon/mchypixelnet.webp",
          "bannerUrl": "https://mcstat.org/media/banners/mchypixelnet.webp",
          "currentPlayers": 48230,
          "maxPlayers": 200000,
          "isOnline": true,
          "rating": 3.4
        }
      ],
      "players": [
        {
          "id": "h6JDPuUGKI3Mfw3m",
          "minecraftUuid": "de5f2979-1168-43d6-b5f3-e18f975a806b",
          "mainNickname": "Notch",
          "createdAt": "2026-04-01T10:00:00Z",
          "updatedAt": "2026-05-24T22:00:00Z"
        }
      ]
    },
    "query": "hypixel"
  }
}

Ζωντανά και παγκόσμια στατιστικά

Παγκόσμια δραστηριότητα σε πραγματικό χρόνο, αναλύσεις περιοχών και χωρών.

GET

/api/v1/live

Ζωντανά στατιστικά

Παγκόσμια online σύνολα, κορυφαίοι διακομιστές, πρόσφατη δραστηριότητα, ανάλυση περιοχής και χώρας.

Παράδειγμα αιτήματος

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/live"

Παράμετροι ερωτήματος

Δεν υπάρχουν παράμετροι

Παράδειγμα απάντησης

JSON

{
  "success": true,
  "data": {
    "stats": {
      "totalPlayers": 184320,
      "totalServers": 12480,
      "onlineServers": 9821,
      "newPlayersToday": 412,
      "peakToday": 202700,
      "generatedAt": "2026-05-24T22:00:00Z",
      "latestPingAt": "2026-05-24T21:59:48Z",
      "statsAgeSeconds": 18,
      "stale": false
    },
    "topServers": [
      {
        "id": "mchypixelnet",
        "name": "Hypixel Network",
        "players": 48230,
        "maxPlayers": 200000,
        "isOnline": true,
        "country": "United States",
        "trend": "up",
        "change": 240
      }
    ],
    "recentActivity": [
      {
        "type": "vote",
        "actor": "Notch",
        "target": "Hypixel Network",
        "time": "2026-05-24T22:00:00Z"
      }
    ],
    "regions": [
      {
        "id": "na",
        "name": "North America",
        "players": 80120,
        "servers": 4120
      }
    ],
    "countryPlayers": {
      "United States": 60120,
      "Germany": 18230
    }
  }
}

GET

/api/v1/live/history

Ζωντανή ιστορία

Ωριαία κουβάδες συνολικών διαδικτυακών παικτών τις τελευταίες 7 ημέρες.

Παράδειγμα αιτήματος

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/live/history"

Παράμετροι ερωτήματος

Δεν υπάρχουν παράμετροι

Παράδειγμα απάντησης

JSON

{
  "success": true,
  "data": {
    "history": [
      {
        "timestamp": "2026-05-23T22:00:00Z",
        "totalPlayers": 174200
      }
    ]
  }
}

Πίνακες κατάταξης

Οι κορυφαίοι παίκτες ταξινομούνται κατά περιόδους σύνδεσης, διακομιστές ή βαθμούς.

GET

/api/v1/leaderboards

Πίνακες κατάταξης

Κορυφαίοι παίκτες για την επιλεγμένη μέτρηση, περίοδο, επίπεδο και φίλτρα επιτευγμάτων.

Παράδειγμα αιτήματος

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/leaderboards"

Παράμετροι ερωτήματος

Όνομα	Τύπος	απαιτείται	προεπιλογή	Περιγραφή
`metric`	`string`	Όχι	`best`	Μέτρηση κατάταξης: best, sessions, servers.
`period`	`string`	Όχι	`all-time`	Χρονικό παράθυρο: 24h, 7d, 30d, 90d, all-time.
`page`	`integer`	Όχι	`1`	Αριθμός σελίδας, από 1.
`limit`	`integer`	Όχι	`20`	Στοιχεία ανά σελίδα.
`tier`	`string`	Όχι	`—`	Φίλτρο βαθμίδας.
`achievement`	`string`	Όχι	`—`	Φίλτρο επιτευγμάτων.
`search`	`string`	Όχι	`—`	Ερώτημα ελεύθερου κειμένου.

Παράδειγμα απάντησης

JSON

{
  "success": true,
  "data": {
    "leaderboard": {
      "metric": "best",
      "period": "all-time",
      "serverId": null,
      "generatedAt": "2026-05-24T22:00:00Z",
      "entries": [
        {
          "rank": 1,
          "player": {
            "id": "Vz2BaB2r6eC9TL_o",
            "mainNickname": "Notch",
            "minecraftUuid": "069a79f4-3e42-4b0c-8f1a-9c2b1d5e6f70",
            "tierOverall": "MCStat Mythic",
            "tierPoints": 224606,
            "tierRank": 1,
            "skinModel": "classic",
            "skinUrl": "http://textures.minecraft.net/texture/d71c3adef2ec…",
            "linkedSkinPngPath": "https://mcstat.org/media/skins/published/player-skin-notch.png"
          },
          "value": 224606,
          "formattedValue": "224,606 score"
        }
      ]
    },
    "pagination": {
      "page": 1,
      "limit": 24,
      "total": 1240,
      "totalPages": 52
    }
  }
}

Δέρματα & Κάπες

Αναζητήστε δέρματα και κάπες που έχουν ανέβει από την κοινότητα.

GET

/api/v1/skins

Λίστα δέρματα

Περιηγηθείτε στις μεταφορτώσεις δέρματος της κοινότητας με ταξινόμηση/φίλτρο.

Παράδειγμα αιτήματος

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/skins"

Παράμετροι ερωτήματος

Όνομα	Τύπος	απαιτείται	προεπιλογή	Περιγραφή
`page`	`integer`	Όχι	`1`	Αριθμός σελίδας, από 1.
`limit`	`integer`	Όχι	`24`	Στοιχεία ανά σελίδα.
`sort`	`string`	Όχι	`recent`	Σειρά ταξινόμησης.
`model`	`string`	Όχι	`—`	Μοντέλο δέρματος: κλασικό ή λεπτό.
`search`	`string`	Όχι	`—`	Ερώτημα ελεύθερου κειμένου.
`tag`	`string`	Όχι	`—`	Φιλτράρισμα ανά ετικέτα.
`owner`	`string`	Όχι	`—`	Φίλτρο ονόματος χρήστη κατόχου.

Παράδειγμα απάντησης

JSON

{
  "success": true,
  "data": {
    "skins": [
      {
        "id": "Wi_n1dUvFqgJs0aP",
        "slug": "cool-knight",
        "name": "Cool Knight",
        "model": "classic",
        "tags": [
          "medieval",
          "armor"
        ],
        "pngPath": "https://mcstat.org/media/skins/published/cool-knight.png",
        "viewCount": 3120,
        "likeCount": 124,
        "favoriteCount": 88,
        "downloadCount": 980,
        "usageCount": 12,
        "isFeatured": false,
        "createdAt": "2026-05-01T10:00:00Z",
        "ownerId": "Nf3kPq8sT2wVxJ7b",
        "owner": {
          "id": "Nf3kPq8sT2wVxJ7b",
          "username": "notch",
          "avatar": "https://mcstat.org/media/avatars/notch.webp"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 24,
      "total": 1240,
      "totalPages": 52
    }
  }
}

GET

/api/v1/skins/{slug}

Λεπτομέρεια δέρματος

Μεταδεδομένα πλήρους δέρματος συν το like/την αγαπημένη κατάσταση του θεατή.

Παράδειγμα αιτήματος

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/skins/hypixel-net"

Παράμετροι ερωτήματος

Όνομα	Τύπος	απαιτείται	προεπιλογή	Περιγραφή
`slug`	`string`	Ναι	`—`	Slug διακομιστή (από τη λίστα /servers).

Παράδειγμα απάντησης

JSON

{
  "success": true,
  "data": {
    "skin": {
      "id": "Wi_n1dUvFqgJs0aP",
      "slug": "cool-knight",
      "name": "Cool Knight",
      "description": "Custom medieval knight skin",
      "tags": [
        "medieval",
        "armor"
      ],
      "model": "classic",
      "pngPath": "https://mcstat.org/media/skins/published/cool-knight.png",
      "viewCount": 3120,
      "likeCount": 124,
      "favoriteCount": 88,
      "downloadCount": 980,
      "playersUsing": [
        {
          "id": "h6tC6lGfBEDulI8o",
          "mainNickname": "Notch",
          "minecraftUuid": "069a79f4-3e42-4b0c-8f1a-9c2b1d5e6f70",
          "skinUrl": "http://textures.minecraft.net/texture/98d4f27b450d…",
          "skinModel": "classic",
          "tierOverall": "MCStat Mythic",
          "linkedSkinPngPath": "https://mcstat.org/media/skins/published/cool-knight.png"
        }
      ],
      "playersUsingCount": 1,
      "owner": {
        "id": "Nf3kPq8sT2wVxJ7b",
        "username": "notch",
        "avatar": "https://mcstat.org/media/avatars/notch.webp"
      },
      "viewer": {
        "liked": false,
        "favorited": false,
        "isOwner": false
      }
    }
  }
}

GET

/api/v1/capes

Λίστα κάπες

Περιηγηθείτε στις μεταφορτώσεις ακρωτηρίων κοινότητας με ταξινόμηση/φίλτρο.

Παράδειγμα αιτήματος

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/capes"

Παράμετροι ερωτήματος

Όνομα	Τύπος	απαιτείται	προεπιλογή	Περιγραφή
`page`	`integer`	Όχι	`1`	Αριθμός σελίδας, από 1.
`limit`	`integer`	Όχι	`24`	Στοιχεία ανά σελίδα.
`sort`	`string`	Όχι	`recent`	Σειρά ταξινόμησης.
`search`	`string`	Όχι	`—`	Ερώτημα ελεύθερου κειμένου.
`tag`	`string`	Όχι	`—`	Φιλτράρισμα ανά ετικέτα.
`owner`	`string`	Όχι	`—`	Φίλτρο ονόματος χρήστη κατόχου.

Παράδειγμα απάντησης

JSON

{
  "success": true,
  "data": {
    "capes": [
      {
        "id": "De-jbTlj_PTnJJ5N",
        "slug": "royal-red",
        "name": "Royal Red",
        "tags": [
          "red",
          "royal"
        ],
        "pngPath": "https://mcstat.org/media/capes/published/royal-red.png",
        "viewCount": 210,
        "likeCount": 18,
        "favoriteCount": 6,
        "downloadCount": 44,
        "isFeatured": false,
        "createdAt": "2026-05-02T10:00:00Z",
        "ownerId": "Nf3kPq8sT2wVxJ7b",
        "owner": {
          "id": "Nf3kPq8sT2wVxJ7b",
          "username": "notch",
          "avatar": "https://mcstat.org/media/avatars/notch.webp"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 24,
      "total": 1240,
      "totalPages": 52
    }
  }
}

GET

/api/v1/capes/{slug}

Λεπτομέρειες κάπας

Πλήρη μεταδεδομένα κάπας και η κατάσταση like/αγαπημένων του θεατή.

Παράδειγμα αιτήματος

cURL

curl -X GET \
  -H "X-API-Key: mcs_your_key_here" \
  "https://mcstat.org/api/v1/capes/hypixel-net"

Παράμετροι ερωτήματος

Όνομα	Τύπος	απαιτείται	προεπιλογή	Περιγραφή
`slug`	`string`	Ναι	`—`	Slug διακομιστή (από τη λίστα /servers).

Παράδειγμα απάντησης

JSON

{
  "success": true,
  "data": {
    "cape": {
      "id": "De-jbTlj_PTnJJ5N",
      "slug": "royal-red",
      "name": "Royal Red",
      "description": "Deep red royal cape",
      "tags": [
        "red",
        "royal"
      ],
      "pngPath": "https://mcstat.org/media/capes/published/royal-red.png",
      "viewCount": 210,
      "likeCount": 18,
      "favoriteCount": 6,
      "downloadCount": 44,
      "playersUsing": [
        {
          "id": "h6tC6lGfBEDulI8o",
          "mainNickname": "Notch",
          "minecraftUuid": "069a79f4-3e42-4b0c-8f1a-9c2b1d5e6f70",
          "skinUrl": "http://textures.minecraft.net/texture/98d4f27b450d…",
          "skinModel": "classic",
          "linkedSkinPngPath": "https://mcstat.org/media/skins/published/player-skin-notch.png",
          "tierOverall": "MCStat Mythic"
        }
      ],
      "playersUsingCount": 1,
      "owner": {
        "id": "Nf3kPq8sT2wVxJ7b",
        "username": "notch",
        "avatar": "https://mcstat.org/media/avatars/notch.webp"
      },
      "viewer": {
        "liked": false,
        "favorited": false,
        "isOwner": false
      }
    }
  }
}