Öffentliche API
Liste Server auf, lies Live-Spielerzahlen und Votes oder zeig einen Server auf deiner eigenen Website. Schreibgeschütztes JSON über HTTPS, kein Schlüssel nötig.
Grundlagen
Die Basis-URL ist https://serverroam.com/api/v1. Jeder Endpunkt antwortet auf GET mit JSON, braucht weder Schlüssel noch Konto und sendet Access-Control-Allow-Origin: *, ein Browser kann ihn also von jeder Website aus aufrufen.
Antworten werden 30 Sekunden gecacht (Cache-Control: public, max-age=30); häufigeres Fragen liefert dieselben Daten. In der API selbst gibt es kein Kontingent pro Client. Bitte cache auf deiner Seite und frag nicht schneller ab.
Gelistet sind die Einträge, die auch auf der Website erscheinen: veröffentlicht und in den letzten 7 Tagen online gesehen. votes zählt die letzten 30 Tage.
Spiele
GET /games liefert die unterstützten Spiele. servers ist die Listen-URL des Spiels.
curl https://serverroam.com/api/v1/games{
"data": [
{
"slug": "minecraft",
"name": "Minecraft",
"url": "https://serverroam.com/minecraft",
"servers": "https://serverroam.com/api/v1/servers?game=minecraft"
}
]
}
Server auflisten
GET /servers liefert eine Seite mit Einträgen. Alle Parameter sind optional:
game ist ein Spiel-Slug aus /games, etwa minecraft, fivem oder redm. Ohne ihn werden alle Spiele aufgelistet. Ein unbekannter Slug antwortet mit 400 unknown_game.
tag beschränkt die Liste auf Server mit diesem Tag, etwa survival oder roleplay. Groß- und Kleinschreibung ist egal; ein ungültiger antwortet mit 400 invalid_tag.
country beschränkt die Liste auf Server aus einem Land, als zweistelliger ISO-3166-Code wie de oder us. Ein ungültiger antwortet mit 400 invalid_country.
q sucht im Servernamen: ein Teilstring ohne Beachtung der Groß- und Kleinschreibung, höchstens 60 Zeichen.
sort ist top (meiste Votes, dann meiste Spieler; Standard), players (meiste Spieler online) oder new (neuester Eintrag zuerst). Jeder andere Wert fällt auf top zurück.
page beginnt bei 1 und geht bis 400; alles andere ist Seite 1. Eine Seite enthält 50 Server. hasMore sagt, ob eine weitere Seite folgt. Eine Gesamtzahl gibt es nicht.
curl "https://serverroam.com/api/v1/servers?game=minecraft&tag=survival&sort=players&page=1"
curl "https://serverroam.com/api/v1/servers?q=roleplay&sort=new"{
"data": [
{
"id": 42,
"game": "minecraft",
"name": "Example SMP",
"description": "A friendly survival server.",
"url": "https://serverroam.com/minecraft/example-smp",
"connect": "play.example.com",
"icon": "https://serverroam.com/icons/42",
"online": true,
"players": 37,
"maxPlayers": 100,
"votes": 214,
"verified": true,
"version": "1.21.4",
"map": null,
"country": null,
"tags": ["survival", "smp"],
"listedAt": "2026-10-02T09:15:00.000Z"
}
],
"page": 1,
"hasMore": true
}
Felder eines Servers
id ist eine Zahl, die gleich bleibt. game ist der Spiel-Slug. name und description sind der Text des Eintrags. url ist die Seite des Servers auf dieser Website: Schick Spieler dorthin zum Voten.
connect ist das, was ein Spieler ins Spiel einfügt: bei Minecraft die Adresse, bei FiveM und RedM connect cfx.re/join/<code>. icon ist eine absolute Bild-URL oder null.
online ist das Ergebnis der letzten Statusprüfung, players und maxPlayers die Spielerzahl und die Slots. votes sind die Votes der letzten 30 Tage. verified ist true, sobald der Betreiber den Server beansprucht hat.
version, map und country sind null, wo das Spiel sie nicht meldet. tags ist eine Liste kleingeschriebener Tags. listedAt ist der Zeitpunkt, zu dem der Server hinzugefügt wurde, als ISO-8601-Zeit in UTC.
Ein Server
GET /servers/{game}/{slug} liefert einen Server in data. Der Slug ist der letzte Teil der Adresse des Eintrags auf dieser Website. Nicht gelistete Server antworten mit 404 not_found.
Die Antwort für einen einzelnen Server hat ein Feld mehr, history: peak24h und peak7d sind die höchsten Spielerzahlen der letzten 24 Stunden und 7 Tage, avg7d ist der Durchschnitt der Stundenspitzen und uptime7d der Anteil der Statusprüfungen, in denen der Server geantwortet hat, in Prozent. history ist null, bis ein Server Daten für mindestens zwei Stunden hat.
curl https://serverroam.com/api/v1/servers/minecraft/example-smp{
"data": {
"id": 42,
"...": "the fields above",
"history": { "peak24h": 61, "peak7d": 74, "avg7d": 33, "uptime7d": 99 }
}
}
Fehler
Fehler kommen mit einem HTTP-Status und einem Body wie dem unten. Auch Fehlerantworten werden 30 Sekunden gecacht. Die Codes sind unknown_game und invalid_tag (beide 400) sowie not_found (404).
{ "error": "unknown_game" }
JavaScript
const res = await fetch("https://serverroam.com/api/v1/servers?game=fivem&sort=top");
const { data, hasMore } = await res.json();
for (const server of data) console.log(server.name, server.players, server.votes);
Mehr für deine Website
Zeig ein Vote-Badge mit dem Badge und empfang Votes auf deinem Server mit Webhooks oder Votifier.