API-Referenz

Eine Zensus-API, die nur liest. Alles Folgende ist ein GET, und ein Schlüssel liest genau das, was eine angemeldete Person liest — nicht mehr.

Authentifizierung

Sende deinen Schlüssel in einem der beiden Header. Nichts anderes authentifiziert eine Anfrage, und ein Schlüssel an eine hier nicht aufgeführte Route wird abgelehnt statt bedient.

X-Api-Key: wos_YOUR_KEY

Oder als Bearer-Token

Authorization: Bearer wos_YOUR_KEY

Schnellstart

Ersetze den Schlüssel durch deinen eigenen.

curl -H "X-Api-Key: wos_YOUR_KEY" \ "https://api.wosatlas.com/v1/players/search?playerName=LordFrost"

Endpunkte

Methode	Pfad	Was zurückkommt	Zählt als
GET	/v1/alliances/{aid}/members	Eine Allianz mit ihrer Mitgliederliste abrufen	Anfrage
GET	/v1/alliances/leaderboard	Allianzen nach Gesamtkraft ordnen	Anfrage
GET	/v1/alliances/recruiting	Allianzen auflisten, die Bewerbungen annehmen	Anfrage
GET	/v1/alliances/search	Allianzen nach Kürzel oder Namen suchen	Suche
GET	/v1/players/{uid}	Einen Gouverneur über die interne uid abrufen	Anfrage
GET	/v1/players/search	Gouverneure nach Namen oder Gouverneur-ID suchen	Suche

Tarife und Limits

Aktuelle Betriebswerte, kein Anspruch. Sie können sich ändern.

Jedes Limit gilt pro Konto. Zusätzliche Schlüssel kaufen kein zusätzliches Budget.

Beide Kontingentfenster sind ROLLIEREND, keine Kalenderzeiträume: das Lesefenster blickt dreißig Tage zurück und das Suchfenster vierundzwanzig Stunden. Kontingent und Suche werden pro KONTO gemessen, nicht pro Schlüssel — jeder Schlüssel eines Kontos schöpft aus einem einzigen Budget.

Antwort-Header

Eine bediente Antwort trägt all diese, und eine Kontingent-Ablehnung ebenfalls. Eine Spitzen-Ablehnung trägt allein die drei Header mit dem Präfix X-RateLimit, und eine vor der Messung abgelehnte Anfrage — 401 oder 403 — trägt keine.

Header	Bedeutung
X-Quota-Limit	Das Lesekontingent des Kontos für das rollierende Dreißig-Tage-Fenster.
X-Quota-Remaining	Verbleibende Lesevorgänge in diesem Fenster.
X-Quota-Reset	Unix-Sekunden, zu denen der älteste Lesevorgang aus dem Fenster fällt.
X-Search-Limit	Das Suchkontingent des Kontos für das rollierende Vierundzwanzig-Stunden-Fenster.
X-Search-Remaining	Verbleibende Suchen in diesem Fenster.
X-Search-Reset	Unix-Sekunden, zu denen die älteste Suche aus dem Fenster fällt.
X-RateLimit-Limit	Das Spitzenkontingent des Kontos für das kurze Fenster.
X-RateLimit-Remaining	Verbleibende Anfragen im Spitzenfenster.
X-RateLimit-Reset	Unix-Sekunden, zu denen das Spitzenfenster umschlägt.
Retry-After	Sekunden, die vor einem erneuten Versuch zu warten sind. Wird bei jeder 429 gesendet und gilt dem Fenster, das abgelehnt hat.

Abgelehnt werden

Drei verschiedene Dinge antworten mit einer 429, und sie sind nicht austauschbar.

Fehlercode	Was passiert ist
QUOTA_EXCEEDED	Das rollierende Dreißig-Tage-Lesekontingent des Kontos ist aufgebraucht. `X-Quota-Remaining` steht auf null; `X-Search-Remaining` bleibt ehrlich.
SEARCH_QUOTA_EXCEEDED	Das rollierende Vierundzwanzig-Stunden-Suchkontingent des Kontos ist aufgebraucht. `X-Search-Remaining` steht auf null; `X-Quota-Remaining` bleibt ehrlich. Nur die beiden Suchrouten zählen dagegen.
RATE_LIMIT_EXCEEDED	Das kurze Spitzenfenster des Kontos ist voll. `X-RateLimit-Remaining` steht auf null. Das ist eine Grenze im Sekundenbereich, die sich von selbst löst; kein Kontingentfenster wurde angetastet.

Triff die Entscheidung über einen erneuten Versuch anhand des `error`-Codes und des `Retry-After`-Headers, niemals anhand eines Restzählers. Eine monatliche Ablehnung und eine tägliche Suchablehnung sind beide eine 429 und lassen beide den Restzähler des ANDEREN Fensters wahrheitsgemäß von null verschieden — ein Client, der nur auf `X-Quota-Remaining` schaut, sieht also eine 429 neben einem großen Restwert und schließt daraus, der Server sei kaputt.

Fehlercodes

Code	Status	Bedeutung
INVALID_API_KEY	401	Der Schlüssel ist unbekannt, widerrufen, oder das Konto, dem er gehört, wurde gelöscht.
ENDPOINT_NOT_ALLOWED	403	Die Route gehört nicht zur Entwicklerfläche. Ein Schlüssel auf einer Route außerhalb dieser Fläche wird abgelehnt statt bedient — sende also keinen Schlüssel an Endpunkte, die dieses Dokument nicht aufführt.
QUOTA_EXCEEDED	429	Das rollierende Dreißig-Tage-Lesekontingent des Kontos ist aufgebraucht. `X-Quota-Remaining` steht auf null; `X-Search-Remaining` bleibt ehrlich.
SEARCH_QUOTA_EXCEEDED	429	Das rollierende Vierundzwanzig-Stunden-Suchkontingent des Kontos ist aufgebraucht. `X-Search-Remaining` steht auf null; `X-Quota-Remaining` bleibt ehrlich. Nur die beiden Suchrouten zählen dagegen.
RATE_LIMIT_EXCEEDED	429	Das kurze Spitzenfenster des Kontos ist voll. `X-RateLimit-Remaining` steht auf null. Das ist eine Grenze im Sekundenbereich, die sich von selbst löst; kein Kontingentfenster wurde angetastet.

Maschinenlesbare Spezifikation

Das OpenAPI-Dokument unten wird vom laufenden Server erzeugt und ist dasselbe, das diese Seite darstellt.

openapi.json herunterladen

Bedingungen