REST API

API-dokumentaatio

Integroi live-Minecraft-palvelin-, pelaaja-, ulko- ja yhteisötiedot mcstat.orgista omiin sovelluksiisi, botteihisi ja kojelautaihisi.

Perus-URL-osoite

Kaikki API-pyynnöt alkavat tällä perus-URL-osoitteella

https://mcstat.org/api/v1

Näytä Markdownina

Raaka Markdown-dokumentaatio tekoälyille, boteille ja työkaluille

API-avaimet

Hallitse ja valvo API-avaimia

Luo, kierrä ja tarkastele API-avaimien analytiikkaa kojelaudassa.

Avaa API Key Dashboard

API-testausympäristö

Testaa päätepisteitä suoraan selaimessa

Bottitarkistus

Tämä hiekkalaatikko ei vaadi API-avainta; väärinkäytön vähentämiseksi vaaditaan ihmisen vahvistus.

Päätepiste

GET

/api/v1/servers

Kyselyparametrit

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

Pyydä URL-osoite

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

Suorita pyyntö nähdäksesi vastauksen

Todennus

Kaikki dokumentoidut julkiset API-päätepisteet vaativat API-avaimen. Lähetä avaimesi X-API-Key-otsikossa.

Pyynnön otsikko

Lisää tämä otsikko todentaaksesi

X-API-Key: mcs_your_key_here

Tai kyselyparametrina

Tai välitä kyselyparametrina

?api_key=mcs_your_key_here

Hintarajoitukset

Pyynnöt todennetaan API-avaimella. Puuttuva tai virheellinen avain palauttaa HTTP 401:n, käytöstä poistettu avain palauttaa HTTP 403:n ja ylitetty raja palauttaa HTTP 429:n.

Ilman API-avainta

Ei sallittu

API-avaimella

Oletusarvoisesti 60 pyyntöä minuutissa, 1 000 päivässä ja 30 000 kuukaudessa. Rajan ylittäminen palauttaa HTTP 429:n, jossa on X-RateLimit-*-otsikot, jotka näyttävät rajasi, ja Retry-After, joka kertoo, kun ikkuna nollautuu. Suuremmat rajat voidaan myöntää per avain pyynnöstä.

Rate Limit otsikot:429 vastaus sisältää X-RateLimit-Limit-Minute, X-RateLimit-Limit-Day, X-RateLimit-Remaining-Day, X-RateLimit-Limit-Month, X-RateLimit-Remaining-Month ja Retry-After. Onnistuneet vastaukset sisältävät Cache-Control-otsikon, jotta voit tallentaa tulokset turvallisesti välimuistiin asiakaspuolella.

Vastauksen muoto

Jokainen onnistunut vastaus on JSON, jossa on boolean ja -objekti. Virheissä käytetään samaa kirjekuorta, jossa on : false.

Menestysvastaus

JSON

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

Virhevastaus

JSON

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

Virheet

Käytetään tavallisia HTTP-tilakoodeja. Yleisiä tapauksia:

Koodi	Merkitys
`400`	Virheellinen pyyntö – virheelliset parametrit
`401`	Luvaton – puuttuva tai virheellinen API-avain
`403`	Kielletty — API-avain poistettu käytöstä
`404`	Ei löydy – resurssia ei ole olemassa
`429`	Liian monta pyyntöä – määräraja ylitetty
`500`	Sisäinen palvelinvirhe – yritä myöhemmin uudelleen

Palvelimen päätepisteet

Selaa, suodata ja tarkasta mcstat.orgin seuraamia Minecraft-palvelimia.

GET

/api/v1/servers

Listaa palvelimet

Sivutettu luettelo julkisista palvelimista, joissa on monipuoliset suodattimet.

Esimerkkipyyntö

cURL

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

Kyselyparametrit

Nimi	Kirjoita	tarvitaan	oletuksena	Kuvaus
`page`	`integer`	Ei	`1`	Sivunumero alkaen 1.
`limit`	`integer`	Ei	`20`	Kohteita per sivu.
`sort`	`string`	Ei	`recent`	Lajittelujärjestys.
`search`	`string`	Ei	`—`	Vapaatekstikysely.
`country`	`string`	Ei	`—`	ISO-maan nimisuodatin.
`version`	`string`	Ei	`—`	Minecraft-version suodatin.
`tag`	`string`	Ei	`—`	Suodata tunnisteen mukaan.
`mode`	`string`	Ei	`—`	Pelitilan suodatin.
`minPlayers`	`integer`	Ei	`—`	Nykyinen vähimmäispelaajamäärä.
`maxPlayers`	`integer`	Ei	`—`	Suurin nykyinen pelaajamäärä.
`minUptime`	`number`	Ei	`—`	Minimi käyttöaikaprosentti.
`minVotes`	`integer`	Ei	`—`	Kokonaisäänten vähimmäismäärä.
`minRating`	`number`	Ei	`—`	Minimiarvosana (1–5).
`onlineOnly`	`boolean`	Ei	`—`	Sisällytä vain verkossa raportoivat palvelimet.

Esimerkkivastaus

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}

Palvelimen yksityiskohdat

Täysi palvelinprofiili: tilastohistoria, käytettävyys, äänestyskaavio, sijoitukset.

Esimerkkipyyntö

cURL

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

Kyselyparametrit

Nimi	Kirjoita	tarvitaan	oletuksena	Kuvaus
`slug`	`string`	Kyllä	`—`	Palvelimen etana (/palvelimet-luettelosta).
`period`	`string`	Ei	`24h`	Aikaikkuna: 24h, 7d, 30d, 90d, all-time.

Esimerkkivastaus

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

Palvelimen äänestäjät

Viimeaikaiset äänestäjät (todennetut ja anonyymit) tietylle palvelimelle.

Esimerkkipyyntö

cURL

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

Kyselyparametrit

Nimi	Kirjoita	tarvitaan	oletuksena	Kuvaus
`slug`	`string`	Kyllä	`—`	Palvelimen etana (/palvelimet-luettelosta).
`page`	`integer`	Ei	`1`	Sivunumero alkaen 1.
`limit`	`integer`	Ei	`7`	Kohteita per sivu.

Esimerkkivastaus

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

Palvelimen arvostelut

Sivutetut pelaajien arvostelut ja arviot palvelimelle.

Esimerkkipyyntö

cURL

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

Kyselyparametrit

Nimi	Kirjoita	tarvitaan	oletuksena	Kuvaus
`slug`	`string`	Kyllä	`—`	Palvelimen etana (/palvelimet-luettelosta).
`page`	`integer`	Ei	`1`	Sivunumero alkaen 1.
`limit`	`integer`	Ei	`5`	Kohteita per sivu.

Esimerkkivastaus

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

Palvelimen päivitykset

Hyväksytyt uutis- ja päivitysjulkaisut palvelimelle.

Esimerkkipyyntö

cURL

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

Kyselyparametrit

Nimi	Kirjoita	tarvitaan	oletuksena	Kuvaus
`slug`	`string`	Kyllä	`—`	Palvelimen etana (/palvelimet-luettelosta).
`page`	`integer`	Ei	`1`	Sivunumero alkaen 1.
`limit`	`integer`	Ei	`3`	Kohteita per sivu.

Esimerkkivastaus

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

Huippupalvelimet

Trendikäs luettelo optimoitu etusivun/widgetin käyttöön.

Esimerkkipyyntö

cURL

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

Kyselyparametrit

Nimi	Kirjoita	tarvitaan	oletuksena	Kuvaus
`sort`	`string`	Ei	`votes`	Lajittelujärjestys.
`limit`	`integer`	Ei	`10`	Kohteita per sivu.
`country`	`string`	Ei	`—`	ISO-maan nimisuodatin.
`gameMode`	`string`	Ei	`—`	Pelitilan suodatin.

Esimerkkivastaus

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

Palvelinmaat

Maittain ryhmitelty palvelimien kokonaismäärä.

Esimerkkipyyntö

cURL

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

Kyselyparametrit

Ei parametreja

Esimerkkivastaus

JSON

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

GET

/api/v1/servers/versions

Palvelinversiot

Palvelinten kokonaismäärä ryhmiteltynä Minecraft-version mukaan.

Esimerkkipyyntö

cURL

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

Kyselyparametrit

Ei parametreja

Esimerkkivastaus

JSON

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

Pelaajan päätepisteet

Katso pelaajaprofiilit, istunnot, tasot ja historia.

GET

/api/v1/players

Listaa pelaajat

Sivutettu julkinen pelaajahakemisto.

Esimerkkipyyntö

cURL

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

Kyselyparametrit

Nimi	Kirjoita	tarvitaan	oletuksena	Kuvaus
`page`	`integer`	Ei	`1`	Sivunumero alkaen 1.
`limit`	`integer`	Ei	`—`	Kohteita per sivu.
`sort`	`string`	Ei	`recent`	Lajittelujärjestys.
`search`	`string`	Ei	`—`	Vapaatekstikysely.

Esimerkkivastaus

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}

Pelaajan yksityiskohdat

Profiili, viimeisimmät istunnot, pelatut palvelimet, K/D, saavutukset.

Esimerkkipyyntö

cURL

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

Kyselyparametrit

Nimi	Kirjoita	tarvitaan	oletuksena	Kuvaus
`id`	`string`	Kyllä	`—`	Pelaajatunnus, UUID tai lempinimi.

Esimerkkivastaus

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

Etsi

Yhtenäinen haku palvelimista ja pelaajista.

GET

/api/v1/search

Globaali haku

Hae palvelimia ja pelaajia yhdellä kutsulla.

Esimerkkipyyntö

cURL

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

Kyselyparametrit

Nimi	Kirjoita	tarvitaan	oletuksena	Kuvaus
`q`	`string`	Kyllä	`—`	Hakukysely (2–100 merkkiä).
`type`	`string`	Ei	`all`	Tulostyyppi: all, servers, players.
`limit`	`integer`	Ei	`10`	Kohteita per sivu.

Esimerkkivastaus

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 ja globaalit tilastot

Reaaliaikainen globaali toiminta, alue- ja maaerittelyt.

GET

/api/v1/live

Live-tilastot

Globaalit online-summat, suosituimmat palvelimet, viimeaikainen toiminta, alue- ja maaerittely.

Esimerkkipyyntö

cURL

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

Kyselyparametrit

Ei parametreja

Esimerkkivastaus

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 historia

Kaikkien online-pelaajien tuntiryhmät viimeisen 7 päivän ajalta.

Esimerkkipyyntö

cURL

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

Kyselyparametrit

Ei parametreja

Esimerkkivastaus

JSON

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

Tulostaulukot

Parhaat pelaajat istuntojen, palvelimien tai tasopisteiden mukaan.

GET

/api/v1/leaderboards

Tulostaulukot

Parhaat pelaajat valituilla mittareilla, ajanjaksoilla, tasoilla ja saavutussuodattimilla.

Esimerkkipyyntö

cURL

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

Kyselyparametrit

Nimi	Kirjoita	tarvitaan	oletuksena	Kuvaus
`metric`	`string`	Ei	`best`	Sijoitusmittari: best, sessions, servers.
`period`	`string`	Ei	`all-time`	Aikaikkuna: 24h, 7d, 30d, 90d, all-time.
`page`	`integer`	Ei	`1`	Sivunumero alkaen 1.
`limit`	`integer`	Ei	`20`	Kohteita per sivu.
`tier`	`string`	Ei	`—`	Tasosuodatin.
`achievement`	`string`	Ei	`—`	Saavutussuodatin.
`search`	`string`	Ei	`—`	Vapaatekstikysely.

Esimerkkivastaus

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

Skins & Cape

Hae yhteisön lataamia skinejä ja viitaja.

GET

/api/v1/skins

Listaa skinit

Selaa yhteisön skin-latauksia lajittelun/suodattimen avulla.

Esimerkkipyyntö

cURL

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

Kyselyparametrit

Nimi	Kirjoita	tarvitaan	oletuksena	Kuvaus
`page`	`integer`	Ei	`1`	Sivunumero alkaen 1.
`limit`	`integer`	Ei	`24`	Kohteita per sivu.
`sort`	`string`	Ei	`recent`	Lajittelujärjestys.
`model`	`string`	Ei	`—`	Ihomalli: klassinen tai ohut.
`search`	`string`	Ei	`—`	Vapaatekstikysely.
`tag`	`string`	Ei	`—`	Suodata tunnisteen mukaan.
`owner`	`string`	Ei	`—`	Omistajan käyttäjänimisuodatin.

Esimerkkivastaus

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}

Ihon yksityiskohta

Koko ihon metatiedot sekä katsojan tykkäys/suosikkitila.

Esimerkkipyyntö

cURL

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

Kyselyparametrit

Nimi	Kirjoita	tarvitaan	oletuksena	Kuvaus
`slug`	`string`	Kyllä	`—`	Palvelimen etana (/palvelimet-luettelosta).

Esimerkkivastaus

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

Listaa viitat

Selaa yhteisön cape -latauksia lajittelun/suodattimen avulla.

Esimerkkipyyntö

cURL

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

Kyselyparametrit

Nimi	Kirjoita	tarvitaan	oletuksena	Kuvaus
`page`	`integer`	Ei	`1`	Sivunumero alkaen 1.
`limit`	`integer`	Ei	`24`	Kohteita per sivu.
`sort`	`string`	Ei	`recent`	Lajittelujärjestys.
`search`	`string`	Ei	`—`	Vapaatekstikysely.
`tag`	`string`	Ei	`—`	Suodata tunnisteen mukaan.
`owner`	`string`	Ei	`—`	Omistajan käyttäjänimisuodatin.

Esimerkkivastaus

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}

Viitan tiedot

Viitan täydelliset metatiedot sekä katsojan tykkäys-/suosikkitila.

Esimerkkipyyntö

cURL

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

Kyselyparametrit

Nimi	Kirjoita	tarvitaan	oletuksena	Kuvaus
`slug`	`string`	Kyllä	`—`	Palvelimen etana (/palvelimet-luettelosta).

Esimerkkivastaus

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