REST API

תיעוד API

שלב נתונים חיים של שרת Minecraft, נגן, עור וקהילה מ-mcstat.org לתוך האפליקציות, הבוטים והדשבורדים שלך.

כתובת האתר הבסיסית

כל בקשות ה-API מתחילות בכתובת האתר הבסיסית הזו

https://mcstat.org/api/v1

הצג כ-Markdown

תיעוד Markdown גולמי עבור בינה מלאכותית, בוטים וכלים

מפתחות API

נהל וניטור מפתחות ה-API שלך

צור, סובב והצג ניתוחים עבור מפתחות ה-API שלך בלוח המחוונים.

פתח את לוח המחוונים של מפתח API

מגרש משחקים של API

בדוק נקודות קצה ישירות בדפדפן

בדיקת בוט

סביבת הניסוי הזו אינה דורשת מפתח 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

בקש כתובת אתר

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 ו-Research-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`	כן	`—`	שבלול שרת (מרשימת /שרתים).
`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`	כן	`—`	שבלול שרת (מרשימת /שרתים).
`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`	כן	`—`	שבלול שרת (מרשימת /שרתים).
`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`	כן	`—`	שבלול שרת (מרשימת /שרתים).
`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

סטטיסטיקה חיה

סכומים מקוונים גלובליים, שרתים מובילים, פעילות אחרונה, פירוט אזור ומדינה.

בקשה לדוגמה

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}

פירוט העור

מטא נתונים מלאים של העור בתוספת מצב 'אהבתי'/מועדף של הצופה.

בקשה לדוגמה

cURL

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

פרמטרי שאילתה

שם	הקלד	נדרש	ברירת מחדל	תיאור
`slug`	`string`	כן	`—`	שבלול שרת (מרשימת /שרתים).

תגובה לדוגמה

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}

פרטי גלימה

מטא-נתונים מלאים של הגלימה בתוספת מצב הלייק/מועדפים של הצופה.

בקשה לדוגמה

cURL

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

פרמטרי שאילתה

שם	הקלד	נדרש	ברירת מחדל	תיאור
`slug`	`string`	כן	`—`	שבלול שרת (מרשימת /שרתים).

תגובה לדוגמה

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
      }
    }
  }
}