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 for this section

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.

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 for this section

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

AbfrageparameterPermalink for this section

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 Zeilen, die sich noch im Übertragungsfenster befinden.

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

Antwort-HüllePermalink for this section

{
  "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.

Event-Status-FelderPermalink for this section

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 for this section

Zeitlich (die meisten Mannschaftssportarten)Permalink for this section

SituativPermalink for this section

SportartspezifischPermalink for this section

AktualitätPermalink for this section

Beendete EventsPermalink for this section

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 nach Spielende 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 for this section

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

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
}

Welche Felder eine terminale Zeile nicht trägtPermalink for this section

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 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 nicht status: "final" ist.

Beendete Events filternPermalink for this section

# 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"

BeispielanfragenPermalink for this section

# 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"

const res = await fetch('https://api.sharpapi.io/api/v1/gamestate/soccer', {
  headers: { 'X-API-Key': process.env.SHARPAPI_KEY }
});
const { data, updated_at } = await res.json();
for (const [eventId, state] of Object.entries(data.soccer ?? {})) {
  if (state.stale || state.aggregator_stale) continue;  // skip lagging rows
  console.log(
    `${state.home_team} ${state.home_score}-${state.away_score} ${state.away_team}`,
    `(${state.game_period ?? '?'} ${state.game_clock ?? ''}, ${state.primary_book})`
  );
}

import httpx, os
r = httpx.get(
    "https://api.sharpapi.io/api/v1/gamestate/soccer",
    headers={"X-API-Key": os.environ["SHARPAPI_KEY"]},
)
body = r.json()
for event_id, state in body["data"].get("soccer", {}).items():
    if state.get("stale") or state.get("aggregator_stale"):
        continue  # skip lagging rows
    print(
        f"{state['home_team']} {state['home_score']}-{state['away_score']} "
        f"{state['away_team']} ({state.get('game_period')} "
        f"{state.get('game_clock','')}, {state['primary_book']})"
    )

BeispielantwortPermalink for this section

{
  "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
      },
      "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 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 for this section

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 for this section

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"]} auf wss://ws.sharpapi.io/ws

Streaming-Clients erhalten einen initialen gamestate:snapshot mit dem vollständigen aktuellen Status (eine flache Liste von Event-Zeilen), 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.

AbschlussmeldungenPermalink for this section

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).

Rate Limits & KontingentePermalink for this section

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 for this section

• 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" — der einzige akzeptierte ?status=-Wert ist final. 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.
• primary_book / book_count fehlen — Sie lesen eine terminale 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.
• Dieselbe Partie erscheint zweimal unter verschiedenen event_ids — bekannte Einschränkung bei einigen regionalen Ligen, in denen Sportsbooks inkonsistente Liganamen verwenden. Verwenden Sie (home_team, away_team) als sekundären Dedup-Schlüssel auf dem Client, bis die verbleibenden Alias-Lücken geschlossen sind.