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
| Parameter | Typ | Beschreibung |
|---|---|---|
sport | string | (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.
| Parameter | Akzeptiert | Beschreibung |
|---|---|---|
status | final, unconfirmed | final 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_live | true, false | true 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
| Feld | Typ | Hinweise |
|---|---|---|
home_team | string | Normalisierter Name des Heimteams |
away_team | string | Normalisierter Name des Auswärtsteams |
sport | string | Sportart-Bucket (baseball, soccer, …) |
league | string | Atlas-Liga-ID (z. B. mlb, england_-_premier_league) |
home_score | integer | Aktueller Heim-Punktestand in der natürlichen Einheit für die Sportart (Runs, Punkte, Tore, Sätze — Tennis verwendet summierte Satzpunkte) |
away_score | integer | Aktueller Auswärts-Punktestand |
is_live | boolean | true bei einem Live-Event. false bei einer übertragenen beendeten Zeile — siehe Beendete Events |
primary_book | string | Das Buch, aus dem die zusammengeführten Punktestände ausgewählt wurden. Konsensbasiert — höherwertige Bücher gewinnen bei Gleichstand |
book_count | integer | Anzahl 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
| Feld | Typ | Hinweise |
|---|---|---|
aliases | string[] | 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/oddsDas 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
| Feld | Typ | Beispiel |
|---|---|---|
game_period | string | "T5" (MLB Anfang des 5.), "Q3" (NBA Q3), "2H" (Soccer 2. Halbzeit), "P2" (NHL), "S2" (Tennis 2. Satz), "FT" (Spielende) |
game_clock | string | "49:06" für hochzählende Sportarten (Soccer), "5:42" für herunterzählende Sportarten (Basketball, Hockey) |
period_number | integer | game_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
| Feld | Typ | Hinweise |
|---|---|---|
possession | "home" | "away" | Welches Team in Ballbesitz ist (Mannschaftssportarten) oder aufschlägt (Tennis) |
server | "home" | "away" | Nur Tennis — aktueller Aufschläger |
last_play | string | Sportartspezifische Beschreibung des letzten Spielzugs, sofern verfügbar |
is_timeout | boolean | true während eines Timeouts |
SportartspezifischPermalink zu diesem Abschnitt
| Feld | Sportart | Typ |
|---|---|---|
fouls_home, fouls_away | basketball, soccer | integer |
corners_home, corners_away | soccer | integer |
yellow_cards_home, yellow_cards_away | soccer | integer |
red_cards_home, red_cards_away | soccer | integer |
cards_home, cards_away | soccer | integer — Karten insgesamt, von Büchern, die eine Gesamtzahl statt der Aufteilung in Gelb / Rot melden |
power_play | hockey | "home" | "away" |
sets_home, sets_away | tennis | integer (gewonnene Sätze) |
hits_home, hits_away | baseball | integer |
home_pitcher, away_pitcher | baseball | string — Anzeigename des Starting Pitchers |
wickets_home, wickets_away | cricket | integer |
overs | cricket | float |
batting_team | cricket | "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.
| Feld | Sportart | Typ | Hinweise |
|---|---|---|---|
regulation_periods | basketball, football, hockey, soccer, baseball | integer | Anzahl 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_seconds | basketball, football, hockey, soccer | integer | Lä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_sets | tennis | integer | 3 (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
| Feld | Typ | Bedeutung |
|---|---|---|
stale | true (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_stale | true (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
}| Feld | Typ | Hinweise |
|---|---|---|
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_at | string | ISO 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_live | false | Immer explizit false, damit jede is_live-gesteuerte Darstellung die Zeile als nicht live behandelt. |
stale | false | Immer 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-0erfasst wird. Deshalb ist ein0-0ohnewinnernicht 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öchten | Anfrage |
|---|---|
| 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.
| Feld | Typ | Hinweise |
|---|---|---|
status | "unconfirmed" | Das Spiel hat den Live-Feed ohne einen Spielende-Status verlassen. |
last_seen_at | string | RFC 3339, UTC. Der Zeitpunkt, an dem das Spiel zuletzt live gesehen wurde. Das Übertragungsfenster wird ab diesem Zeitstempel gemessen. |
home_score / away_score | integer | Der zuletzt gesehene Punktestand in einer punktbasierten Sportart. |
sets_home / sets_away | integer | Die 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_clock | string | Wie zuletzt gesehen. Fehlt, wenn die Live-Zeile keine hatte. |
is_live | false | Immer explizit false. |
stale | false | Immer 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
cURL
# 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:
- SSE:
GET /api/v1/stream/gamestate - WebSocket: Abonnieren Sie
{channels: ["gamestate"]}aufwss://ws.sharpapi.io/ws
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. Wergamestate:updateerhält, erhält auchgamestate:final; Ihresport/league-Filter gelten. Ohne Game-State-Zugang erhalten Sie keines von beiden. - WebSocket spielt ihn erneut ab. Wie
gamestate:updateundgamestate:removedliegt er im Replay-Puffer und wird bei einem Reconnect mitfrom_seqerneut 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:snapshotundgamestate: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 alsgamestate: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_restrictedmitaddon: "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_errormitparameter: "status"— die einzigen akzeptierten?status=-Werte sindfinalundunconfirmed. Es gibt keinen Wertlive; Live-Zeilen sind die Standardmenge, oder fordern Sie sie allein mit?is_live=truean. - 400
validation_errormitparameter: "is_live"—?is_live=akzeptiert nurtrue/false.1und0werden abgelehnt; früher wurden sie alsfalsegelesen und lieferten das Gegenteil des Gewünschten. - Eine Zeile mit
status: "final"undis_live: false— kein Fehler. Das ist ein beendetes Event innerhalb seines 15-Minuten-Fensters. Filtern Sie mit?is_live=truefür das Verhalten von vorher. - Eine Zeile mit
status: "unconfirmed"und ohnewinner— 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=trueschließt auch diese Zeilen aus. primary_book/book_countfehlen — Sie lesen eine terminale oder unbestätigte Zeile. Prüfen Siestatus, 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_ideiner Quotenzeile hat keine Game-State-Zeile — das Spiel ist möglicherweise unter einer anderen ID gelistet, mit dieser in seinenaliases. 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 mitaliaseswurde. 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.