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.

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

Autenticación

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 Ruta

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

Sobre de Respuesta

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

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 presentes

Temporales (la mayoría de deportes de equipo)

Situacionales

Específicos por deporte

Frescura

Ejemplos de Solicitudes

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

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

Modelo de Fusión Entre Libros

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.

Streaming

Cada actualización 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.

Rate Limits y Cuotas

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 Problemas

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