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âmetro | Tipo | Descrição |
|---|---|---|
sport | string | (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âmetro | Aceito | Descrição |
|---|---|---|
status | final, unconfirmed | final 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_live | true, false | true 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
| Campo | Tipo | Notas |
|---|---|---|
home_team | string | Nome normalizado do time da casa |
away_team | string | Nome normalizado do time visitante |
sport | string | Bucket de esporte (baseball, soccer, …) |
league | string | ID da liga no Atlas (ex. mlb, england_-_premier_league) |
home_score | integer | Placar atual da casa na unidade natural do esporte (corridas, pontos, gols, sets — tênis usa pontos somados de sets) |
away_score | integer | Placar atual do visitante |
is_live | boolean | true em um evento ao vivo. false em uma linha finalizada retida — veja Eventos finalizados |
primary_book | string | O book de onde os placares mesclados foram selecionados. Respeita o consenso — books de maior qualidade vencem empates |
book_count | integer | Nú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
| Campo | Tipo | Notas |
|---|---|---|
aliases | string[] | 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/oddsO 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
| Campo | Tipo | Exemplo |
|---|---|---|
game_period | string | "T5" (MLB topo do 5º), "Q3" (NBA Q3), "2H" (futebol 2º tempo), "P2" (NHL), "S2" (tênis 2º set), "FT" (tempo final) |
game_clock | string | "49:06" para esportes com contagem progressiva (futebol), "5:42" para esportes com contagem regressiva (basquete, hóquei) |
period_number | integer | game_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
| Campo | Tipo | Notas |
|---|---|---|
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_play | string | Descrição da última jogada específica do esporte, quando disponível |
is_timeout | boolean | true durante um timeout |
Específicos do esporteLink permanente para esta seção
| Campo | Esporte | Tipo |
|---|---|---|
fouls_home, fouls_away | basketball, soccer | integer |
corners_home, corners_away | soccer | integer |
yellow_cards_home, yellow_cards_away | soccer | integer |
red_cards_home, red_cards_away | soccer | integer |
cards_home, cards_away | soccer | integer — total de cartões, de books que relatam um total em vez da divisão amarelos / vermelhos |
power_play | hockey | "home" | "away" |
sets_home, sets_away | tennis | integer (sets vencidos) |
hits_home, hits_away | baseball | integer |
home_pitcher, away_pitcher | baseball | string — nome de exibição do arremessador titular |
wickets_home, wickets_away | cricket | integer |
overs | cricket | float |
batting_team | cricket | "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.
| Campo | Esporte | Tipo | Notas |
|---|---|---|---|
regulation_periods | basketball, football, hockey, soccer, baseball | integer | Perí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_seconds | basketball, football, hockey, soccer | integer | Duraçã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_sets | tennis | integer | 3 (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
| Campo | Tipo | Significado |
|---|---|---|
stale | true (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_stale | true (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
}| Campo | Tipo | Notas |
|---|---|---|
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_at | string | ISO 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_live | false | Sempre false de forma explícita, para que qualquer renderização condicionada a is_live trate a linha como não ao vivo. |
stale | false | Sempre 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 um0-0semwinnernã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ê quer | Requisiçã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.
| Campo | Tipo | Notas |
|---|---|---|
status | "unconfirmed" | O jogo saiu do feed ao vivo sem um estado de fim de jogo. |
last_seen_at | string | RFC 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_score | integer | O último placar visto, em um esporte por pontos. |
sets_home / sets_away | integer | A ú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_clock | string | Como foram vistos pela última vez. Omitidos quando a linha ao vivo não os tinha. |
is_live | false | Sempre false de forma explícita. |
stale | false | Sempre 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
cURL
# 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:
- SSE:
GET /api/v1/stream/gamestate - WebSocket: assine
{channels: ["gamestate"]}emwss://ws.sharpapi.io/ws
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 recebegamestate:updaterecebegamestate:final, e seus filtrossport/leaguese aplicam. Sem acesso a game state, você não recebe nenhum dos dois. - O WebSocket faz replay. Como
gamestate:updateegamestate:removed, ele fica no buffer de replay e é reenviado numa reconexão comfrom_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:snapshotegamestate: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 comogamestate: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_restrictedcomaddon: "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_errorcomparameter: "status"— os valores aceitos de?status=sãofinaleunconfirmed. Não existe o valorlive; linhas ao vivo são o conjunto padrão, ou peça só elas com?is_live=true. - 400
validation_errorcomparameter: "is_live"—?is_live=aceita apenastrue/false.1e0são rejeitados; antes eram lidos comofalsee devolviam o oposto do que se pedia. - Uma linha com
status: "final"eis_live: false— não é bug. É um evento finalizado dentro da janela de 15 minutos. Filtre com?is_live=truepara o comportamento anterior. - Uma linha com
status: "unconfirmed"e semwinner— 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=truetambém exclui essas linhas. primary_book/book_countausentes — você está lendo uma linha terminal ou não confirmada. Verifiquestatusantes de ler campos que só existem ao vivo.- Objeto
datavazio — 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_idde uma linha de odds não tem linha de estado de jogo — o jogo pode estar listado sob outro id, com este em seusaliases. 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 comaliases. 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.