Skip to Content
API-ReferenzLive-Spielstand

Live-Spielstatus

Aggregierter Live-Spielstatus — Punktestände, Perioden, Uhren, Ballbesitz und sportartspezifische situative Daten — aus Sportsbooks zusammengeführt zu einer einzigen autoritativen Ansicht pro Event. Eine Zeile pro Live-Spiel, konsensbasiert ausgewählt aus den Büchern, die es abdecken. Ein gerade beendetes Spiel bleibt hier ebenfalls für ein kurzes Zeitfenster als terminale Zeile — siehe Beendete Events.

GET /api/v1/gamestate GET /api/v1/gamestate/{sport}

AuthentifizierungPermalink zu diesem Abschnitt

Erfordert API-Schlüssel. Verfügbar mit dem Game State Add-on (79 $/Monat) oder der Enterprise-Stufe. Schlüssel ohne eines von beiden erhalten 403 tier_restricted mit addon: "game_state" im Fehler-Body. Fügen Sie das Add-on über die Abrechnungsseite  bei jedem kostenpflichtigen Plan hinzu (Hobby / Pro / Sharp); Enterprise-Schlüssel haben es bereits enthalten.

Die Ablehnung enthält außerdem upgrade und upgrade_note, und ihre message endet mit dem Preis des Add-ons und einem Link (Upgrade-Felder). Bei einem kostenpflichtigen Plan öffnet der Link das Add-on auf Ihrer Abrechnungsseite; bei Free verweist er auf die Preisseite, da Add-ons einen kostenpflichtigen Plan voraussetzen. Ein Hobby-Schlüssel erhält:

{ "error": { "code": "tier_restricted", "message": "This endpoint requires the Game State add-on or Enterprise tier. Try the Game State add-on free for 72 hours ($79/mo after, if eligible): https://sharpapi.io/dashboard/billing?addon=game_state", "docs": "https://sharpapi.io/pricing", "tier": "hobby", "addon": "game_state", "upgrade": "https://sharpapi.io/dashboard/billing?addon=game_state", "upgrade_note": "Try the Game State add-on free for 72 hours ($79/mo after, if eligible)" } }

Live-Spielstatus wird auch über den Kanal gamestate per SSE und WebSocket gestreamt — siehe Streaming unten. (Streaming-Zugriff erfordert das WebSocket Add-on oder Enterprise, zusätzlich zur oben genannten Game State- Anforderung.)

PfadparameterPermalink zu diesem Abschnitt

ParameterTypBeschreibung
sportstring(optional) Einzelne zurückzugebende Sportart. Entspricht einer bekannten Atlas-Sportart (soccer, tennis, esports, basketball, table_tennis, baseball, hockey, cricket, volleyball, handball, football, olympics, darts, boxing, rugby_league, mma, aussie_rules, snooker, rugby_union, golf, floorball, water_polo, lacrosse, futsal, other). Groß-/Kleinschreibung wird ignoriert. Eine unbekannte Sportart gibt ein leeres data-Objekt zurück — ebenso eine unterstützte Sportart, für die gerade nichts live ist; siehe Hinweis unten.

Ein leeres data-Objekt bedeutet nicht, dass die Sportart nicht unterstützt wird. Game State wird pro Sportart in einem gamestate:{sport}-Key mit 60 Sekunden TTL zusammengeführt (GAMESTATE_TTL, bewusst das Doppelte des 30-Sekunden-livestate-Fensters). Ist nichts live, läuft der Key ab und die Antwort lautet {"data":{}} — identisch zur Antwort für eine nicht abgedeckte Sportart. Mehrere der oben genannten Sportarten sind saisonal.

Mit GET /api/v1/sports sehen Sie event_count und live_count je Sportart. other ist der Fallback-Bucket für von Atlas nicht zugeordnete Sportarten.

Ohne den Pfadparameter werden alle Sportarten mit Live-Events zurückgegeben.

AbfrageparameterPermalink zu diesem Abschnitt

Beide gelten für /api/v1/gamestate und /api/v1/gamestate/{sport}. Werte sind case-insensitiv und werden getrimmt. Lassen Sie beide weg, erhalten Sie die Standardmenge: alles Live plus die beendeten und die unbestätigten Zeilen, die sich noch im Übertragungsfenster befinden.

ParameterAkzeptiertBeschreibung
statusfinal, unconfirmedfinal gibt ausschließlich die übertragenen beendeten Zeilen zurück — das Gegenstück zu /events?status=final. unconfirmed gibt ausschließlich die unbestätigten Zeilen zurück: Spiele, die den Live-Feed ohne einen Spielende-Status verlassen haben. Jeder andere Wert ist ein 400 validation_error mit accepted: ["final", "unconfirmed"] (siehe unten). Es gibt keinen Wert live: Live-Zeilen sind die Standardmenge, und ?is_live=true fordert sie allein an.
is_livetrue, falsetrue gibt nur Live-Zeilen zurück und schließt damit jede beendete und jede unbestätigte Zeile aus. false gibt nur Nicht-Live-Zeilen zurück, also die beendeten und unbestätigten Zeilen, die sich noch im Übertragungsfenster befinden. Jeder andere Wert — einschließlich 1 und 0 — ist ein 400 validation_error.

Ein unbekannter Wert wird abgelehnt, nicht ignoriert. ?status=zzz und ?is_live=1 liefern beide 400 mit einem validation_error-Body, der die akzeptierte Menge nennt, statt stillschweigend die ungefilterten oder die falschen Zeilen zurückzugeben.

{ "error": { "code": "validation_error", "message": "is_live must be one of: true, false", "details": { "parameter": "is_live", "accepted": ["true", "false"] } } }

?is_live=1 wurde früher als false gelesen und lieferte genau die Zeilen, die der Aufrufer ausschließen wollte; jetzt ist es ein 400. Wenn Sie 1 / 0 senden, stellen Sie auf true / false um.

Antwort-HüllePermalink zu diesem Abschnitt

{ "data": { "<sport>": { "<event_id>": { ...event state... } } }, "updated_at": "2026-04-23T23:55:01.234Z" }

Jeder Event-Status ist über seine kanonische event_id innerhalb seines Sportart- Buckets indiziert. updated_at ist die Serverzeit, zu der diese Antwort erstellt wurde — verwenden Sie sie, um die Aktualität bei Polling abzuschätzen.

Ein Spiel, das Sportsbooks unter verschiedenen event_ids führen, erscheint einmal: Die Zeile ist unter einer davon indiziert und listet die anderen in aliases.

Event-Status-FelderPermalink zu diesem Abschnitt

Jedes Feld ist optional, sofern nicht anders angegeben. Das Vorhandensein variiert je nach Sportart — Tennis-Events enthalten sets_home / server; Hockey-Events enthalten power_play; Soccer-Events enthalten corners_* / yellow_cards_*; usw.

Immer vorhandenPermalink zu diesem Abschnitt

FeldTypHinweise
home_teamstringNormalisierter Name des Heimteams
away_teamstringNormalisierter Name des Auswärtsteams
sportstringSportart-Bucket (baseball, soccer, …)
leaguestringAtlas-Liga-ID (z. B. mlb, england_-_premier_league)
home_scoreintegerAktueller Heim-Punktestand in der natürlichen Einheit für die Sportart (Runs, Punkte, Tore, Sätze — Tennis verwendet summierte Satzpunkte)
away_scoreintegerAktueller Auswärts-Punktestand
is_livebooleantrue bei einem Live-Event. false bei einer übertragenen beendeten Zeile — siehe Beendete Events
primary_bookstringDas Buch, aus dem die zusammengeführten Punktestände ausgewählt wurden. Konsensbasiert — höherwertige Bücher gewinnen bei Gleichstand
book_countintegerAnzahl der Sportsbooks, die zum Zeitpunkt des Mergens Live-Status für dieses Event beigetragen haben

„Immer vorhanden” heißt: immer vorhanden auf einer Live-Zeile. Eine übertragene beendete Zeile wird aus dem Abschluss-Datensatz gebildet, nicht aus einem Live-Merge, und trägt daher weder primary_book noch book_count und kein game_period / game_clock. Auch ihre Punktestandsfelder hängen von der Sportart ab: satzbasierte Sportarten tragen sets_home / sets_away statt home_score / away_score. Prüfen Sie status === "final", bevor Sie eines dieser Felder lesen. Die vollständige terminale Form steht unter Beendete Events. Eine unbestätigte Zeile (status: "unconfirmed") trägt ebenfalls weder primary_book noch book_count, behält aber game_period / game_clock wie zuletzt gesehen.

Eine Zeile pro Spiel: aliasesPermalink zu diesem Abschnitt

FeldTypHinweise
aliasesstring[]Die anderen event_ids, die dasselbe Spiel bezeichnen, alphabetisch sortiert. Enthält nie die eigene event_id der Zeile. Nur vorhanden, wenn das Spiel unter mehr als einer ID bekannt ist; sonst weggelassen, nie null oder []

Sportsbooks führen ein Spiel manchmal unter unterschiedlichen Liganamen, wodurch es bei jedem Buch eine andere event_id erhält. SharpAPI führt diese zu einer Zeile zusammen: Das Spiel erscheint einmal, unter einer event_id, und aliases listet die anderen.

Quotenzeilen und Opportunities des Spiels können jede dieser IDs tragen. Um den Spielstatus zu einer Quotenzeile zu finden, gleichen Sie deren event_id mit dem Schlüssel der Zeile oder einer beliebigen ID in aliases ab:

// data = body.data aus GET /api/v1/gamestate const byId = new Map(); for (const rows of Object.values(data)) { for (const [eventId, state] of Object.entries(rows)) { byId.set(eventId, state); for (const alias of state.aliases ?? []) byId.set(alias, state); } } const state = byId.get(odd.event_id); // odd = eine Zeile aus /api/v1/odds

Das Feld ist auf REST und auf den Streaming-Zeilen gleich. Nur Live-Zeilen tragen es: terminale und unbestätigte Zeilen nicht.

Seit 2026-11-12: IDs auch über aliases nachschlagen. Davor erschien ein zusammengeführtes Spiel einmal pro ID, jede Zeile mit demselben Status, sodass jede seiner IDs es als Schlüssel fand. Jetzt tut das nur noch eine. Code, der den Spielstatus über die event_id einer Quotenzeile nachschlägt, muss auch aliases prüfen, sonst verfehlt er diese Spiele. Code, der die wiederholten Zeilen verworfen hat, funktioniert weiter.

Zeitlich (die meisten Mannschaftssportarten)Permalink zu diesem Abschnitt

FeldTypBeispiel
game_periodstring"T5" (MLB Anfang des 5.), "Q3" (NBA Q3), "2H" (Soccer 2. Halbzeit), "P2" (NHL), "S2" (Tennis 2. Satz), "FT" (Spielende)
game_clockstring"49:06" für hochzählende Sportarten (Soccer), "5:42" für herunterzählende Sportarten (Basketball, Hockey)
period_numberintegergame_period als Zahl, zum Sortieren und Vergleichen des Spielfortschritts: "Q3" → 3, "2H" → 2, "S2" → 2; Anfang und Ende eines Innings teilen sich die Zahl ("T8" und "B8" → 8). Die Verlängerung zählt nach der regulären Spielzeit weiter: "OT" → 5 und "OT2" → 6 in einem Spiel mit vier Vierteln, Soccer-Verlängerung "ET" → 3. Fehlt (nie null), wenn die Periode keine Nummer hat ("HT", "SO", "PK", "FT"), und bei allen Sportarten außer Baseball, Basketball, Football, Hockey, Soccer und Tennis. Wie regulation_periods die Nummer der Verlängerung ändert: Spielstruktur

SituativPermalink zu diesem Abschnitt

FeldTypHinweise
possession"home" | "away"Welches Team in Ballbesitz ist (Mannschaftssportarten) oder aufschlägt (Tennis)
server"home" | "away"Nur Tennis — aktueller Aufschläger
last_playstringSportartspezifische Beschreibung des letzten Spielzugs, sofern verfügbar
is_timeoutbooleantrue während eines Timeouts

SportartspezifischPermalink zu diesem Abschnitt

FeldSportartTyp
fouls_home, fouls_awaybasketball, soccerinteger
corners_home, corners_awaysoccerinteger
yellow_cards_home, yellow_cards_awaysoccerinteger
red_cards_home, red_cards_awaysoccerinteger
cards_home, cards_awaysoccerinteger — Karten insgesamt, von Büchern, die eine Gesamtzahl statt der Aufteilung in Gelb / Rot melden
power_playhockey"home" | "away"
sets_home, sets_awaytennisinteger (gewonnene Sätze)
hits_home, hits_awaybaseballinteger
home_pitcher, away_pitcherbaseballstring — Anzeigename des Starting Pitchers
wickets_home, wickets_awaycricketinteger
overscricketfloat
batting_teamcricket"home" | "away"

Rote Karten. Bei Fußball bedeutet ein explizites red_cards_home / red_cards_away von 0, dass ein abdeckendes Buch keine Rote Karte gemeldet hat. Fehlen beide Felder, hat kein abdeckendes Buch Karten für dieses Spiel gemeldet: das bedeutet nicht 0, und die Felder sind nie null.

Zählfelder sind nur vorhanden, wenn sie gemeldet wurden. corners_*, fouls_*, cards_*, yellow_cards_*, red_cards_* und die übrigen Zählwerte je Team erscheinen nur, wenn ein Buch, das das Event abdeckt, sie gemeldet hat. Eine gemeldete Null ist 0; ein fehlendes Feld bedeutet unbekannt, niemals 0. Setzen Sie einen fehlenden Zählwert also nicht auf null. Welche Zählwerte ein Event trägt, hängt von den Büchern ab, die es abdecken: Decken mehrere Bücher ein Event ab, stammt jeder Zählwert vom ranghöchsten abdeckenden Buch, das ihn gemeldet hat (Klasse C im Cross-Book-Merge-Modell). Der optionale stats-Block je Team wird aus denselben Feldern gebaut und folgt derselben Regel: Ein Zählwert steht dort nur, wenn er vorhanden ist.

SpielstrukturPermalink zu diesem Abschnitt

Wie das Event angesetzt ist. Diese drei Felder stammen aus den Event-Daten von DraftKings. Sie erscheinen daher nur auf einer Live-Zeile, zu der DraftKings beim Merge beigetragen hat, und nur, wenn DraftKings den Wert geliefert hat. Sonst fehlt das Feld (nie null) — prüfen Sie, ob der Schlüssel vorhanden ist, bevor Sie ihn lesen. Zeilen beendeter Events tragen sie nie.

FeldSportartTypHinweise
regulation_periodsbasketball, football, hockey, soccer, baseballintegerAnzahl der regulären Perioden, ohne Verlängerung. Typische Werte: NBA und NFL 4, College-Basketball der Männer 2 (Halbzeiten), College-Basketball der Frauen 4, NHL 3, Soccer 2, MLB 9 (Innings)
period_length_secondsbasketball, football, hockey, soccerintegerLänge einer regulären Periode auf der Spieluhr, in Sekunden. Typische Werte: NBA 720, NFL und College-Football 900, College-Basketball der Männer 1200, College-Basketball der Frauen 600, NHL 1200, Soccer 2700. Für Baseball nie gesendet
best_of_setstennisinteger3 (Best of Three) oder 5 (Best of Five)

Trägt eine Zeile regulation_periods, zählt period_number die Verlängerung von diesem Wert aus statt vom üblichen Format der Sportart. Ein College-Basketballspiel der Männer hat zwei Halbzeiten, also ist seine erste Verlängerung period_number 3; mit dem Standard von vier Vierteln wäre es 5. Zeilen ohne das Feld nutzen das übliche Format: vier Viertel für Basketball und Football, drei Perioden für Hockey, zwei Halbzeiten für Soccer.

AktualitätPermalink zu diesem Abschnitt

FeldTypBedeutung
staletrue (sonst weggelassen)Die TTL des Livestate-Schlüssels von primary_book ist zum Zeitpunkt des Mergens unter den Aktualitätsschwellenwert des Aggregators (~10s) gefallen. Punktestände sind die zuletzt bekannten Werte; das Buch ist verstummt. Behandeln Sie Punktestände und Periode des Events als möglicherweise hinter dem tatsächlichen Spielstatus zurückbleibend.
aggregator_staletrue (sonst weggelassen)Der SharpAPI-Aggregator selbst hat seit über ~30s keinen neuen gamestate:{sport}-Shard für diese Sportart geschrieben. Breiteres Signal als stale — weist auf eine Pipeline-Störung hin, nicht auf ein Problem mit einem einzelnen Buch. Wenn Sie dies anhaltend sehen, kontaktieren Sie den Support.

Abwesenheit = aktuell. Sowohl stale als auch aggregator_stale werden nur geschrieben, wenn sie zutreffen, was die Payload kompakt hält. Wenn Sie sie nicht bei einem Event sehen, gelten die Daten als aktuell.

Beendete EventsPermalink zu diesem Abschnitt

Ein Spiel verschwand früher in dem Moment aus /gamestate, in dem es endete — das Endergebnis war nur für Clients sichtbar, die zufällig während des letzten Live-Zyklus gepollt haben. Beendete Events bleiben jetzt 15 Minuten ab dem Zeitpunkt, an dem sie erstmals als beendet erscheinen, als terminale Zeile auf diesem Endpoint, sodass jeder Poller mit vernünftigem Intervall das Endergebnis mindestens einmal sieht.

Das Fenster ist serverseitig und beträgt derzeit 15 Minuten (GAMESTATE_TERMINAL_CARRY_SECONDS, Standard 900). Danach verschwindet die Zeile endgültig; das abgeschlossene Ergebnis bleibt über /api/v1/events?status=final verfügbar — die Quelle, aus der die terminale Zeile stammt.

So sieht eine terminale Zeile ausPermalink zu diesem Abschnitt

{ "home_team": "Skelleftea AIK", "away_team": "Geneva Servette HC", "sport": "hockey", "league": "champions_hockey_league", "home_score": 2, "away_score": 1, "score_type": "points", "winner": "home", "status": "final", "completed_at": "2026-09-10T18:54:03Z", "is_live": false, "stale": false }
FeldTypHinweise
status"final" | "unconfirmed"Nur auf einer übertragenen Zeile vorhanden: "final" auf einer terminalen Zeile, "unconfirmed" auf einer unbestätigten Zeile. Live-Zeilen tragen überhaupt keinen status-Schlüssel, daher ist status === "final" der verlässliche Test — leiten Sie ihn nicht aus is_live ab. Eine "final"-Zeile kann noch zu "unconfirmed" zurückkehren, solange eine andere Quelle ihren Punktestand bestreitet; behandeln Sie ein Endergebnis also nicht in dem Moment als unumkehrbar, in dem Sie es sehen.
completed_atstringISO 8601 — der Zeitpunkt, zu dem SharpAPI den Abschluss erkannt hat, nicht der offizielle Schlusspfiff der Liga. Das Übertragungsfenster wird nicht ab diesem Zeitstempel gemessen, sondern ab dem Zeitpunkt, an dem die Zeile erstmals als beendet erschien, meist wenige Minuten danach. Ein Spiel, das als beendet bestätigt wird, nachdem es den Live-Feed verlassen hat, kann deutlich später als sein completed_at als beendet erscheinen.
score_type"points" | "sets"Welche Felder das Ergebnis tragen. "sets" für die satzbasierten Sportarten (tennis, table_tennis, volleyball, badminton); "points" überall sonst.
winner"home" | "away" | "draw"Optional — wird weggelassen, wenn das Ergebnis nicht bestimmbar ist; siehe unten. "draw" entsteht nur bei Sportarten, in denen ein Gleichstand ein echtes Resultat ist (soccer, hockey, football, rugby_union, rugby_league).
is_livefalseImmer explizit false, damit jede is_live-gesteuerte Darstellung die Zeile als nicht live behandelt.
stalefalseImmer explizit false. Dies ist die einzige Stelle, an der stale erscheint, ohne zuzutreffen — die Regel „Abwesenheit = aktuell” oben gilt nur für Live-Zeilen.

Endergebnisse verwenden die Live-Feldnamen, je nach Sportart. Eine punktbasierte Sportart legt ihren Zählstand in home_score / away_score. Eine satzbasierte Sportart legt ihre Satzanzahl in sets_home / sets_away und trägt kein home_score / away_score — ein Tennis-Endstand ist 2:1 in Sätzen, und das in home_score zu legen würde mit den Spielpunkten der Live-Zeile kollidieren:

{ "home_team": "Mikhail Biserov", "away_team": "Vasily Yugov", "sport": "table_tennis", "league": "pro_league", "sets_home": 2, "sets_away": 1, "score_type": "sets", "winner": "home", "status": "final", "completed_at": "2026-09-10T18:55:25Z", "is_live": false, "stale": false }

winner kann fehlen, und das hat eine Bedeutung. Das Feld wird weggelassen, wenn das erfasste Ergebnis das Spiel nicht entscheidet:

  • ein Gleichstand in einer Sportart ohne Unentschieden (Basketball, Handball, E-Sport, Baseball …) — das Spiel ging in die Verlängerung, wurde abgebrochen, oder der Feed endete vor der Entscheidung;
  • eine sub-terminale Satzanzahl in einer satzbasierten Sportart (wer weniger als zwei Sätze führt, kann kein Format gewonnen haben);
  • ein Snapshot, dessen Punktestände nie eintrafen, der als 0-0 erfasst wird. Deshalb ist ein 0-0 ohne winner nicht dasselbe wie ein echtes torloses Unentschieden — ein echtes trägt "winner": "draw".

Behandeln Sie ein fehlendes winner als „nicht entschieden”, nicht als Gleichstand. Wenn Sie werten oder abrechnen, überspringen Sie diese Zeilen.

Welche Felder eine terminale Zeile nicht trägtPermalink zu diesem Abschnitt

Eine terminale Zeile wird aus dem Abschluss-Datensatz projiziert, nicht aus einem Live-Merge über mehrere Bücher, daher fehlen diese Live-Felder schlicht: primary_book, book_count, game_period, game_clock, period_number, die Felder der Spielstruktur sowie jedes situative Feld (possession, corners_*, power_play, in_play, die Tennis-Siegwahrscheinlichkeits-Familie und so weiter). Lesen Sie sie erst, nachdem Sie geprüft haben, dass die Zeile keinen status-Schlüssel trägt.

Beendete Events filternPermalink zu diesem Abschnitt

Sie möchtenAnfrage
Nur Live-Zeilen (Verhalten vor der Übertragung)?is_live=true
Nur beendete Zeilen?status=final
Nur unbestätigte Zeilen?status=unconfirmed
Alle zusammen (Standard)kein Parameter
# Nur die Endergebnisse der letzten 15 Minuten, eine Sportart curl "https://api.sharpapi.io/api/v1/gamestate/soccer?status=final" \ -H "X-API-Key: YOUR_API_KEY" # Genau das, was Sie vor der Übertragung bekommen haben curl "https://api.sharpapi.io/api/v1/gamestate?is_live=true" \ -H "X-API-Key: YOUR_API_KEY"

Ist ein beendetes Event irgendwo noch live, gewinnt die Live-Zeile. Eine event_id, die sowohl in der Live-Menge als auch in der übertragenen Menge auftaucht, wird einmal zurückgegeben — als Live-Zeile. Ein Buch, das das Spiel noch quotiert, hält es live, bis jedes Buch es fallengelassen hat.

Unbestätigte SpielePermalink zu diesem Abschnitt

Manchmal führt der Live-Feed ein Spiel nicht mehr, bevor er das Spielende zeigt. Ein solches Spiel verschwindet nicht mehr aus /gamestate. Es bleibt für dasselbe 15-minütige Übertragungsfenster, gezählt ab dem Zeitpunkt, an dem es zuletzt live gesehen wurde, als unbestätigte Zeile:

{ "home_team": "CSU Bakersfield", "away_team": "North Dakota State", "sport": "basketball", "league": "ncaab", "home_score": 91, "away_score": 80, "score_type": "points", "game_period": "2H", "game_clock": "0:17", "status": "unconfirmed", "last_seen_at": "2026-11-09T00:53:55Z", "is_live": false, "stale": false }

Der Punktestand ist der zuletzt gesehene. Er ist kein Endergebnis, werten oder rechnen Sie also nicht darauf ab.

FeldTypHinweise
status"unconfirmed"Das Spiel hat den Live-Feed ohne einen Spielende-Status verlassen.
last_seen_atstringRFC 3339, UTC. Der Zeitpunkt, an dem das Spiel zuletzt live gesehen wurde. Das Übertragungsfenster wird ab diesem Zeitstempel gemessen.
home_score / away_scoreintegerDer zuletzt gesehene Punktestand in einer punktbasierten Sportart.
sets_home / sets_awayintegerDie zuletzt gesehene Satzanzahl in einer satzbasierten Sportart (tennis, table_tennis, volleyball, badminton), statt home_score / away_score, wie auf einer terminalen Zeile.
score_type"points" | "sets"Welche Punktestandsfelder die Zeile trägt. Fehlt, wenn die letzte Live-Zeile einen unvollständigen Punktestand hatte; siehe unten.
game_period / game_clockstringWie zuletzt gesehen. Fehlt, wenn die Live-Zeile keine hatte.
is_livefalseImmer explizit false.
stalefalseImmer explizit false.

Eine unbestätigte Zeile hat kein winner und kein completed_at, weil nichts besagt, dass das Spiel geendet hat. Wie eine terminale Zeile trägt sie weder primary_book noch book_count noch situative Felder.

Ein unvollständiger Punktestand wird so weitergegeben, wie er gesehen wurde. In einer satzbasierten Sportart fehlen der letzten Live-Zeile manchmal eine oder beide Satzanzahlen, und sie trägt vielleicht nur home_score / away_score oder games_home / games_away. Im Cricket hat die Seite, die noch nicht geschlagen hat, keinen Punktestand. Die unbestätigte Zeile trägt dann genau die Punktestandsfelder, die die Live-Zeile hatte, unter denselben Namen und ohne score_type. Eine fehlende Seite wird nicht mit 0 aufgefüllt:

{ "home_team": "Andrey Shmakov", "away_team": "Dmitry Kutenkov", "sport": "table_tennis", "league": "russia_-_liga_pro", "sets_home": 2, "game_period": "S3", "status": "unconfirmed", "last_seen_at": "2026-11-09T00:58:05Z", "is_live": false, "stale": false }

Ein Spiel, dessen letzte Live-Zeile keinen verwertbaren Punktestand hatte, wird nicht als unbestätigt übertragen. Es verlässt /gamestate, sobald der Live-Feed es nicht mehr führt.

Wann ein unbestätigtes Spiel beendet wirdPermalink zu diesem Abschnitt

Eine unbestätigte Zeile wird auf einem von zwei Wegen zu einer terminalen Zeile mit status: "final", mit winner und completed_at:

  • der Live-Feed zeigt doch noch das Spielende, oder
  • SharpAPI bestätigt das Endergebnis aus einer anderen Quelle.

Vorher wird es nie als beendet angezeigt. Die beendete Zeile wird dann ab diesem Moment 15 Minuten lang übertragen, nicht ab ihrem completed_at. Geschieht keines von beiden innerhalb des Übertragungsfensters, verlässt die unbestätigte Zeile /gamestate, wenn das Fenster endet, und eine später eintreffende Bestätigung bringt das Spiel für seine 15 Minuten als beendete Zeile zurück. Kehrt das Spiel in den Live-Feed zurück, ersetzt die Live-Zeile sie, wie im Hinweis oben. Ein Endergebnis, dessen Punktestand eine andere Quelle bestreitet, kann außerdem zu unconfirmed zurückkehren, bis der Streit geklärt ist.

unconfirmed bedeutet dasselbe auf /events/{eventId}, das den zuletzt gesehenen Punktestand unter last_seen zeigt.

# Spiele, die den Feed ohne Spielende-Status verlassen haben, letzte 15 Minuten curl "https://api.sharpapi.io/api/v1/gamestate?status=unconfirmed" \ -H "X-API-Key: YOUR_API_KEY"

BeispielanfragenPermalink zu diesem Abschnitt

# Alle Live-Events über alle Sportarten curl "https://api.sharpapi.io/api/v1/gamestate" \ -H "X-API-Key: YOUR_API_KEY" # Eine Sportart curl "https://api.sharpapi.io/api/v1/gamestate/soccer" \ -H "X-API-Key: YOUR_API_KEY"

BeispielantwortPermalink zu diesem Abschnitt

{ "data": { "soccer": { "argentina_-_primera_division_bocajuniors_defensayjusticia_2026-04-23": { "home_team": "Defensa y Justicia", "away_team": "Boca Juniors", "sport": "soccer", "league": "argentina_-_primera_division", "home_score": 0, "away_score": 1, "game_period": "2H", "game_clock": "49:06", "is_live": true, "possession": "away", "corners_home": 1, "corners_away": 0, "fouls_home": 0, "fouls_away": 0, "yellow_cards_home": 0, "yellow_cards_away": 0, "red_cards_home": 0, "red_cards_away": 0, "primary_book": "draftkings", "book_count": 6, "aliases": ["argentina_-_liga_profesional_bocajuniors_defensayjusticia_2026-04-23"] }, "chile_-_primera_division_concepcion_palestino_2026-04-24": { "home_team": "Palestino", "away_team": "Concepción", "sport": "soccer", "league": "chile_-_primera_division", "home_score": 0, "away_score": 0, "is_live": true, "primary_book": "unibet", "book_count": 1, "stale": true }, "montenegro_-_prva_liga_bokelj_otrantolympiculcinj_2026-04-23": { "home_team": "Bokelj", "away_team": "FK Otrant-Olympic Ulcinj", "sport": "soccer", "league": "montenegro_-_prva_liga", "home_score": 2, "away_score": 1, "score_type": "points", "winner": "home", "status": "final", "completed_at": "2026-04-23T23:48:55Z", "is_live": false, "stale": false } } }, "updated_at": "2026-04-23T23:55:01.234Z" }

Die erste Zeile ist ein Spiel, das manche Bücher unter einem anderen Liganamen führen, daher steht seine andere event_id in aliases. Die dritte Zeile ist eine terminale Zeile: Das Spiel endete rund sechs Minuten, bevor diese Antwort erzeugt wurde, wird also mit status: "final" und seinem Endstand übertragen und trägt kein primary_book, book_count, game_period oder game_clock.

Cross-Book-Merge-ModellPermalink zu diesem Abschnitt

Die Felder jedes Events werden aus dem Livestate-Snapshot jedes Sportsbooks über einen dreiklassigen Algorithmus zusammengeführt:

  • Klasse A — Punktestände werden per Konsens ausgewählt: Unter den Büchern mit dem am weitesten fortgeschrittenen Periodenrang gewinnt der höchste Gesamtpunktestand mit ≥2 Unterstützern. Ein einzelnes Buch, das einen Ausreißer-Score meldet (häufig in den ersten Sekunden einer Punkteänderung oder von einem fehlerhaften Adapter), wird abgelehnt.
  • Klasse B — Zeitliche Felder (game_period, game_clock) werden basierend auf der sportartabhängigen Uhrenrichtung — herunterzählend vs. hochzählend — und dem Periodenrang ausgewählt.
  • Klasse C — Situative Felder (possession, corners_*, etc.) werden prioritätsbasiert aus einem festen Buchranking gefüllt.

primary_book gibt an, aus welchem Buch die siegreichen Punktestände stammten. book_count ist die Gesamtzahl der Bücher, die zum Zeitpunkt des Mergens irgendeinen Status zum Event beigetragen haben.

StreamingPermalink zu diesem Abschnitt

Jede Live-Aktualisierung, die der REST-Endpoint beim nächsten Poll anzeigen würde, löst auch ein gamestate:update-Event auf den Streaming-Kanälen aus:

Streaming-Clients erhalten einen initialen gamestate:snapshot mit dem vollständigen aktuellen Status (eine flache Liste von Event-Zeilen: Live-Zeilen plus alle beendeten und unbestätigten Zeilen, die sich noch im Übertragungsfenster befinden), dann gamestate:update-Events mit geänderten Zeilen während des Mergens und gamestate:removed-Events, wenn Events aus der Live-Menge fallen.

Ein beendetes Event bleibt als status: "final"-Zeile für das Fenster aus Beendete Events in der gestreamten Slate und wird einmal mit einem gamestate:final-Frame angekündigt. Ein Spiel, das den Feed ohne Spielende-Status verlässt, bleibt für das Fenster als status: "unconfirmed"-Zeile in der Slate, gesendet als gamestate:update. Auf WebSocket kommt sein gamestate:removed erst, wenn sein Fenster endet; auf SSE erscheint die Zeile danach einfach nicht mehr. Auf beiden Transporten ist eine Zeile mit einem status-Schlüssel (final oder unconfirmed) nicht live. Um Quotenzeilen zuzuordnen, indizieren Sie jede Zeile zusätzlich unter ihren aliases und aktualisieren diese Einträge, wenn sich die Zeile ändert oder entfernt wird.

AbschlussmeldungenPermalink zu diesem Abschnitt

Wenn ein Event endet, sendet jeder Transport genau einen gamestate:final-Frame dafür. Er trägt die terminale Zeile des Events — dieselbe Form wie die REST-Zeile, plus event_id.

WebSocket:

{"type":"gamestate:final","seq":48213,"global_seq":"48213","data":[{"event_id":"atp_jdoe_rroe_2026-07-03","home_team":"J. Doe","away_team":"R. Roe","sport":"tennis","league":"atp","sets_home":1,"sets_away":2,"score_type":"sets","winner":"away","status":"final","completed_at":"2026-07-03T19:42:10Z","is_live":false,"stale":false}]}

SSE (dieselbe {"data": [...]}-Hülle wie gamestate:update):

event: gamestate:final data: {"data":[{"event_id":"atp_jdoe_rroe_2026-07-03","home_team":"J. Doe","away_team":"R. Roe","sport":"tennis","league":"atp","sets_home":1,"sets_away":2,"score_type":"sets","winner":"away","status":"final","completed_at":"2026-07-03T19:42:10Z","is_live":false,"stale":false}]}
  • Gleicher Zugang, gleiche Filter wie gamestate:update. Wer gamestate:update erhält, erhält auch gamestate:final; Ihre sport/league-Filter gelten. Ohne Game-State-Zugang erhalten Sie keines von beiden.
  • WebSocket spielt ihn erneut ab. Wie gamestate:update und gamestate:removed liegt er im Replay-Puffer und wird bei einem Reconnect mit from_seq erneut gesendet. SSE-Gamestate-Frames sind nicht fortsetzbar.
  • Eine Ankündigung, nicht die einzige Zustellung. Dieselbe Zeile steht während des ganzen Fensters auch in der Slate (gamestate:snapshot und gamestate:update).
  • Nie für eine unbestätigte Zeile. Ein Spiel, das ohne Spielende-Status ausgeschieden ist, wird nicht angekündigt; seine status: "unconfirmed"-Zeile kommt nur als gamestate:update.

„Einmal pro Event“ kann sich gelegentlich wiederholen — deduplizieren Sie auf (event_id, completed_at). Sie können gamestate:final für dasselbe Event mehr als einmal erhalten. event_id und completed_at sind bei jeder Wiederholung identisch; verwerfen Sie einen Frame, dessen Paar Sie schon verarbeitet haben. Das ist immer sicher, weil die Zeile weiterhin in der Slate steht.

Rate Limits & KontingentePermalink zu diesem Abschnitt

Rate Limits richten sich nach Ihrer Basisstufe, nicht nach dem Add-on — Hobby-Schlüssel behalten ihre 120 req/min, Pro behalten 300, Sharp behalten 1.000, Enterprise individuell. Siehe Pricing . /gamestate zählt genauso wie andere REST-Aufrufe zum Pro-Minute-Kontingent.

FehlerbehebungPermalink zu diesem Abschnitt

  • 403 tier_restricted mit addon: "game_state" — Ihr Schlüssel hat das Game State Add-on nicht. Fügen Sie es über Billing  für 79 $/Monat hinzu oder upgraden Sie auf Enterprise.
  • 400 validation_error mit parameter: "status" — die einzigen akzeptierten ?status=-Werte sind final und unconfirmed. Es gibt keinen Wert live; Live-Zeilen sind die Standardmenge, oder fordern Sie sie allein mit ?is_live=true an.
  • 400 validation_error mit parameter: "is_live" — ?is_live= akzeptiert nur true / false. 1 und 0 werden abgelehnt; früher wurden sie als false gelesen und lieferten das Gegenteil des Gewünschten.
  • Eine Zeile mit status: "final" und is_live: false — kein Fehler. Das ist ein beendetes Event innerhalb seines 15-Minuten-Fensters. Filtern Sie mit ?is_live=true für das Verhalten von vorher.
  • Eine Zeile mit status: "unconfirmed" und ohne winner — kein Fehler. Das Spiel hat den Live-Feed ohne Spielende-Status verlassen; der Punktestand ist der zuletzt gesehene, kein Ergebnis. Siehe Unbestätigte Spiele. ?is_live=true schließt auch diese Zeilen aus.
  • primary_book / book_count fehlen — Sie lesen eine terminale oder unbestätigte Zeile. Prüfen Sie status, bevor Sie Live-Felder lesen.
  • Leeres data-Objekt — keine Live-Events im Bereich. Dies ist häufig zwischen Events bei kleineren Sportplänen. Pollen Sie erneut.
  • Events mit stale: true — das primäre Buch ist verstummt. Punktestände können hinterherhinken; erwägen Sie, sie herauszufiltern oder einen UI- Indikator anzuzeigen.
  • Events mit aggregator_stale: true — der SharpAPI-Aggregator hat diese Sportart seit >30s nicht aktualisiert. Wenn anhaltend, kontaktieren Sie den Support; ein kurzer Anstieg kann während Redeploys auftreten.
  • Die event_id einer Quotenzeile hat keine Game-State-Zeile — das Spiel ist möglicherweise unter einer anderen ID gelistet, mit dieser in seinen aliases. Suchen Sie die ID auch dort.
  • Dieselbe Partie erscheint zweimal unter verschiedenen event_ids — seltener seit 2026-11-12, als ein unter verschiedenen Liganamen geführtes Spiel zu einer Zeile mit aliases wurde. Es kann weiterhin vorkommen, etwa wenn Bücher einen Teamnamen unterschiedlich schreiben, und ein beendetes oder unbestätigtes Spiel kann unter mehr als einer ID übertragen werden. Wenn Sie nach (home_team, away_team) deduplizieren, vergleichen Sie auch den Punktestand: Dieselben zwei Teams können an einem Tag zweimal spielen.
Last updated on