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. Uma partida que acabou de terminar também permanece aqui por uma janela curta como linha terminal — veja Eventos finalizados.

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

AutenticaçãoPermalink for this section

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

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

Filtros de consultaPermalink for this section

Ambos valem para /api/v1/gamestate e /api/v1/gamestate/{sport}. Os valores não diferenciam maiúsculas e são aparados. Se você omitir os dois, recebe o conjunto padrão: tudo o que está ao vivo, mais as linhas finalizadas que ainda estão dentro da janela de retenção.

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

Envelope da RespostaPermalink for this section

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

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

Temporais (maioria dos esportes em equipe)Permalink for this section

SituacionaisPermalink for this section

Específicos do esportePermalink for this section

AtualidadePermalink for this section

Eventos finalizadosPermalink for this section

Antes, uma partida sumia de /gamestate no instante em que terminava — o placar final só era visível para o cliente que por acaso fizesse polling durante o último ciclo ao vivo. Agora os eventos finalizados permanecem neste endpoint por 15 minutos após a conclusão como linha terminal, de modo que qualquer cliente com um intervalo razoável veja o resultado final pelo menos uma vez.

A janela é do lado do servidor e hoje é de 15 minutos (GAMESTATE_TERMINAL_CARRY_SECONDS, padrão 900). Depois disso a linha some de vez; o resultado encerrado continua disponível em /api/v1/events?status=final, que é a origem da linha terminal.

Como é uma linha 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
}

Os placares finais usam os nomes de campo ao vivo, conforme o esporte. Um esporte por pontos coloca sua contagem em home_score / away_score. Um esporte por sets coloca sua contagem de sets em sets_home / sets_away e não carrega home_score / away_score — um final de tênis é 2-1 em sets, e colocar isso em home_score colidiria com os pontos de game da linha ao 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
}

Quais campos uma linha terminal não carregaPermalink for this section

Uma linha terminal é projetada a partir do registro de conclusão, não de uma mesclagem ao vivo entre books, então estes campos ao vivo simplesmente não existem: primary_book, book_count, game_period, game_clock e todos os campos situacionais (possession, corners_*, power_play, in_play, a família de probabilidade de vitória do tênis, e assim por diante). Leia-os somente depois de conferir que a linha não é status: "final".

Filtrando eventos finalizadosPermalink for this section

# Só os finais dos últimos 15 minutos, um esporte
curl "https://api.sharpapi.io/api/v1/gamestate/soccer?status=final" \
  -H "X-API-Key: YOUR_API_KEY"
 
# Exatamente o que você recebia antes da retenção existir
curl "https://api.sharpapi.io/api/v1/gamestate?is_live=true" \
  -H "X-API-Key: YOUR_API_KEY"

Exemplos de RequisiçãoPermalink for this section

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

A terceira linha é uma linha terminal: a partida terminou cerca de seis minutos antes de esta resposta ser montada, então ela é retida com status: "final" e seu placar final, e não carrega primary_book, book_count, game_period nem game_clock.

Modelo de Mesclagem Cross-BookPermalink for this section

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.

StreamingPermalink for this section

Toda atualização ao vivo 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.

Um evento finalizado continua no slate transmitido como sua linha status: "final" durante a janela descrita em Eventos finalizados, e é anunciado uma vez com um frame gamestate:final.

Avisos de evento finalizadoPermalink for this section

Quando um evento termina, cada transporte envia um único frame gamestate:final para ele. Ele carrega a linha terminal do evento — o mesmo formato da linha REST, mais o 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 (o mesmo envelope {"data": [...]} do 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}]}

• Mesmo acesso e mesmos filtros do gamestate:update. Quem recebe gamestate:update recebe gamestate:final, e seus filtros sport/league se aplicam. Sem acesso a game state, você não recebe nenhum dos dois.
• O WebSocket faz replay. Como gamestate:update e gamestate:removed, ele fica no buffer de replay e é reenviado numa reconexão com from_seq. Frames de gamestate no SSE não são retomáveis.
• É um aviso, não a única entrega. A mesma linha também está no slate (gamestate:snapshot e gamestate:update) durante toda a janela.

Rate Limits e QuotasPermalink for this section

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

• 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.
• 400 validation_error com parameter: "status" — o único valor aceito de ?status= é final. Não existe o valor live; linhas ao vivo são o conjunto padrão, ou peça só elas com ?is_live=true.
• 400 validation_error com parameter: "is_live" — ?is_live= aceita apenas true / false. 1 e 0 são rejeitados; antes eram lidos como false e devolviam o oposto do que se pedia.
• Uma linha com status: "final" e is_live: false — não é bug. É um evento finalizado dentro da janela de 15 minutos. Filtre com ?is_live=true para o comportamento anterior.
• primary_book / book_count ausentes — você está lendo uma linha terminal. Verifique status antes de ler campos que só existem ao vivo.
• 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.