REST API

Dokumentasyon ng API

Isama ang live na Minecraft server, player, skin at data ng komunidad mula sa mcstat.org sa iyong sariling mga app, bot at dashboard.

Base URL

Ang lahat ng mga kahilingan sa API ay nagsisimula sa base URL na ito

https://mcstat.org/api/v1

Tingnan bilang Markdown

Raw na Markdown docs para sa mga AI, bot at tool

Mga API Key

Pamahalaan at subaybayan ang iyong mga API key

Gumawa, mag-rotate, at tumingin ng analytics para sa iyong mga API key sa dashboard.

Buksan ang API Key Dashboard

Palaruan ng API

Direktang subukan ang mga endpoint sa browser

Pagsusuri ng Bot

Ang playground na ito ay hindi nangangailangan ng API key; kinakailangan ang pagpapatunay ng tao upang mabawasan ang pag-abuso.

Endpoint

GET

/api/v1/servers

Mga Parameter ng Query

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

Humiling ng URL

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

Magpatakbo ng isang kahilingan upang makita ang tugon

Authentication

Ang lahat ng nakadokumentong pampublikong API endpoint ay nangangailangan ng API key. Ipadala ang iyong susi sa X-API-Key header.

Humiling ng header

Idagdag ang header na ito upang patotohanan

X-API-Key: mcs_your_key_here

O bilang parameter ng query

O ipasa bilang parameter ng query

?api_key=mcs_your_key_here

Mga limitasyon sa rate

Ang mga kahilingan ay pinatotohanan ng API key. Ang mga nawawala o di-wastong key ay nagbabalik ng HTTP 401; lumampas sa mga limitasyon ay nagbabalik ng HTTP 429.

Nang walang API key

Hindi pinapayagan

Gamit ang API key

Parehong moderate tier ngayon, na may attribution at priority queueing. Magiging available ang mas matataas na tier kasama ng mga bayad na plano.

Mga Header ng Hangganan ng Rate:Ang bawat tugon ay may kasamang Cache-Control header upang ligtas mong mai-cache ang mga resulta sa panig ng kliyente.

Format ng tugon

Ang bawat matagumpay na tugon ay JSON na may boolean at object. Ginagamit ng mga error ang parehong sobre na may : false.

Tagumpay na tugon

JSON

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

Sagot ng error

JSON

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

Mga pagkakamali

Ginagamit ang mga karaniwang HTTP status code. Mga karaniwang kaso:

Code	Ibig sabihin
`400`	Masamang kahilingan — di-wastong mga parameter
`401`	Hindi awtorisado — nawawala o di-wastong API key
`404`	Hindi nahanap — walang mapagkukunan
`429`	Masyadong maraming kahilingan — lumampas sa limitasyon sa rate
`500`	Error sa panloob na server — subukang muli sa ibang pagkakataon

Mga endpoint ng server

Mag-browse, mag-filter at suriin ang mga server ng Minecraft na sinusubaybayan ng mcstat.org.

GET

/api/v1/servers

Listahan ng mga server

Naka-paginate na listahan ng mga pampublikong server na may mga rich filter.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Pangalan	Uri	kinakailangan	default	Paglalarawan
`page`	`integer`	Hindi	`1`	Numero ng pahina, simula sa 1.
`limit`	`integer`	Hindi	`20`	Mga item bawat pahina.
`sort`	`string`	Hindi	`recent`	Pagbukud-bukurin ang pagkakasunud-sunod.
`search`	`string`	Hindi	`—`	Libreng-text na query.
`country`	`string`	Hindi	`—`	Filter ng pangalan ng bansang ISO.
`version`	`string`	Hindi	`—`	Filter ng bersyon ng Minecraft.
`tag`	`string`	Hindi	`—`	I-filter ayon sa tag.
`mode`	`string`	Hindi	`—`	Filter ng mode ng laro.
`minPlayers`	`integer`	Hindi	`—`	Minimum na kasalukuyang bilang ng manlalaro.
`maxPlayers`	`integer`	Hindi	`—`	Pinakamataas na kasalukuyang bilang ng manlalaro.
`minUptime`	`number`	Hindi	`—`	Pinakamababang porsyento ng uptime.
`minVotes`	`integer`	Hindi	`—`	Minimum na kabuuang bilang ng boto.
`minRating`	`number`	Hindi	`—`	Pinakamababang rating (1–5).
`onlineOnly`	`boolean`	Hindi	`—`	Isama lamang ang mga server na nag-uulat online.

Halimbawang tugon

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}

Detalye ng server

Buong profile ng server: kasaysayan ng mga istatistika, uptime, tsart ng pagboto, mga ranggo.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Pangalan	Uri	kinakailangan	default	Paglalarawan
`slug`	`string`	Oo	`—`	Server slug (mula sa /servers list).
`period`	`string`	Hindi	`24h`	Time window: 24h, 7d, 30d, 90d, all-time.

Halimbawang tugon

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

Mga botante ng server

Kamakailang mga botante (na-authenticate at anonymous) para sa ibinigay na server.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Pangalan	Uri	kinakailangan	default	Paglalarawan
`slug`	`string`	Oo	`—`	Server slug (mula sa /servers list).
`page`	`integer`	Hindi	`1`	Numero ng pahina, simula sa 1.
`limit`	`integer`	Hindi	`7`	Mga item bawat pahina.

Halimbawang tugon

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

Mga review ng server

Mga paginated na review at rating ng manlalaro para sa isang server.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Pangalan	Uri	kinakailangan	default	Paglalarawan
`slug`	`string`	Oo	`—`	Server slug (mula sa /servers list).
`page`	`integer`	Hindi	`1`	Numero ng pahina, simula sa 1.
`limit`	`integer`	Hindi	`5`	Mga item bawat pahina.

Halimbawang tugon

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

Mga update ng server

Mga aprubadong balita at update na post para sa isang server.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Pangalan	Uri	kinakailangan	default	Paglalarawan
`slug`	`string`	Oo	`—`	Server slug (mula sa /servers list).
`page`	`integer`	Hindi	`1`	Numero ng pahina, simula sa 1.
`limit`	`integer`	Hindi	`3`	Mga item bawat pahina.

Halimbawang tugon

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

Mga nangungunang server

Listahan ng trending na na-optimize para sa paggamit ng homepage/widget.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Pangalan	Uri	kinakailangan	default	Paglalarawan
`sort`	`string`	Hindi	`votes`	Pagbukud-bukurin ang pagkakasunud-sunod.
`limit`	`integer`	Hindi	`10`	Mga item bawat pahina.
`country`	`string`	Hindi	`—`	Filter ng pangalan ng bansang ISO.
`gameMode`	`string`	Hindi	`—`	Filter ng mode ng laro.

Halimbawang tugon

JSON

{
  "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

Mga bansa ng server

Pinagsama-samang bilang ng mga server na nakapangkat ayon sa bansa.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Walang mga parameter

Halimbawang tugon

JSON

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

GET

/api/v1/servers/versions

Mga bersyon ng server

Pinagsama-samang bilang ng mga server na nakapangkat ayon sa bersyon ng Minecraft.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Walang mga parameter

Halimbawang tugon

JSON

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

Mga endpoint ng manlalaro

Hanapin ang mga profile ng player, session, tier at history.

GET

/api/v1/players

Maglista ng mga manlalaro

Naka-page na direktoryo ng pampublikong manlalaro.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Pangalan	Uri	kinakailangan	default	Paglalarawan
`page`	`integer`	Hindi	`1`	Numero ng pahina, simula sa 1.
`limit`	`integer`	Hindi	`—`	Mga item bawat pahina.
`sort`	`string`	Hindi	`recent`	Pagbukud-bukurin ang pagkakasunud-sunod.
`search`	`string`	Hindi	`—`	Libreng-text na query.

Halimbawang tugon

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}

Detalye ng manlalaro

Profile, kamakailang mga session, mga server na nilalaro, K/D, mga tagumpay.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Pangalan	Uri	kinakailangan	default	Paglalarawan
`id`	`string`	Oo	`—`	Player id, UUID o palayaw.

Halimbawang tugon

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

Maghanap

Pinag-isang paghahanap sa mga server at manlalaro.

GET

/api/v1/search

Pandaigdigang paghahanap

Maghanap ng mga server at manlalaro sa isang tawag.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Pangalan	Uri	kinakailangan	default	Paglalarawan
`q`	`string`	Oo	`—`	Query sa paghahanap (2–100 character).
`type`	`string`	Hindi	`all`	Uri ng resulta: all, servers, players.
`limit`	`integer`	Hindi	`10`	Mga item bawat pahina.

Halimbawang tugon

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

Live at Global stats

Real-time na pandaigdigang aktibidad, mga breakdown ng rehiyon at bansa.

GET

/api/v1/live

Mga live na istatistika

Mga kabuuang online na pandaigdig, nangungunang mga server, kamakailang aktibidad, pagkasira ng rehiyon at bansa.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Walang mga parameter

Halimbawang tugon

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

Live na kasaysayan

Oras-oras na bucket ng kabuuang online na mga manlalaro sa nakalipas na 7 araw.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Walang mga parameter

Halimbawang tugon

JSON

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

Mga leaderboard

Nangungunang mga manlalaro na niraranggo ayon sa mga session, server o tier point.

GET

/api/v1/leaderboards

Mga leaderboard

Mga nangungunang manlalaro para sa napiling sukatan, panahon, tier at mga filter ng tagumpay.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Pangalan	Uri	kinakailangan	default	Paglalarawan
`metric`	`string`	Hindi	`best`	Sukat ng pagraranggo: best, sessions, servers.
`period`	`string`	Hindi	`all-time`	Time window: 24h, 7d, 30d, 90d, all-time.
`page`	`integer`	Hindi	`1`	Numero ng pahina, simula sa 1.
`limit`	`integer`	Hindi	`20`	Mga item bawat pahina.
`tier`	`string`	Hindi	`—`	Tier na filter.
`achievement`	`string`	Hindi	`—`	Filter ng tagumpay.
`search`	`string`	Hindi	`—`	Libreng-text na query.

Halimbawang tugon

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

Mga Balat at Cape

Maghanap ng mga skin at kapa na na-upload ng komunidad.

GET

/api/v1/skins

Listahan ng mga balat

Mag-browse ng mga skin upload ng komunidad gamit ang pag-uuri/filter.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Pangalan	Uri	kinakailangan	default	Paglalarawan
`page`	`integer`	Hindi	`1`	Numero ng pahina, simula sa 1.
`limit`	`integer`	Hindi	`24`	Mga item bawat pahina.
`sort`	`string`	Hindi	`recent`	Pagbukud-bukurin ang pagkakasunud-sunod.
`model`	`string`	Hindi	`—`	Modelo ng balat: classic o slim.
`search`	`string`	Hindi	`—`	Libreng-text na query.
`tag`	`string`	Hindi	`—`	I-filter ayon sa tag.
`owner`	`string`	Hindi	`—`	Filter ng username ng may-ari.

Halimbawang tugon

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}

Detalye ng balat

Buong skin metadata kasama ang gusto/paboritong estado ng manonood.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Pangalan	Uri	kinakailangan	default	Paglalarawan
`slug`	`string`	Oo	`—`	Server slug (mula sa /servers list).

Halimbawang tugon

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

Maglista ng mga kapa

Mag-browse ng mga pag-upload ng community cape gamit ang sort/filter.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Pangalan	Uri	kinakailangan	default	Paglalarawan
`page`	`integer`	Hindi	`1`	Numero ng pahina, simula sa 1.
`limit`	`integer`	Hindi	`24`	Mga item bawat pahina.
`sort`	`string`	Hindi	`recent`	Pagbukud-bukurin ang pagkakasunud-sunod.
`search`	`string`	Hindi	`—`	Libreng-text na query.
`tag`	`string`	Hindi	`—`	I-filter ayon sa tag.
`owner`	`string`	Hindi	`—`	Filter ng username ng may-ari.

Halimbawang tugon

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}

Detalye ng cape

Kumpletong metadata ng cape at ang like/favorite na status ng viewer.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Pangalan	Uri	kinakailangan	default	Paglalarawan
`slug`	`string`	Oo	`—`	Server slug (mula sa /servers list).

Halimbawang tugon

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,
      "owner": {
        "id": "Nf3kPq8sT2wVxJ7b",
        "username": "notch",
        "avatar": "https://mcstat.org/media/avatars/notch.webp"
      },
      "viewer": {
        "liked": false,
        "favorited": false,
        "isOwner": false
      }
    }
  }
}

MCSTATListahan ng Minecraft Server

REST API

Dokumentasyon ng API

Isama ang live na Minecraft server, player, skin at data ng komunidad mula sa mcstat.org sa iyong sariling mga app, bot at dashboard.

Base URL

Ang lahat ng mga kahilingan sa API ay nagsisimula sa base URL na ito

https://mcstat.org/api/v1

Tingnan bilang Markdown

Raw na Markdown docs para sa mga AI, bot at tool

Mga API Key

Pamahalaan at subaybayan ang iyong mga API key

Gumawa, mag-rotate, at tumingin ng analytics para sa iyong mga API key sa dashboard.

Buksan ang API Key Dashboard

Palaruan ng API

Direktang subukan ang mga endpoint sa browser

Pagsusuri ng Bot

Ang playground na ito ay hindi nangangailangan ng API key; kinakailangan ang pagpapatunay ng tao upang mabawasan ang pag-abuso.

Endpoint

GET

/api/v1/servers

Mga Parameter ng Query

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

Humiling ng URL

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

Magpatakbo ng isang kahilingan upang makita ang tugon

Authentication

Ang lahat ng nakadokumentong pampublikong API endpoint ay nangangailangan ng API key. Ipadala ang iyong susi sa X-API-Key header.

Humiling ng header

Idagdag ang header na ito upang patotohanan

X-API-Key: mcs_your_key_here

O bilang parameter ng query

O ipasa bilang parameter ng query

?api_key=mcs_your_key_here

Mga limitasyon sa rate

Ang mga kahilingan ay pinatotohanan ng API key. Ang mga nawawala o di-wastong key ay nagbabalik ng HTTP 401; lumampas sa mga limitasyon ay nagbabalik ng HTTP 429.

Nang walang API key

Hindi pinapayagan

Gamit ang API key

Parehong moderate tier ngayon, na may attribution at priority queueing. Magiging available ang mas matataas na tier kasama ng mga bayad na plano.

Mga Header ng Hangganan ng Rate:Ang bawat tugon ay may kasamang Cache-Control header upang ligtas mong mai-cache ang mga resulta sa panig ng kliyente.

Format ng tugon

Ang bawat matagumpay na tugon ay JSON na may boolean at object. Ginagamit ng mga error ang parehong sobre na may : false.

Tagumpay na tugon

JSON

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

Sagot ng error

JSON

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

Mga pagkakamali

Ginagamit ang mga karaniwang HTTP status code. Mga karaniwang kaso:

Code	Ibig sabihin
`400`	Masamang kahilingan — di-wastong mga parameter
`401`	Hindi awtorisado — nawawala o di-wastong API key
`404`	Hindi nahanap — walang mapagkukunan
`429`	Masyadong maraming kahilingan — lumampas sa limitasyon sa rate
`500`	Error sa panloob na server — subukang muli sa ibang pagkakataon

Mga endpoint ng server

Mag-browse, mag-filter at suriin ang mga server ng Minecraft na sinusubaybayan ng mcstat.org.

GET

/api/v1/servers

Listahan ng mga server

Naka-paginate na listahan ng mga pampublikong server na may mga rich filter.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Pangalan	Uri	kinakailangan	default	Paglalarawan
`page`	`integer`	Hindi	`1`	Numero ng pahina, simula sa 1.
`limit`	`integer`	Hindi	`20`	Mga item bawat pahina.
`sort`	`string`	Hindi	`recent`	Pagbukud-bukurin ang pagkakasunud-sunod.
`search`	`string`	Hindi	`—`	Libreng-text na query.
`country`	`string`	Hindi	`—`	Filter ng pangalan ng bansang ISO.
`version`	`string`	Hindi	`—`	Filter ng bersyon ng Minecraft.
`tag`	`string`	Hindi	`—`	I-filter ayon sa tag.
`mode`	`string`	Hindi	`—`	Filter ng mode ng laro.
`minPlayers`	`integer`	Hindi	`—`	Minimum na kasalukuyang bilang ng manlalaro.
`maxPlayers`	`integer`	Hindi	`—`	Pinakamataas na kasalukuyang bilang ng manlalaro.
`minUptime`	`number`	Hindi	`—`	Pinakamababang porsyento ng uptime.
`minVotes`	`integer`	Hindi	`—`	Minimum na kabuuang bilang ng boto.
`minRating`	`number`	Hindi	`—`	Pinakamababang rating (1–5).
`onlineOnly`	`boolean`	Hindi	`—`	Isama lamang ang mga server na nag-uulat online.

Halimbawang tugon

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}

Detalye ng server

Buong profile ng server: kasaysayan ng mga istatistika, uptime, tsart ng pagboto, mga ranggo.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Pangalan	Uri	kinakailangan	default	Paglalarawan
`slug`	`string`	Oo	`—`	Server slug (mula sa /servers list).
`period`	`string`	Hindi	`24h`	Time window: 24h, 7d, 30d, 90d, all-time.

Halimbawang tugon

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

Mga botante ng server

Kamakailang mga botante (na-authenticate at anonymous) para sa ibinigay na server.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Pangalan	Uri	kinakailangan	default	Paglalarawan
`slug`	`string`	Oo	`—`	Server slug (mula sa /servers list).
`page`	`integer`	Hindi	`1`	Numero ng pahina, simula sa 1.
`limit`	`integer`	Hindi	`7`	Mga item bawat pahina.

Halimbawang tugon

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

Mga review ng server

Mga paginated na review at rating ng manlalaro para sa isang server.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Pangalan	Uri	kinakailangan	default	Paglalarawan
`slug`	`string`	Oo	`—`	Server slug (mula sa /servers list).
`page`	`integer`	Hindi	`1`	Numero ng pahina, simula sa 1.
`limit`	`integer`	Hindi	`5`	Mga item bawat pahina.

Halimbawang tugon

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

Mga update ng server

Mga aprubadong balita at update na post para sa isang server.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Pangalan	Uri	kinakailangan	default	Paglalarawan
`slug`	`string`	Oo	`—`	Server slug (mula sa /servers list).
`page`	`integer`	Hindi	`1`	Numero ng pahina, simula sa 1.
`limit`	`integer`	Hindi	`3`	Mga item bawat pahina.

Halimbawang tugon

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

Mga nangungunang server

Listahan ng trending na na-optimize para sa paggamit ng homepage/widget.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Pangalan	Uri	kinakailangan	default	Paglalarawan
`sort`	`string`	Hindi	`votes`	Pagbukud-bukurin ang pagkakasunud-sunod.
`limit`	`integer`	Hindi	`10`	Mga item bawat pahina.
`country`	`string`	Hindi	`—`	Filter ng pangalan ng bansang ISO.
`gameMode`	`string`	Hindi	`—`	Filter ng mode ng laro.

Halimbawang tugon

JSON

{
  "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

Mga bansa ng server

Pinagsama-samang bilang ng mga server na nakapangkat ayon sa bansa.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Walang mga parameter

Halimbawang tugon

JSON

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

GET

/api/v1/servers/versions

Mga bersyon ng server

Pinagsama-samang bilang ng mga server na nakapangkat ayon sa bersyon ng Minecraft.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Walang mga parameter

Halimbawang tugon

JSON

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

Mga endpoint ng manlalaro

Hanapin ang mga profile ng player, session, tier at history.

GET

/api/v1/players

Maglista ng mga manlalaro

Naka-page na direktoryo ng pampublikong manlalaro.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Pangalan	Uri	kinakailangan	default	Paglalarawan
`page`	`integer`	Hindi	`1`	Numero ng pahina, simula sa 1.
`limit`	`integer`	Hindi	`—`	Mga item bawat pahina.
`sort`	`string`	Hindi	`recent`	Pagbukud-bukurin ang pagkakasunud-sunod.
`search`	`string`	Hindi	`—`	Libreng-text na query.

Halimbawang tugon

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}

Detalye ng manlalaro

Profile, kamakailang mga session, mga server na nilalaro, K/D, mga tagumpay.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Pangalan	Uri	kinakailangan	default	Paglalarawan
`id`	`string`	Oo	`—`	Player id, UUID o palayaw.

Halimbawang tugon

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

Maghanap

Pinag-isang paghahanap sa mga server at manlalaro.

GET

/api/v1/search

Pandaigdigang paghahanap

Maghanap ng mga server at manlalaro sa isang tawag.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Pangalan	Uri	kinakailangan	default	Paglalarawan
`q`	`string`	Oo	`—`	Query sa paghahanap (2–100 character).
`type`	`string`	Hindi	`all`	Uri ng resulta: all, servers, players.
`limit`	`integer`	Hindi	`10`	Mga item bawat pahina.

Halimbawang tugon

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

Live at Global stats

Real-time na pandaigdigang aktibidad, mga breakdown ng rehiyon at bansa.

GET

/api/v1/live

Mga live na istatistika

Mga kabuuang online na pandaigdig, nangungunang mga server, kamakailang aktibidad, pagkasira ng rehiyon at bansa.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Walang mga parameter

Halimbawang tugon

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

Live na kasaysayan

Oras-oras na bucket ng kabuuang online na mga manlalaro sa nakalipas na 7 araw.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Walang mga parameter

Halimbawang tugon

JSON

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

Mga leaderboard

Nangungunang mga manlalaro na niraranggo ayon sa mga session, server o tier point.

GET

/api/v1/leaderboards

Mga leaderboard

Mga nangungunang manlalaro para sa napiling sukatan, panahon, tier at mga filter ng tagumpay.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Pangalan	Uri	kinakailangan	default	Paglalarawan
`metric`	`string`	Hindi	`best`	Sukat ng pagraranggo: best, sessions, servers.
`period`	`string`	Hindi	`all-time`	Time window: 24h, 7d, 30d, 90d, all-time.
`page`	`integer`	Hindi	`1`	Numero ng pahina, simula sa 1.
`limit`	`integer`	Hindi	`20`	Mga item bawat pahina.
`tier`	`string`	Hindi	`—`	Tier na filter.
`achievement`	`string`	Hindi	`—`	Filter ng tagumpay.
`search`	`string`	Hindi	`—`	Libreng-text na query.

Halimbawang tugon

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

Mga Balat at Cape

Maghanap ng mga skin at kapa na na-upload ng komunidad.

GET

/api/v1/skins

Listahan ng mga balat

Mag-browse ng mga skin upload ng komunidad gamit ang pag-uuri/filter.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Pangalan	Uri	kinakailangan	default	Paglalarawan
`page`	`integer`	Hindi	`1`	Numero ng pahina, simula sa 1.
`limit`	`integer`	Hindi	`24`	Mga item bawat pahina.
`sort`	`string`	Hindi	`recent`	Pagbukud-bukurin ang pagkakasunud-sunod.
`model`	`string`	Hindi	`—`	Modelo ng balat: classic o slim.
`search`	`string`	Hindi	`—`	Libreng-text na query.
`tag`	`string`	Hindi	`—`	I-filter ayon sa tag.
`owner`	`string`	Hindi	`—`	Filter ng username ng may-ari.

Halimbawang tugon

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}

Detalye ng balat

Buong skin metadata kasama ang gusto/paboritong estado ng manonood.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Pangalan	Uri	kinakailangan	default	Paglalarawan
`slug`	`string`	Oo	`—`	Server slug (mula sa /servers list).

Halimbawang tugon

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

Maglista ng mga kapa

Mag-browse ng mga pag-upload ng community cape gamit ang sort/filter.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Pangalan	Uri	kinakailangan	default	Paglalarawan
`page`	`integer`	Hindi	`1`	Numero ng pahina, simula sa 1.
`limit`	`integer`	Hindi	`24`	Mga item bawat pahina.
`sort`	`string`	Hindi	`recent`	Pagbukud-bukurin ang pagkakasunud-sunod.
`search`	`string`	Hindi	`—`	Libreng-text na query.
`tag`	`string`	Hindi	`—`	I-filter ayon sa tag.
`owner`	`string`	Hindi	`—`	Filter ng username ng may-ari.

Halimbawang tugon

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}

Detalye ng cape

Kumpletong metadata ng cape at ang like/favorite na status ng viewer.

Halimbawa ng kahilingan

cURL

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

Mga Parameter ng Query

Pangalan	Uri	kinakailangan	default	Paglalarawan
`slug`	`string`	Oo	`—`	Server slug (mula sa /servers list).

Halimbawang tugon

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,
      "owner": {
        "id": "Nf3kPq8sT2wVxJ7b",
        "username": "notch",
        "avatar": "https://mcstat.org/media/avatars/notch.webp"
      },
      "viewer": {
        "liked": false,
        "favorited": false,
        "isOwner": false
      }
    }
  }
}