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.

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

Authentifizierung

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

Pfadparameter

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

Antwort-Hülle

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

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 vorhanden

Zeitlich (die meisten Mannschaftssportarten)

Situativ

Sportartspezifisch

Aktualität

Beispielanfragen

# 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']})"
    )

Beispielantwort

{
  "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
      }
    }
  },
  "updated_at": "2026-04-23T23:55:01.234Z"
}

Cross-Book-Merge-Modell

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.

Streaming

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

Rate Limits & Kontingente

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.

Fehlerbehebung

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