Estado de Juego en Vivo

Estado de juego en vivo agregado — marcadores, periodos, relojes, posesión y datos situacionales específicos de cada deporte — fusionado entre sportsbooks en una única vista autorizada por evento. Una fila por encuentro en vivo, seleccionada por consenso entre los libros que lo cubren. Un encuentro que acaba de terminar también permanece aquí durante una ventana breve como fila terminal — consulta Eventos finalizados.

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

AutenticaciónPermalink for this section

Requiere API key. Disponible con el complemento Game State ($79/mes) o el plan Enterprise. Las claves sin ninguno de los dos reciben 403 tier_restricted con addon: "game_state" en el cuerpo del error. Añade el complemento desde la página de facturación  en cualquier plan de pago (Hobby / Pro / Sharp); las claves Enterprise lo tienen incluido.

El estado de juego en vivo también se transmite a través del canal gamestate en SSE y WebSocket — consulta Streaming más abajo. (El acceso al streaming requiere el complemento WebSocket o Enterprise, además del requisito de Game State indicado anteriormente.)

Parámetros de RutaPermalink for this section

Sin el parámetro de ruta, devuelve todos los deportes con eventos en vivo.

Filtros de consultaPermalink for this section

Ambos se aplican a /api/v1/gamestate y /api/v1/gamestate/{sport}. Los valores no distinguen mayúsculas y se recortan. Si omites ambos, obtienes el conjunto por defecto: todo lo que está en vivo, más las filas finalizadas que siguen dentro de la ventana de arrastre.

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

Sobre de RespuestaPermalink for this section

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

Cada estado de evento se indexa por su event_id canónico dentro del contenedor de su deporte. updated_at es la hora del servidor en la que se construyó esta respuesta — úsala para evaluar la frescura si haces polling.

Campos del Estado del EventoPermalink for this section

Todos los campos son opcionales excepto donde se indique. La presencia varía según el deporte — los eventos de tenis incluyen sets_home / server; los eventos de hockey incluyen power_play; los eventos de fútbol incluyen corners_* / yellow_cards_*; etc.

Siempre presentesPermalink for this section

Temporales (la mayoría de deportes de equipo)Permalink for this section

SituacionalesPermalink for this section

Específicos por deportePermalink for this section

FrescuraPermalink for this section

Eventos finalizadosPermalink for this section

Antes, un encuentro desaparecía de /gamestate en el momento en que terminaba — el marcador final solo era visible para el cliente que casualmente hiciera polling durante el último ciclo en vivo. Ahora los eventos finalizados permanecen en este endpoint 15 minutos después de terminar como fila terminal, de modo que cualquier cliente con un intervalo razonable ve el resultado final al menos una vez.

La ventana es del lado servidor y actualmente es de 15 minutos (GAMESTATE_TERMINAL_CARRY_SECONDS, por defecto 900). Cuando expira, la fila desaparece definitivamente; el resultado ya cerrado sigue disponible en /api/v1/events?status=final, que es de donde procede la fila terminal.

Cómo es una fila terminalPermalink 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
}

Los marcadores finales usan los nombres de campo en vivo, según el deporte. Un deporte por puntos pone su cómputo en home_score / away_score. Un deporte por sets pone su recuento de sets en sets_home / sets_away y no lleva home_score / away_score — un final de tenis es 2-1 en sets, y ponerlo en home_score chocaría con los puntos de juego de la fila en vivo:

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

Qué campos no lleva una fila terminalPermalink for this section

Una fila terminal se proyecta desde el registro de finalización, no desde una fusión en vivo entre libros, así que estos campos en vivo simplemente no están: primary_book, book_count, game_period, game_clock y todos los campos situacionales (possession, corners_*, power_play, in_play, la familia de probabilidad de victoria de tenis, etc.). Léelos solo después de comprobar que la fila no es status: "final".

Filtrar eventos finalizadosPermalink for this section

# Solo los finales de los últimos 15 minutos, un deporte
curl "https://api.sharpapi.io/api/v1/gamestate/soccer?status=final" \
  -H "X-API-Key: YOUR_API_KEY"
 
# Exactamente lo que obtenías antes de que existiera el arrastre
curl "https://api.sharpapi.io/api/v1/gamestate?is_live=true" \
  -H "X-API-Key: YOUR_API_KEY"

Ejemplos de SolicitudesPermalink for this section

# Todos los eventos en vivo de cada deporte
curl "https://api.sharpapi.io/api/v1/gamestate" \
  -H "X-API-Key: YOUR_API_KEY"
 
# Un solo deporte
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']})"
    )

Ejemplo de RespuestaPermalink 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"
}

La tercera fila es una fila terminal: el partido terminó unos seis minutos antes de que se construyera esta respuesta, así que se arrastra con status: "final" y su marcador final, y no lleva primary_book, book_count, game_period ni game_clock.

Modelo de Fusión Entre LibrosPermalink for this section

Los campos de cada evento se fusionan a partir del snapshot de livestate de cada sportsbook mediante un algoritmo de tres clases:

• Clase A — Puntuaciones se eligen por consenso: entre los libros con el rango de periodo más avanzado, gana la puntuación total más alta con ≥2 respaldos. Una puntuación atípica reportada por un único libro (común en los primeros segundos de un cambio de marcador, o por un adaptador con mal comportamiento) se rechaza.
• Clase B — Campos temporales (game_period, game_clock) se seleccionan según la dirección del reloj específica del deporte — cuenta atrás frente a cuenta ascendente — y el rango del periodo.
• Clase C — Campos situacionales (possession, corners_*, etc.) se rellenan por prioridad a partir de una clasificación fija de libros.

primary_book indica de qué libro provienen las puntuaciones ganadoras. book_count es el número total de libros que aportaron cualquier estado para el evento en el momento de la fusión.

StreamingPermalink for this section

Cada actualización en vivo que el endpoint REST mostraría en el siguiente poll también dispara un evento gamestate:update en los canales de streaming:

• SSE: GET /api/v1/stream/gamestate
• WebSocket: suscríbete a {channels: ["gamestate"]} en wss://ws.sharpapi.io/ws

Los clientes de streaming reciben un gamestate:snapshot inicial con el estado actual completo (una lista plana de filas de eventos), después eventos gamestate:update que llevan las filas modificadas conforme se fusionan, y eventos gamestate:removed cuando los eventos salen del conjunto en vivo.

Un evento finalizado se queda en el slate transmitido como su fila status: "final" durante la ventana descrita en Eventos finalizados, y se anuncia una vez con un frame gamestate:final.

Avisos de evento finalizadoPermalink for this section

Cuando un evento termina, cada transporte envía un único frame gamestate:final para él. Lleva la fila terminal del evento — la misma forma que la fila REST, más su 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 (el mismo envoltorio {"data": [...]} que 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}]}

• Mismo acceso y mismos filtros que gamestate:update. Si recibes gamestate:update, recibes gamestate:final, y tus filtros sport/league se aplican. Sin acceso a game state no recibes ninguno de los dos.
• WebSocket lo reproduce. Igual que gamestate:update y gamestate:removed, queda en el buffer de replay y se reenvía en una reconexión con from_seq. Los frames de gamestate por SSE no son reanudables.
• Es un aviso, no la única entrega. La misma fila está también en el slate (gamestate:snapshot y gamestate:update) durante toda la ventana.

Rate Limits y CuotasPermalink for this section

Los rate limits siguen tu plan base, no el complemento — las claves Hobby mantienen sus 120 req/min, Pro mantiene 300, Sharp mantiene 1.000, Enterprise personalizado. Consulta Precios . /gamestate cuenta igual que otras llamadas REST en la cuota por minuto.

Resolución de ProblemasPermalink for this section

• 403 tier_restricted con addon: "game_state" — tu clave no tiene el complemento Game State. Añádelo desde Facturación  por $79/mes, o actualiza a Enterprise.
• 400 validation_error con parameter: "status" — el único valor aceptado de ?status= es final. No existe el valor live; las filas en vivo son el conjunto por defecto, o pídelas por separado con ?is_live=true.
• 400 validation_error con parameter: "is_live" — ?is_live= solo acepta true / false. 1 y 0 se rechazan; antes se leían como false y devolvían lo contrario de lo pedido.
• Una fila con status: "final" y is_live: false — no es un fallo. Es un evento finalizado dentro de su ventana de 15 minutos. Filtra con ?is_live=true para el comportamiento anterior.
• Faltan primary_book / book_count — estás leyendo una fila terminal. Comprueba status antes de leer campos que solo existen en vivo.
• Objeto data vacío — no hay eventos en vivo en el ámbito. Esto es habitual entre eventos de calendarios deportivos más pequeños. Vuelve a hacer polling.
• Eventos con stale: true — el libro principal ha quedado en silencio. Las puntuaciones pueden ir con retraso; considera filtrarlos o mostrar un indicador en la interfaz.
• Eventos con aggregator_stale: true — el agregador de SharpAPI no ha refrescado ese deporte en >30s. Si es persistente, contacta con soporte; un breve aumento puede ocurrir durante los redespliegues.
• El mismo partido aparece dos veces bajo event_ids diferentes — limitación conocida en algunas ligas regionales donde los sportsbooks usan nomenclatura de liga inconsistente. Usa (home_team, away_team) como clave secundaria de deduplicación en el cliente hasta que se cierren los huecos de alias restantes.