API pro vývojáře

Veřejné API vrací data ve formátu JSON a můžete ho volat z webu, Discord bota nebo pluginu. Endpointy s tokenem mají limit 600 dotazů za minutu na server.

API token najdete v administraci serveru v kartě Votifier a API. Nikomu ho neposílejte a nedávejte ho do kódu webové stránky, kterou vidí návštěvníci. Kdo token zná, vidí seznam hlasujících.

Informace o serveru

Nevyžaduje token.

GET https://mcservery.cz/api/v1/server?slug=vas-server

{
  "name": "Váš server",
  "slug": "vas-server",
  "url": "https://mcservery.cz/server/vas-server",
  "address": "play.vasserver.cz",
  "bedrock": { "host": "bedrock.vasserver.cz", "port": 19132 },
  "online": true,
  "players": 42,
  "max_players": 200,
  "version": "Paper 1.21.4",
  "votes_month": 1250,
  "last_ping": "2026-09-25T20:15:00+02:00"
}

Hlasoval hráč?

Vrátí, jestli hráč hlasoval za posledních 24 hodin a kdy může znovu.

GET https://mcservery.cz/api/v1/check?token=TOKEN&nickname=Steve

{
  "nickname": "Steve",
  "voted_24h": true,
  "last_vote": "2026-09-25T18:02:11+02:00",
  "next_vote": "2026-09-25T20:02:11+02:00"
}

Seznam hlasů

Posledních až 500 hlasů. Parametr since (unixový čas) vrátí jen novější hlasy, takže se hodí na pravidelné stahování.

GET https://mcservery.cz/api/v1/votes?token=TOKEN&since=1790000000

{
  "votes": [
    { "nickname": "Steve", "country": "CZ", "delivered": true,
      "time": "2026-09-25T18:02:11+02:00", "unix": 1790265731 }
  ]
}

Obrázky

Tyto adresy vrací PNG obrázek a můžete je vložit kamkoliv:

https://mcservery.cz/api/badge/vas-server.png    štítek 468 × 60 px
https://mcservery.cz/api/og/vas-server.png       náhled 1200 × 630 px

Příklad: JavaScript

const res = await fetch('https://mcservery.cz/api/v1/server?slug=vas-server');
const s = await res.json();
console.log(`${s.name}: ${s.players}/${s.max_players} hráčů online`);

Příklad: PHP

$token = 'VAS_TOKEN'; // držte na serveru, ne v HTML
$url = 'https://mcservery.cz/api/v1/check?token=' . $token . '&nickname=' . urlencode($nick);
$data = json_decode(file_get_contents($url), true);
if ($data['voted_24h']) {
    // hráč hlasoval – dejte mu bonus
}

Chybové kódy

• 401 invalid_token – token je špatně nebo byl vygenerován nový.
• 400 invalid_nickname – nick nemá 3–16 povolených znaků.
• 404 not_found – server s tímto slugem neexistuje.
• 429 rate_limited – příliš mnoho dotazů, zpomalte.