API Wardog Servers

Vue d’ensemble

L’URL de base est https://api.wardogservers.com. Toutes les réponses sont en JSON et les lectures ne demandent aucune clé d’API.

Le contrat complet est publié sous forme de document OpenAPI 3.1 à l’adresse https://api.wardogservers.com/openapi.json ↗. Ce document fait foi ; cette page en est le résumé lisible.

• Le collecteur interroge le navigateur de serveurs du jeu dans chaque région environ une fois par minute. L’intervalle actuel est indiqué dans chaque réponse, dans meta.refreshSeconds.
• Les requêtes provenant d’un navigateur ne sont acceptées que depuis wardogservers.com. Appelle l’API depuis ton propre serveur, bot ou script, pas depuis une page web sur un autre domaine.
• Les paramètres de requête inconnus, en double ou mal formés sont rejetés avec une erreur 400 au lieu d’être ignorés : une faute de frappe échoue donc de façon visible au lieu de tout renvoyer en silence.

Démarrage rapide

Trois requêtes couvrent la plupart des usages : les totaux actuels, les serveurs les plus peuplés qui correspondent à un filtre, et un serveur précis par son id d’instance.

# Totaux actuels
curl https://api.wardogservers.com/v1/stats

# Serveurs communautaires en Europe de l’Ouest avec de la place, les plus peuplés d’abord
curl "https://api.wardogservers.com/v1/servers?region=eu-west&type=community&hideFull=true&limit=10"

# Un serveur par id d’instance
curl https://api.wardogservers.com/v1/servers/$ID

Une réponse abrégée de /v1/stats ressemble à ceci :

{
  "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", "…"]
  }
}

Endpoints

Chaque endpoint de lecture accepte GET et HEAD, respecte If-None-Match et utilise l’enveloppe de réponse décrite plus bas.

Filtrer la liste des serveurs

Tous les paramètres de /v1/servers sont facultatifs. Les valeurs sont sensibles à la casse, sauf q.

Enveloppe de réponse

Chaque réponse réussie contient data et meta. L’endpoint de liste ajoute pagination ; les endpoints d’historique ajoutent un objet history qui décrit la période, le groupe, la métrique et la taille des intervalles.

Vérifie meta.stale avant de présenter des chiffres comme actuels. Il vaut true quand la collecte est en pause ou que l’instantané date de plus de refreshSeconds plus 60 secondes. Les réponses périmées sont aussi envoyées avec Cache-Control: no-store et X-Data-Stale: true.

L’objet serveur

Voici la forme résumée renvoyée par /v1/servers et /v1/snapshot. /v1/servers/{id} renvoie les mêmes champs, plus attributes, build, level et 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"]
}

Historique

/v1/history/players renvoie une série en colonnes : un tableau des débuts d’intervalle en secondes Unix et un tableau de valeurs par clé de groupe, alignés par index. Une valeur null correspond à un intervalle où rien n’a été enregistré, généralement parce que le collecteur était en pause. Affiche un trou ; n’interpole pas.

Les intervalles sont enregistrés une fois par instantané depuis l’activation de l’historique, sans rattrapage des données antérieures. Les intervalles d’une minute sont conservés 7 jours, ceux de cinq minutes 90 jours et les intervalles horaires indéfiniment.

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": { "…": "…" }
}

Pour metric=players, la réponse contient aussi un objet peak avec le plus haut instantané de chaque intervalle. L’endpoint heatmap fait la moyenne d’une métrique par jour de la semaine et heure UTC sur les 28 derniers jours complets, éventuellement pour une seule région. Peaks renvoie le plus haut nombre de joueurs relevé sur un seul instantané, au total et par type, depuis toujours et pour chacun des 30 derniers jours UTC.

Historique par serveur

L’historique par serveur est indexé par le code de connexion, qui persiste après les redémarrages et les changements de carte, contrairement à l’id d’instance. /v1/history/servers/{serverId} renvoie des tableaux alignés : la moyenne des joueurs et le plus haut relevé pendant que le serveur était listé, sa limite de joueurs, la part des relevés de l’intervalle qui le listaient (sa disponibilité, de 0 à 1) et la carte à la fin de l’intervalle ; les valeurs de carte successives donnent ainsi la rotation. L’enregistrement commence la première fois qu’un code est vu, sans rattrapage des données antérieures, et la route répond 404 jusque-là.

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 déduit un journal des changements à partir des relevés consécutifs, du plus récent au plus ancien : tracking_started, online, offline, restart (l’instance a changé sans interruption), build (changelist), map (variante, monde ou ciel), modifiers et limits (plages de niveau et d’argent, mot de passe et limite de joueurs). Chaque événement contient at, kind, et des objets before et after qui ne contiennent que les champs propres à ce type, null quand il n’y a pas d’état antérieur ou ultérieur. limit accepte de 1 à 500 et vaut 100 par défaut.

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 liste les serveurs enregistrés, du plus récemment vu au plus ancien. q correspond exactement à un code de connexion, ou à un dernier nom connu sans tenir compte de la casse : il trouve donc un serveur hors ligne en ce moment ; les serveurs en ligne ont déjà leur serverId dans /v1/servers.

Cache et fréquence d’interrogation

Chaque réponse contient un ETag. Renvoie-le dans If-None-Match : si l’instantané n’a pas changé, la réponse est un 304 sans corps, qui ne coûte presque rien de part et d’autre. Un relevé par minute avec If-None-Match est l’usage prévu.

const res = await fetch('https://api.wardogservers.com/v1/snapshot', {
  headers: lastEtag ? { 'if-none-match': lastEtag } : {}
});
if (res.status === 304) return; // Rien n’a changé depuis le dernier relevé
lastEtag = res.headers.get('etag');
const { data, meta } = await res.json();
if (meta.stale) console.warn('stale'); // Le collecteur est en retard ; continue d’afficher les dernières données connues

Les réponses récentes sont mises en cache en périphérie du réseau pendant 15 secondes, donc les rafales de requêtes identiques coûtent peu. Il n’y a pas de limite de débit stricte aujourd’hui, mais interroger l’API plus souvent que meta.refreshSeconds ne peut pas renvoyer de données plus récentes et pourra être bridé à l’avenir. Si tu as besoin de toute la liste, récupère /v1/snapshot une fois et filtre en local au lieu de parcourir /v1/servers page par page.

Erreurs

Les erreurs sont en JSON avec un code stable et un message lisible. Le message peut changer ; base-toi sur le code.

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

Conditions d’utilisation

L’API est gratuite pour les projets communautaires : bots Discord, overlays, tableaux de bord, recherche. Cite Wardog Servers avec un lien là où tu affiches les données publiquement, et ne les présente pas comme des données officielles de BULKHEAD ou de Team17.

L’API de lecture est versionnée sous /v1. De nouveaux champs peuvent être ajoutés au sein d’une version : accepte donc les clés que tu ne reconnais pas. Les changements incompatibles sortiront dans une nouvelle version et seront d’abord annoncés sur cette page.

Des questions, un projet à montrer ou un champ dont tu as besoin : Discord @xcausxn.