Estado de Jogo ao Vivo

Estado agregado de jogos ao vivo — placares, períodos, cronômetros, posse de bola e dados situacionais específicos do esporte — mesclados entre sportsbooks em uma única visão autoritativa por evento. Uma linha por partida ao vivo, selecionada por consenso entre os books que a cobrem.

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

Autenticação

Requer API key. Disponível no add-on Game State (US$ 79/mês) ou no tier Enterprise. Keys sem nenhum dos dois recebem 403 tier_restricted com addon: "game_state" no corpo do erro. Adicione o add-on pela página de billing  em qualquer plano pago (Hobby / Pro / Sharp); keys Enterprise já o incluem.

O estado de jogo ao vivo também é transmitido pelo canal gamestate via SSE e WebSocket — veja Streaming abaixo. (O acesso ao streaming requer o add-on WebSocket ou Enterprise, além do requisito de Game State acima.)

Parâmetros de Path

Sem o parâmetro de path, retorna todos os esportes com eventos ao vivo.

Envelope da Resposta

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

Cada estado de evento é indexado pelo seu event_id canônico dentro do bucket do esporte. updated_at é o horário do servidor quando esta resposta foi construída — use-o para avaliar a atualidade se estiver fazendo polling.

Campos do Estado do Evento

Todos os campos são opcionais, exceto onde indicado. A presença varia por esporte — eventos de tênis carregam sets_home / server; eventos de hóquei carregam power_play; eventos de futebol carregam corners_* / yellow_cards_*; etc.

Sempre presentes

Temporais (maioria dos esportes em equipe)

Situacionais

Específicos do esporte

Atualidade

Exemplos de Requisição

# Todos os eventos ao vivo de todos os esportes
curl "https://api.sharpapi.io/api/v1/gamestate" \
  -H "X-API-Key: YOUR_API_KEY"
 
# Um esporte
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']})"
    )

Exemplo de Resposta

{
  "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 Mesclagem Cross-Book

Os campos de cada evento são mesclados a partir do snapshot de livestate de cada sportsbook por meio de um algoritmo de três classes:

• Classe A — Placares são escolhidos por consenso: entre os books no rank de período mais avançado, vence o placar de maior total com ≥2 apoiadores. Um único book relatando um placar discrepante (comum nos primeiros segundos de uma mudança de placar, ou de um adapter com mau funcionamento) é rejeitado.
• Classe B — Campos temporais (game_period, game_clock) são selecionados pela direção do cronômetro de acordo com o esporte — regressivo vs progressivo — e rank de período.
• Classe C — Campos situacionais (possession, corners_*, etc.) são preenchidos por prioridade a partir de um ranking fixo de books.

primary_book informa de qual book vieram os placares vencedores. book_count é o número total de books que contribuíram com qualquer estado para o evento no momento da mesclagem.

Streaming

Toda atualização que o endpoint REST exibiria no próximo poll também dispara um evento gamestate:update nos canais de streaming:

• SSE: GET /api/v1/stream/gamestate
• WebSocket: assine {channels: ["gamestate"]} em wss://ws.sharpapi.io/ws

Clientes de streaming recebem um gamestate:snapshot inicial com o estado atual completo (uma lista plana de linhas de eventos), depois eventos gamestate:update carregando linhas alteradas conforme são mescladas, e eventos gamestate:removed quando eventos saem do conjunto ao vivo.

Rate Limits e Quotas

Os rate limits seguem o seu tier base, não o add-on — keys Hobby mantêm seus 120 req/min, Pro mantêm 300, Sharp mantêm 1.000, Enterprise customizado. Veja Pricing . /gamestate conta da mesma forma que outras chamadas REST para a quota por minuto.

Solução de Problemas

• 403 tier_restricted com addon: "game_state" — sua key não tem o add-on Game State. Adicione-o pela Billing  por US$ 79/mês, ou faça upgrade para Enterprise.
• Objeto data vazio — não há eventos ao vivo no escopo. Isso é comum entre eventos em calendários de esportes menores. Faça polling novamente.
• Eventos com stale: true — o book primário ficou em silêncio. Os placares podem estar atrasados; considere filtrá-los ou exibir um indicador de UI.
• Eventos com aggregator_stale: true — o agregador SharpAPI não atualizou esse esporte em >30s. Se persistente, entre em contato com o suporte; um pico breve pode acontecer durante redeploys.
• Mesma partida aparece duas vezes sob diferentes event_ids — limitação conhecida para algumas ligas regionais onde os sportsbooks usam nomenclatura de liga inconsistente. Use (home_team, away_team) como uma chave secundária de deduplicação no cliente até que as lacunas restantes de aliases sejam fechadas.