Wardog Servers API

Přehled

Základní URL je https://api.wardogservers.com. Každá odpověď je v JSON a čtení nevyžaduje API klíč.

Kompletní kontrakt je zveřejněný jako dokument OpenAPI 3.1 na https://api.wardogservers.com/openapi.json ↗. Rozhodující je tento dokument; tahle stránka je jeho čitelné shrnutí.

• Sběrač dat se zhruba jednou za minutu dotazuje prohlížeče serverů ve hře ve všech regionech. Aktuální interval uvádí každá odpověď v poli meta.refreshSeconds.
• Požadavky z prohlížeče se přijímají jen z wardogservers.com. Volej API ze svého serveru, bota nebo skriptu, ne z webové stránky na jiné doméně.
• Neznámé, duplicitní nebo chybně zapsané parametry dotazu se odmítnou s kódem 400, místo aby se ignorovaly, takže překlep skončí hlasitou chybou a nevrátí potichu všechno.

Rychlý start

Tři požadavky pokryjí většinu použití: aktuální souhrny, nejvytíženější servery podle filtru a jeden server podle ID instance.

# Aktuální souhrny
curl https://api.wardogservers.com/v1/stats

# Komunitní servery v západní Evropě s volnými sloty, nejvytíženější první
curl "https://api.wardogservers.com/v1/servers?region=eu-west&type=community&hideFull=true&limit=10"

# Jeden server podle ID instance
curl https://api.wardogservers.com/v1/servers/$ID

Zkrácená odpověď z /v1/stats vypadá takto:

{
  "data": {
    "serverCount": 3544,
    "playerCount": 252109,
    "officialServerCount": 2765,
    "communityServerCount": 779
  },
  "meta": {
    "fetchedAt": "2026-09-13T12:54:57.302Z",
    "snapshotId": "95635cb938811a34…",
    "refreshSeconds": 60,
    "stale": false,
    "requestedRegions": ["asia-east", "asia-southeast", "…"],
    "observedRegions": ["asia-east", "asia-west", "…"]
  }
}

Endpointy

Každý endpoint pro čtení přijímá GET a HEAD, respektuje If-None-Match a používá obálku odpovědi popsanou níže.

Filtrování seznamu serverů

Všechny parametry /v1/servers jsou nepovinné. Hodnoty rozlišují velká a malá písmena, kromě q.

Obálka odpovědi

Každá úspěšná odpověď obsahuje data a meta. Endpoint se seznamem přidává pagination; endpointy historie přidávají objekt history, který popisuje okno, skupinu, metriku a velikost intervalu.

Než čísla zobrazíš jako aktuální, zkontroluj meta.stale. Má hodnotu true, když se sběr dat zastavil nebo je snapshot starší než refreshSeconds plus 60 sekund. Zastaralé odpovědi se navíc posílají s Cache-Control: no-store a X-Data-Stale: true.

Objekt serveru

Toto je souhrnný tvar, který vrací /v1/servers a /v1/snapshot. /v1/servers/{id} vrací stejná pole a navíc attributes, build, level a cash.

{
  "id": "001ab36e-9985-4a9c-8dff-9dc137826dfe",
  "serverId": "756872",
  "serverIdUpdatedAt": "2026-09-13T11:14:32.995Z",
  "name": "Official #4",
  "nativeName": "f14859cce268",
  "type": "official",
  "region": "eu-south",
  "players": 100,
  "maxPlayers": 100,
  "reservedPlayers": 0,
  "passwordProtected": false,
  "serverNumber": 4,
  "map": { "variant": "Bakurani", "base": "Europe" },
  "mode": { "experience": "Bakurani_KOTH_01", "gameMode": "GM_Session_C", "modifiers": [] },
  "rulesets": ["standard"]
}

Historie

/v1/history/players vrací sloupcovou řadu: jedno pole časů začátku intervalů v unixových sekundách a jedno pole hodnot pro každý klíč skupiny, zarovnané podle indexu. Hodnota null je interval, ve kterém se nic nezaznamenalo, obvykle proto, že byl sběrač pozastavený. Zobraz mezeru, neinterpoluj.

Intervaly se zaznamenávají jednou za snapshot od chvíle, kdy se historie zapnula, bez zpětného doplnění. Minutové intervaly se uchovávají 7 dní, pětiminutové 90 dní a hodinové natrvalo.

GET /v1/history/players?window=24h&group=type

{
  "data": {
    "t": [1789217880, 1789217940, 1789218000, "…"],
    "series": {
      "official": [248112, 248390, null, "…"],
      "community": [3902, 3911, null, "…"]
    },
    "peak": { "official": ["…"], "community": ["…"] }
  },
  "history": {
    "window": "24h", "group": "type", "metric": "players",
    "step": 60, "from": 1789217880, "to": 1789304280, "since": 1789257600
  },
  "meta": { "…": "…" }
}

Pro metric=players nese odpověď i objekt peak s nejvyšším jednotlivým snapshotem v každém intervalu. Endpoint heatmapy průměruje metriku podle dne v týdnu a hodiny v UTC za posledních 28 celých dní, volitelně pro jeden region. Peaks vrací nejvyšší počet hráčů z jednoho snapshotu celkově i podle typu, za celou dobu i pro každý z posledních 30 dní v UTC.

Historie jednotlivých serverů

Historie jednotlivých serverů má jako klíč kód pro připojení, který na rozdíl od ID instance vydrží restarty i změny map. /v1/history/servers/{serverId} vrací zarovnaná pole: průměrný počet hráčů a nejvyšší jednotlivé měření, dokud byl server v seznamu, jeho limit hráčů, podíl měření v intervalu, ve kterých byl v seznamu (jeho doba online, 0 až 1), a mapu na konci intervalu, takže po sobě jdoucí hodnoty mapy dávají rotaci. Nahrávání začne, když se kód poprvé objeví, bez zpětného doplnění, a do té doby route odpovídá 404.

GET /v1/history/servers/756872?window=24h

{
  "data": {
    "server": {
      "serverId": "756872",
      "name": "Official #4",
      "type": "official",
      "region": "eu-south",
      "instanceId": "001ab36e-9985-4a9c-8dff-9dc137826dfe",
      "firstSeen": "2026-09-13T00:00:39.000Z",
      "lastSeen": "2026-09-14T11:53:22.000Z",
      "samples": 2132,
      "live": true
    },
    "t": [1789300800, 1789301100, 1789301400, "…"],
    "players": [100, 98, null, "…"],
    "peak": [100, 100, null, "…"],
    "capacity": [100, 100, null, "…"],
    "online": [1, 0.8, null, "…"],
    "map": ["Bakurani", "Bakurani", null, "…"]
  },
  "history": {
    "window": "24h", "step": 300,
    "from": 1789300800, "to": 1789387200, "since": 1789257600
  },
  "meta": { "…": "…" }
}

/v1/history/servers/{serverId}/events odvozuje log změn z po sobě jdoucích měření, nejnovější první: tracking_started, online, offline, restart (instance se změnila bez mezery), build (changelist), map (varianta, svět nebo obloha), modifiers a limits (rozsahy úrovní a peněz, heslo a limit hráčů). Každá událost nese at, kind a objekty before a after, které obsahují jen pole definující daný druh, a null tam, kde neexistuje dřívější nebo pozdější stav. limit přijímá 1 až 500 a výchozí hodnota je 100.

GET /v1/history/servers/756872/events?limit=3

{
  "data": {
    "server": { "serverId": "756872", "name": "Official #4", "…": "…" },
    "events": [
      {
        "at": "2026-09-14T12:40:30.000Z",
        "kind": "map",
        "before": { "map": "Madrid", "world": "Europe", "sky": "DayEarlyFog" },
        "after": { "map": "Detroit", "world": "Europe", "sky": "DayLateGray" }
      },
      {
        "at": "2026-09-14T09:12:04.000Z",
        "kind": "restart",
        "before": { "instanceId": "001ab36e-9985-4a9c-8dff-9dc137826dfe" },
        "after": { "instanceId": "7c1e0b52-3d9a-4e1f-9b6e-2f4c8a9d0e11" }
      },
      {
        "at": "2026-09-13T00:00:39.000Z",
        "kind": "tracking_started",
        "before": null,
        "after": { "instanceId": "…", "changelist": "501228", "map": "Bakurani", "…": "…" }
      }
    ]
  },
  "history": { "limit": 3, "since": 1789257600 },
  "meta": { "…": "…" }
}

/v1/history/servers vypisuje zaznamenané servery, naposledy viděné první. q odpovídá přesně kódu pro připojení, nebo bez ohledu na velikost písmen poslednímu známému názvu, takže najde i server, který je právě offline; živé servery už mají své serverId v /v1/servers.

Cachování a dotazování

Každá odpověď nese ETag. Pošli ho zpátky jako If-None-Match a nezměněný snapshot odpoví 304 bez těla, což nestojí skoro nic na žádné straně. Zamýšlený postup je dotaz jednou za minutu s If-None-Match.

const res = await fetch('https://api.wardogservers.com/v1/snapshot', {
  headers: lastEtag ? { 'if-none-match': lastEtag } : {}
});
if (res.status === 304) return; // Od posledního dotazu se nic nezměnilo
lastEtag = res.headers.get('etag');
const { data, meta } = await res.json();
if (meta.stale) console.warn('stale'); // Sběrač je pozadu; dál zobrazuj poslední známá data

Čerstvé odpovědi se na edge cachují 15 sekund, takže nápory stejných požadavků jsou levné. Pevný limit požadavků dnes neexistuje, ale dotazování častější než meta.refreshSeconds nemůže vrátit novější data a v budoucnu může být omezeno. Pokud potřebuješ celý seznam, stáhni jednou /v1/snapshot a filtruj lokálně, místo stránkování přes /v1/servers.

Chyby

Chyby jsou v JSON se stálým kódem a zprávou čitelnou pro lidi. Zpráva se může změnit; rozhoduj podle kódu.

{
  "error": {
    "code": "bad_request",
    "message": "An unsupported query parameter was supplied."
  }
}

Podmínky použití

API je zdarma pro komunitní projekty: boty na Discord, overlaye, dashboardy, výzkum. Kde data veřejně zobrazuješ, uveď Wardog Servers s odkazem a nevydávej je za oficiální data studia BULKHEAD nebo Team17.

API pro čtení je verzované pod /v1. V rámci verze můžou přibýt nová pole, takže počítej s klíči, které neznáš. Nekompatibilní změny vyjdou jako nová verze a nejdřív je oznámíme na této stránce.

Otázky, projekt, kterým se chceš pochlubit, nebo pole, které potřebuješ: Discord @xcausxn.