Skip to Content
Referência da APIEstado do Jogo ao Vivo

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çãoLink permanente para esta seçã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.

A recusa também traz upgrade e upgrade_note, e a sua message termina com o preço do add-on e um link (Campos de upgrade). Em um plano pago, o link abre o add-on na sua página de billing; no Free ele aponta para a página de preços, pois add-ons exigem um plano pago. Uma key Hobby recebe:

{ "error": { "code": "tier_restricted", "message": "This endpoint requires the Game State add-on or Enterprise tier. Try the Game State add-on free for 72 hours ($79/mo after, if eligible): https://sharpapi.io/dashboard/billing?addon=game_state", "docs": "https://sharpapi.io/pricing", "tier": "hobby", "addon": "game_state", "upgrade": "https://sharpapi.io/dashboard/billing?addon=game_state", "upgrade_note": "Try the Game State add-on free for 72 hours ($79/mo after, if eligible)" } }

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 PathLink permanente para esta seção

ParâmetroTipoDescrição
sportstring(opcional) Esporte único a ser retornado. Corresponde a um esporte conhecido do Atlas (soccer, tennis, esports, basketball, table_tennis, baseball, hockey, cricket, volleyball, handball, football, olympics, darts, boxing, rugby_league, mma, aussie_rules, snooker, rugby_union, golf, floorball, water_polo, lacrosse, futsal, other). Não diferencia maiúsculas/minúsculas. Um esporte desconhecido retorna um objeto data vazio — e um esporte suportado sem nada ao vivo no momento também; veja a nota abaixo.

Um objeto data vazio não significa que o esporte não é suportado. O game state é mesclado por esporte em uma chave gamestate:{sport} com TTL de 60 segundos (GAMESTATE_TTL, deliberadamente o dobro da janela livestate de 30 segundos); sem nada ao vivo a chave expira e a resposta é {"data":{}}, idêntica à de um esporte não coberto. Vários dos esportes acima são sazonais.

Use GET /api/v1/sports para ver event_count e live_count por esporte. other é o bucket de reserva para esportes que o Atlas não mapeou.

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

Filtros de consultaLink permanente para esta seção

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 e não confirmadas que ainda estão dentro da janela de retenção.

ParâmetroAceitoDescrição
statusfinal, unconfirmedfinal retorna apenas as linhas finalizadas retidas — o espelho de /events?status=final. unconfirmed retorna apenas as linhas não confirmadas: jogos que saíram do feed ao vivo sem um estado de fim de jogo. Qualquer outro valor é um 400 validation_error com accepted: ["final", "unconfirmed"] (veja abaixo). Não existe o valor live: linhas ao vivo são o conjunto padrão, e ?is_live=true pede só elas.
is_livetrue, falsetrue retorna apenas linhas ao vivo, o que exclui todas as linhas finalizadas e não confirmadas. false retorna apenas linhas não ao vivo, o que inclui as linhas finalizadas e não confirmadas ainda dentro da janela de retenção. Qualquer outro valor — incluindo 1 e 0 — é um 400 validation_error.

Um valor não reconhecido é rejeitado, não ignorado. Tanto ?status=zzz quanto ?is_live=1 retornam 400 com um corpo validation_error que nomeia o conjunto aceito, em vez de devolver silenciosamente as linhas sem filtro ou as do lado errado.

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

Antes ?is_live=1 era lido como false e devolvia exatamente as linhas que quem chamava queria excluir; agora é um 400. Se você envia 1 / 0, mude para true / false.

Envelope da RespostaLink permanente para esta seção

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

Um jogo que os sportsbooks registram com event_ids diferentes aparece uma única vez: a linha é indexada por um deles e lista os outros em aliases.

Campos do Estado do EventoLink permanente para esta seção

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 presentesLink permanente para esta seção

CampoTipoNotas
home_teamstringNome normalizado do time da casa
away_teamstringNome normalizado do time visitante
sportstringBucket de esporte (baseball, soccer, …)
leaguestringID da liga no Atlas (ex. mlb, england_-_premier_league)
home_scoreintegerPlacar atual da casa na unidade natural do esporte (corridas, pontos, gols, sets — tênis usa pontos somados de sets)
away_scoreintegerPlacar atual do visitante
is_livebooleantrue em um evento ao vivo. false em uma linha finalizada retida — veja Eventos finalizados
primary_bookstringO book de onde os placares mesclados foram selecionados. Respeita o consenso — books de maior qualidade vencem empates
book_countintegerNúmero de sportsbooks que contribuíram com estado ao vivo para este evento no momento da mesclagem

“Sempre presentes” significa sempre presentes em uma linha ao vivo. Uma linha finalizada retida é montada a partir do registro de conclusão, não de uma mesclagem ao vivo, então não carrega primary_book nem book_count, e nenhum game_period / game_clock. Os campos de placar também dependem do esporte: esportes por sets carregam sets_home / sets_away em vez de home_score / away_score. Verifique status === "final" antes de ler qualquer um desses campos. A forma terminal completa está em Eventos finalizados. Uma linha não confirmada (status: "unconfirmed") também não tem primary_book nem book_count, mas mantém game_period / game_clock como foram vistos pela última vez.

Uma linha por jogo: aliasesLink permanente para esta seção

CampoTipoNotas
aliasesstring[]Os outros event_ids que se referem a este mesmo jogo, em ordem alfabética. Nunca inclui o próprio event_id da linha. Presente apenas quando o jogo é conhecido por mais de um id; omitido caso contrário, nunca null nem []

Os sportsbooks às vezes registram um jogo com nomes de liga diferentes, o que lhe dá um event_id diferente em cada book. A SharpAPI os mescla em uma única linha: o jogo aparece uma vez, sob um event_id, e aliases lista os demais.

As linhas de odds e as oportunidades do jogo podem carregar qualquer um desses ids. Para encontrar o estado do jogo de uma linha de odds, compare o event_id dela com a chave da linha ou com qualquer id em aliases:

// data = body.data de GET /api/v1/gamestate const byId = new Map(); for (const rows of Object.values(data)) { for (const [eventId, state] of Object.entries(rows)) { byId.set(eventId, state); for (const alias of state.aliases ?? []) byId.set(alias, state); } } const state = byId.get(odd.event_id); // odd = uma linha de /api/v1/odds

O campo é igual no REST e nas linhas de streaming. Apenas linhas ao vivo o carregam: linhas terminais e não confirmadas não.

Desde 2026-11-12: procure os ids também em aliases. Antes, um jogo mesclado aparecia uma vez por id, cada linha com o mesmo estado, então qualquer um dos seus ids o encontrava como chave. Agora só um encontra. Código que busca o estado do jogo pelo event_id de uma linha de odds precisa verificar também aliases, ou não vai encontrar esses jogos. Código que descartava as linhas repetidas continua funcionando.

Temporais (maioria dos esportes em equipe)Link permanente para esta seção

CampoTipoExemplo
game_periodstring"T5" (MLB topo do 5º), "Q3" (NBA Q3), "2H" (futebol 2º tempo), "P2" (NHL), "S2" (tênis 2º set), "FT" (tempo final)
game_clockstring"49:06" para esportes com contagem progressiva (futebol), "5:42" para esportes com contagem regressiva (basquete, hóquei)
period_numberintegergame_period como número, para ordenar e comparar o andamento do jogo: "Q3" → 3, "2H" → 2, "S2" → 2; o topo e o fim de uma entrada compartilham o número ("T8" e "B8" → 8). A prorrogação continua a contagem após o tempo regulamentar: "OT" → 5 e "OT2" → 6 num jogo de quatro quartos, prorrogação do futebol "ET" → 3. Omitido (nunca null) quando o período não tem número ("HT", "SO", "PK", "FT") e em todos os esportes exceto baseball, basketball, football, hockey, soccer e tennis. Como regulation_periods muda o número da prorrogação: Estrutura da partida

SituacionaisLink permanente para esta seção

CampoTipoNotas
possession"home" | "away"Qual time tem a posse (esportes em equipe) ou está sacando (tênis)
server"home" | "away"Apenas tênis — sacador atual
last_playstringDescrição da última jogada específica do esporte, quando disponível
is_timeoutbooleantrue durante um timeout

Específicos do esporteLink permanente para esta seção

CampoEsporteTipo
fouls_home, fouls_awaybasketball, soccerinteger
corners_home, corners_awaysoccerinteger
yellow_cards_home, yellow_cards_awaysoccerinteger
red_cards_home, red_cards_awaysoccerinteger
cards_home, cards_awaysoccerinteger — total de cartões, de books que relatam um total em vez da divisão amarelos / vermelhos
power_playhockey"home" | "away"
sets_home, sets_awaytennisinteger (sets vencidos)
hits_home, hits_awaybaseballinteger
home_pitcher, away_pitcherbaseballstring — nome de exibição do arremessador titular
wickets_home, wickets_awaycricketinteger
overscricketfloat
batting_teamcricket"home" | "away"

Cartões vermelhos. No futebol, um red_cards_home / red_cards_away explícito igual a 0 significa que um book que cobre o evento não relatou nenhum vermelho. Se ambos os campos estiverem ausentes, nenhum book que cobre a partida relatou cartões: isso não é zero, e os campos nunca são null.

Os campos de contagem só aparecem quando foram relatados. corners_*, fouls_*, cards_*, yellow_cards_*, red_cards_* e as demais contagens por time aparecem apenas quando um book que cobre o evento as relatou. Um zero relatado é 0; um campo ausente significa desconhecido, nunca 0, portanto não atribua zero a uma contagem ausente. As contagens que um evento carrega dependem dos books que o cobrem: quando vários books cobrem um evento, cada contagem vem do book de maior ranking que a relatou (Classe C no Modelo de Mesclagem Cross-Book). O bloco opcional stats por time é montado a partir desses mesmos campos e segue a mesma regra: uma contagem só é listada ali quando está presente.

Estrutura da partidaLink permanente para esta seção

Como o evento está programado. Estes três campos vêm dos dados de evento da DraftKings, então só aparecem numa linha ao vivo para a qual a DraftKings contribuiu na mesclagem, e só quando a DraftKings publicou o valor. Caso contrário, o campo é omitido (nunca null) — confira se a chave existe antes de lê-la. Linhas de eventos finalizados nunca os carregam.

CampoEsporteTipoNotas
regulation_periodsbasketball, football, hockey, soccer, baseballintegerPeríodos regulamentares, sem contar a prorrogação. Valores típicos: NBA e NFL 4, basquete universitário masculino 2 (tempos), basquete universitário feminino 4, NHL 3, futebol 2, MLB 9 (entradas)
period_length_secondsbasketball, football, hockey, soccerintegerDuração de um período regulamentar no relógio de jogo, em segundos. Valores típicos: NBA 720, NFL e futebol americano universitário 900, basquete universitário masculino 1200, basquete universitário feminino 600, NHL 1200, futebol 2700. Nunca enviado para baseball
best_of_setstennisinteger3 (melhor de três sets) ou 5 (melhor de cinco)

Quando uma linha carrega regulation_periods, period_number conta a prorrogação a partir desse valor, e não do formato habitual do esporte. Um jogo de basquete universitário masculino tem dois tempos, então sua primeira prorrogação é period_number 3; com o padrão de quatro quartos seria 5. Linhas sem o campo usam o formato habitual: quatro quartos para basketball e football, três períodos para hockey, dois tempos para soccer.

AtualidadeLink permanente para esta seção

CampoTipoSignificado
staletrue (omitido caso contrário)O TTL da chave de livestate do primary_book caiu abaixo do limite de atualidade do agregador (~10s) no momento da mesclagem. Os placares são os últimos valores conhecidos; o book ficou em silêncio. Trate os placares e o período do evento como potencialmente atrasados em relação ao estado real do jogo.
aggregator_staletrue (omitido caso contrário)O próprio agregador SharpAPI não escreveu um novo shard gamestate:{sport} para este esporte em mais de ~30s. Sinal mais amplo do que stale — indica um soluço no pipeline, não um problema isolado de um book. Se você ver isso de forma persistente, entre em contato com o suporte.

Ausência = atualizado. Tanto stale quanto aggregator_stale só são escritos quando verdadeiros, mantendo o payload compacto. Se você não os vê em um evento, os dados são considerados atualizados.

Eventos finalizadosLink permanente para esta seção

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 a partir do momento em que aparecem como finais 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 terminalLink permanente para esta seção

{ "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 }
CampoTipoNotas
status"final" | "unconfirmed"Presente apenas em uma linha retida: "final" em uma linha terminal, "unconfirmed" em uma linha não confirmada. Linhas ao vivo não carregam nenhuma chave status, então status === "final" é o teste confiável — não deduza a partir de is_live. Uma linha "final" ainda pode voltar a "unconfirmed" enquanto outra fonte contesta o seu placar, então não trate um final como irreversível no momento em que o vê.
completed_atstringISO 8601 — quando a SharpAPI detectou a conclusão, não o apito final oficial da liga. A janela de retenção não é medida a partir deste timestamp, e sim de quando a linha apareceu como final pela primeira vez, normalmente poucos minutos depois dele. Um jogo confirmado como final depois de sair do feed ao vivo pode aparecer como final muito depois do seu completed_at.
score_type"points" | "sets"Quais campos carregam o resultado. "sets" para os esportes por sets (tennis, table_tennis, volleyball, badminton); "points" em todo o resto.
winner"home" | "away" | "draw"Opcional — omitido quando o resultado não pode ser determinado; veja abaixo. "draw" só é produzido em esportes nos quais um placar igual é um resultado real (soccer, hockey, football, rugby_union, rugby_league).
is_livefalseSempre false de forma explícita, para que qualquer renderização condicionada a is_live trate a linha como não ao vivo.
stalefalseSempre false de forma explícita. É o único lugar em que stale aparece sem ser verdadeiro — a regra “ausência = atualizado” acima vale só para linhas ao vivo.

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 }

winner pode faltar, e isso significa algo. O campo é omitido quando o resultado registrado não encerra a partida:

  • um placar igual em um esporte que não admite empate (basquete, handebol, esports, beisebol…) — o jogo foi para a prorrogação, foi abandonado, ou o feed parou antes da decisão;
  • uma contagem de sets sub-terminal em um esporte por sets (quem lidera com menos de dois sets não pode ter vencido nenhum formato);
  • um snapshot cujos placares nunca chegaram, registrado como 0-0. Por isso um 0-0 sem winner não é o mesmo que um empate sem gols real — o real carrega "winner": "draw".

Trate um winner ausente como “não decidido”, não como empate. Se você está gradando ou liquidando algo, pule essas linhas.

Quais campos uma linha terminal não carregaLink permanente para esta seção

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, period_number, os campos de estrutura da partida 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 tem a chave status.

Filtrando eventos finalizadosLink permanente para esta seção

O que você querRequisição
Só linhas ao vivo (comportamento anterior à retenção)?is_live=true
Só linhas finalizadas?status=final
Só linhas não confirmadas?status=unconfirmed
Todas elas (padrão)nenhum parâmetro
# 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"

Se um evento finalizado ainda estiver ao vivo em algum lugar, a linha ao vivo vence. Um event_id que aparece tanto no conjunto ao vivo quanto no retido é retornado uma única vez, como linha ao vivo. Um book que ainda precifica o jogo o mantém ao vivo até que todos o tenham largado.

Jogos não confirmadosLink permanente para esta seção

Às vezes o feed ao vivo para de carregar um jogo antes de mostrar o fim da partida. Esse jogo não some mais de /gamestate. Ele permanece pela mesma janela de retenção de 15 minutos, contada a partir da última vez em que foi visto ao vivo, como uma linha não confirmada:

{ "home_team": "CSU Bakersfield", "away_team": "North Dakota State", "sport": "basketball", "league": "ncaab", "home_score": 91, "away_score": 80, "score_type": "points", "game_period": "2H", "game_clock": "0:17", "status": "unconfirmed", "last_seen_at": "2026-11-09T00:53:55Z", "is_live": false, "stale": false }

O placar é o último visto. Ele não é um resultado final, então não gradue nem liquide com base nele.

CampoTipoNotas
status"unconfirmed"O jogo saiu do feed ao vivo sem um estado de fim de jogo.
last_seen_atstringRFC 3339, UTC. A última vez em que o jogo foi visto ao vivo. A janela de retenção é medida a partir deste timestamp.
home_score / away_scoreintegerO último placar visto, em um esporte por pontos.
sets_home / sets_awayintegerA última contagem de sets vista, em um esporte por sets (tennis, table_tennis, volleyball, badminton), em vez de home_score / away_score, como em uma linha terminal.
score_type"points" | "sets"Quais campos de placar a linha carrega. Omitido quando a última linha ao vivo tinha um placar incompleto; veja abaixo.
game_period / game_clockstringComo foram vistos pela última vez. Omitidos quando a linha ao vivo não os tinha.
is_livefalseSempre false de forma explícita.
stalefalseSempre false de forma explícita.

Uma linha não confirmada não tem winner nem completed_at, porque nada indica que o jogo terminou. Como uma linha terminal, ela não tem primary_book, book_count nem campos situacionais.

Um placar incompleto é repassado como foi visto. Em um esporte por sets, a última linha ao vivo às vezes não tem uma ou as duas contagens de sets, e pode carregar apenas home_score / away_score ou games_home / games_away. No críquete, o lado que ainda não rebateu não tem placar. A linha não confirmada carrega então exatamente os campos de placar que a linha ao vivo tinha, com os mesmos nomes, e sem score_type. Um lado ausente não é preenchido com 0:

{ "home_team": "Andrey Shmakov", "away_team": "Dmitry Kutenkov", "sport": "table_tennis", "league": "russia_-_liga_pro", "sets_home": 2, "game_period": "S3", "status": "unconfirmed", "last_seen_at": "2026-11-09T00:58:05Z", "is_live": false, "stale": false }

Um jogo cuja última linha ao vivo não tinha nenhum placar utilizável não é retido como não confirmado. Ele sai de /gamestate quando o feed ao vivo para de carregá-lo.

Quando um jogo não confirmado se torna finalLink permanente para esta seção

Uma linha não confirmada se torna uma linha terminal status: "final", com winner e completed_at, de uma de duas formas:

  • o feed ao vivo acaba mostrando o fim do jogo, ou
  • a SharpAPI confirma o resultado final a partir de outra fonte.

Ela nunca aparece como final antes que uma dessas coisas aconteça. A linha final é então retida por 15 minutos a partir desse momento, não a partir do seu completed_at. Se nenhuma delas acontecer dentro da janela de retenção, a linha não confirmada sai de /gamestate quando a janela termina, e uma confirmação que chegue depois traz o jogo de volta como linha final pelos seus 15 minutos. Se o jogo voltar ao feed ao vivo, a linha ao vivo a substitui, como no callout acima. Um final cujo placar outra fonte contesta também pode voltar a unconfirmed até que a contestação seja resolvida.

unconfirmed significa o mesmo em /events/{eventId}, que mostra o último placar visto em last_seen.

# Jogos que saíram do feed sem um estado de fim de jogo, últimos 15 minutos curl "https://api.sharpapi.io/api/v1/gamestate?status=unconfirmed" \ -H "X-API-Key: YOUR_API_KEY"

Exemplos de RequisiçãoLink permanente para esta seçã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"

Exemplo de RespostaLink permanente para esta seção

{ "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, "aliases": ["argentina_-_liga_profesional_bocajuniors_defensayjusticia_2026-04-23"] }, "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 primeira linha é um jogo que alguns books registram com outro nome de liga, então seu outro event_id está em aliases. 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-BookLink permanente para esta seção

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.

StreamingLink permanente para esta seção

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:

Clientes de streaming recebem um gamestate:snapshot inicial com o estado atual completo — linhas ao vivo mais as linhas finalizadas e não confirmadas ainda dentro da janela de retenção, como 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. Um jogo que sai sem um estado de fim de jogo continua no slate como sua linha status: "unconfirmed" durante a janela, enviada como gamestate:update; no WebSocket, seu gamestate:removed só chega quando a janela termina. Nos dois transportes, uma linha com a chave status (final ou unconfirmed) não está ao vivo. Para cruzar linhas de odds, indexe também cada linha sob seus aliases e atualize essas entradas sempre que a linha mudar ou for removida.

Avisos de evento finalizadoLink permanente para esta seção

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.
  • Nunca para uma linha não confirmada. Um jogo que saiu sem um estado de fim de jogo não é anunciado; sua linha status: "unconfirmed" chega apenas como gamestate:update.

“Uma vez por evento” pode se repetir ocasionalmente — deduplique por (event_id, completed_at). Você pode receber gamestate:final mais de uma vez para o mesmo evento. event_id e completed_at são idênticos em toda repetição: descarte um frame cujo par você já processou. Isso é sempre seguro, porque a linha continua no slate.

Rate Limits e QuotasLink permanente para esta seção

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 ProblemasLink permanente para esta seção

  • 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" — os valores aceitos de ?status= são final e unconfirmed. 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.
  • Uma linha com status: "unconfirmed" e sem winner — não é bug. O jogo saiu do feed ao vivo sem um estado de fim de jogo; o placar é o último visto, não um resultado. Veja Jogos não confirmados. ?is_live=true também exclui essas linhas.
  • primary_book / book_count ausentes — você está lendo uma linha terminal ou não confirmada. 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.
  • O event_id de uma linha de odds não tem linha de estado de jogo — o jogo pode estar listado sob outro id, com este em seus aliases. Procure o id lá também.
  • Mesma partida aparece duas vezes sob diferentes event_ids — menos comum desde 2026-11-12, quando um jogo registrado com nomes de liga diferentes passou a ser uma única linha com aliases. Ainda pode acontecer, por exemplo quando os books escrevem o nome de um time de forma diferente, e um jogo finalizado ou não confirmado pode ser retido sob mais de um id. Se você deduplica por (home_team, away_team), compare também o placar: os mesmos dois times podem jogar duas vezes no mesmo dia.
Last updated on