Skip to Content

Eventos

Endpoint unificado para listar e pesquisar eventos com filtragem, paginação e busca.

GET /api/v1/events

Este endpoint substitui os endpoints anteriores /schedule, /events/live e /events/search. Toda a funcionalidade desses endpoints agora está disponível aqui através de parâmetros de consulta. Veja as Notas de Migração abaixo.

AutenticaçãoLink permanente para esta seção

Requer API key via header X-API-Key, header Authorization: Bearer ou parâmetro de consulta api_key. Disponível para todos os tiers.

Parâmetros de ConsultaLink permanente para esta seção

ParâmetroTipoPadrãoDescrição
sportstringtodosFiltrar por esporte. Separados por vírgula para múltiplos (ex: basketball,football). Apenas IDs de esporte; um ID de liga como nba vai em league (detalhes).
leaguestringtodasFiltrar por liga. Separados por vírgula para múltiplos (ex: nba,nfl)
sportsbookstringtodosFiltrar por sportsbook (ex: draftkings,pinnacle)
statusstring—Filtrar por estado do ciclo de vida: upcoming, live ou final. Omitir para o conjunto padrão (upcoming + live). final retorna as conclusões retidas. Um valor não reconhecido é rejeitado com 400 validation_error.
is_liveboolean—true = apenas ao vivo, false = apenas pré-jogo, omitir = ambos
datestring—Filtrar por data no formato YYYY-MM-DD
qstring—Consulta de busca correspondendo a nomes de equipes ou nomes de eventos
limitinteger50Resultados por página (máx 200)
offsetinteger0Offset de paginação

Os parâmetros de consulta usam a forma singular e valores separados por vírgula para múltiplos: sport=basketball,football, e não sports=basketball&sports=football.

Headers de RespostaLink permanente para esta seção

Todas as respostas incluem headers padrão de rate limit e metadados:

HeaderDescrição
X-RateLimit-LimitMáximo de requisições por minuto para o seu tier
X-RateLimit-RemainingRequisições restantes na janela atual
X-RateLimit-ResetTimestamp Unix de quando a janela de rate limit é reiniciada
X-Data-DelayAtraso de dados para o seu tier (ex: 0s, 60s)
X-Request-IdIdentificador único da requisição para depuração

Objeto EventLink permanente para esta seção

CampoTipoDescrição
idstringIdentificador canônico do evento — o mesmo para todos os sportsbooks que cobrem este evento. Use como sua chave primária para correspondência entre sportsbooks. Veja Correspondência de Eventos.
external_idsobjectMapa de ID do sportsbook para o ID nativo do evento naquele sportsbook (ex: {"draftkings": "33483153"}). Use estes para deep linking de volta às páginas dos sportsbooks.
sportstringIdentificador do esporte (ex: basketball, football)
leaguestringSlug da liga (ex: nba, nfl)
home_teamstringNome da equipe da casa
away_teamstringNome da equipe visitante
start_timestringHorário de início do evento em ISO 8601. Ausente em um evento finalizado servido a partir do armazenamento de retenção — verifique a presença da chave, não o status.
completed_atstringHorário de conclusão em ISO 8601. Presente apenas em linhas com status: "final".
statusstringStatus do evento: upcoming, live ou final. final só é retornado quando solicitado com ?status=final. O status é live quando nosso rastreamento de jogos mostra o jogo em andamento, ou quando várias casas de apostas oferecem preços ao vivo nele.
is_livebooleanSe o jogo está ao vivo: true quando status é live.
live_book_countintegerQuantas casas de apostas têm pelo menos um preço ao vivo neste evento. Sempre presente, 0 quando nenhuma. Pode ser maior que 0 em um evento que não está live. Em um evento live, 0 significa que só o nosso rastreamento de jogos mostra o jogo em andamento.
book_countintegerNúmero de sportsbooks com odds para este evento
marketsstring[]Array ordenado dos tipos de mercado disponíveis (ex: ["moneyline", "point_spread", "total_points"])
booksstring[]Array ordenado de IDs de sportsbooks com odds para este evento
game_stateobject | undefinedEstado do jogo ao vivo (presente apenas para eventos ao vivo com placar)

Eventos finalizados. ?status=final retorna as conclusões retidas, da mais recente para a mais antiga — um conjunto de resultados separado, que não faz parte da lista não filtrada. Essas linhas omitem start_time (nenhum horário de início é retido para elas) e trazem completed_at no lugar. Um evento recém-finalizado cujas odds ainda estão em cache mantém seu start_time real, portanto verifique se a chave está presente em vez de ramificar pelo status.

Objeto Game StateLink permanente para esta seção

Incluído quando o evento está ao vivo e tem dados de placar:

CampoTipoDescrição
home_scorenumberPlacar da equipe da casa
away_scorenumber | nullPlacar da equipe visitante
periodstring | nullPeríodo atual (ex: Q3, 2nd, 3rd Period)
clockstring | nullTempo restante (ex: 5:42)
score_typestringTipo de placar (ex: game_points, match)
possessionstring | nullEquipe com posse de bola (home ou away)
is_timeoutboolean | nullSe um timeout está em andamento
power_playstring | nullInformação de power play (home ou away, hóquei)
last_playstring | nullDescrição da última jogada

Exemplos de RequisiçõesLink permanente para esta seção

Listar próximos eventos da NBA e NFLLink permanente para esta seção

curl -X GET "https://api.sharpapi.io/api/v1/events?sport=basketball,football&league=nba,nfl&limit=20" \ -H "X-API-Key: YOUR_API_KEY"

Obter apenas eventos ao vivoLink permanente para esta seção

curl -X GET "https://api.sharpapi.io/api/v1/events?is_live=true" \ -H "X-API-Key: YOUR_API_KEY"

Pesquisar por uma equipeLink permanente para esta seção

curl -X GET "https://api.sharpapi.io/api/v1/events?q=celtics" \ -H "X-API-Key: YOUR_API_KEY"

Filtrar por data e sportsbookLink permanente para esta seção

curl -X GET "https://api.sharpapi.io/api/v1/events?date=2026-02-08&sportsbook=draftkings,fanduel" \ -H "X-API-Key: YOUR_API_KEY"

RespostaLink permanente para esta seção

Sucesso (200)Link permanente para esta seção

{ "data": [ { "id": "evt_nba_bos_lal_20260208", "external_ids": { "draftkings": "33483200", "fanduel": "nba-bos-lal-20260208" }, "sport": "basketball", "league": "nba", "home_team": "Boston Celtics", "away_team": "Los Angeles Lakers", "start_time": "2026-02-08T19:30:00Z", "status": "upcoming", "is_live": false, "live_book_count": 0, "book_count": 6, "markets": ["moneyline", "point_spread", "total_points"], "books": ["betmgm", "caesars", "draftkings", "fanduel"] }, { "id": "evt_nba_gsw_mia_20260208", "external_ids": { "draftkings": "33483205" }, "sport": "basketball", "league": "nba", "home_team": "Golden State Warriors", "away_team": "Miami Heat", "start_time": "2026-02-08T22:00:00Z", "status": "upcoming", "is_live": false, "live_book_count": 0, "book_count": 5, "markets": ["moneyline", "point_spread", "total_points"], "books": ["betmgm", "draftkings", "fanduel"] } ], "meta": { "count": 2, "total": 43, "pagination": { "limit": 50, "offset": 0, "has_more": true, "next_offset": 50 }, "updated_at": "2026-02-08T12:00:00Z", "filters": { "sport": ["basketball"], "league": ["nba"] } } }

Resultados vazios (200): meta.storeLink permanente para esta seção

Quando /events retorna zero eventos, um bloco meta.store é adicionado explicando o motivo — com o mesmo vocabulário de reason de /odds, para que uma única verificação sirva para os dois endpoints. data é [] (antes de setembro de 2026 a lista padrão o serializava como null; ?status=final já retornava []), e pagination carrega count: 0 e total: 0:

{ "data": [], "meta": { "store": { "ready": true, "events": 11064, "reason": "no_match" } }, "pagination": { "limit": 50, "offset": 0, "count": 0, "total": 0, "has_more": false, "next_offset": null }, "updated_at": "2026-09-07T02:41:18.552Z" }
reasonSignificadoO que fazer
warmingA instância que respondeu não concluiu nenhum ciclo de atualização desde a última mudança de modo — nada foi carregado aindaTentar novamente
store_emptyA instância está pronta, mas o cache de eventos a partir do qual esta página foi construída está vazioTentar novamente — não trate a página vazia como definitiva
no_matchA instância está pronta e o cache está populado; seus filtros não corresponderam a nadaDefinitivo — tentar novamente não mudará a resposta
CampoTipoSignificado
readybooleanPelo menos um ciclo de atualização foi concluído desde a última mudança de modo da instância.
eventsintegerEventos no cache a partir do qual esta página foi construída, independentemente dos seus filtros. Páginas com ?status=final são servidas a partir do store de eventos encerrados e informam o tamanho desse store.
reasonstringwarming, store_empty ou no_match — veja acima.

meta.store está presente apenas em resultados vazios; uma resposta com eventos não muda. Não há generation aqui, de propósito — esse contador pertence ao store de odds, que não alimenta este endpoint. Um valor desconhecido de league ou sportsbook é rejeitado com 400 invalid_filter em vez de respondido com uma página vazia.

Respostas de ErroLink permanente para esta seção

401 Unauthorized

Se nenhuma chave for enviada, retorna missing_api_key; uma chave inválida retorna invalid_api_key.

{ "error": { "code": "missing_api_key", "message": "API key required. Pass via X-API-Key header, api_key query parameter, or Bearer token.", "docs": "https://docs.sharpapi.io/en/authentication" } }

400 Bad Request

{ "error": { "code": "validation_error", "message": "Invalid date format. Use YYYY-MM-DD.", "docs": "https://docs.sharpapi.io/en/api-reference/events" } }

429 Rate Limited

{ "error": { "code": "rate_limited", "message": "Rate limit exceeded. Upgrade your tier for higher limits.", "docs": "https://docs.sharpapi.io/en/pricing" } }

Migração de Endpoints AnterioresLink permanente para esta seção

Vários sub-caminhos legados de eventos de versões anteriores da API são mantidos como sinalizadores de descontinuação — acessá-los retorna 410 Gone com uma dica legível por máquina apontando para o endpoint correto.

Caminho DescontinuadoUse no Lugar
GET /events/search?q=celticsGET /events?q=celtics
GET /events/listGET /events
GET /events/allGET /events
GET /events/findGET /events

Formato da Resposta 410Link permanente para esta seção

{ "error": { "code": "unknown_endpoint", "message": "There is no /api/v1/events/search endpoint. Use GET /api/v1/events — results can be filtered with ?sport=, ?league=, and ?book= query parameters.", "correct_endpoint": "/api/v1/events", "docs": "https://docs.sharpapi.io/api-reference" } }

Respostas pré-v1 usavam nomes de campos em camelCase (homeTeam, awayTeam, isLive, bookCount). A API v1 usa snake_case exclusivamente (home_team, away_team, is_live, book_count). Atualize o código do seu cliente conforme necessário.

Principais mudanças em relação às versões anterioresLink permanente para esta seção

  • Os nomes dos campos agora são snake_case (ex: home_team em vez de homeTeam)
  • A resposta usa o envelope padrão data/meta em vez de um array events no nível superior
  • Os parâmetros de consulta usam a forma singular (sport em vez de sports)
  • A URL base é https://api.sharpapi.io (não https://sharpapi.io)
  • A paginação agora inclui os campos has_more e next_offset

Correspondência de Eventos Entre SportsbooksLink permanente para esta seção

O campo id é um identificador canônico de evento — o mesmo evento do mundo real recebe o mesmo id independentemente de qual sportsbook ele venha. Use-o como sua chave primária ao construir ferramentas de comparação entre sportsbooks. O campo external_ids mapeia cada sportsbook para seu ID nativo de evento para deep linking.

Veja Correspondência de Eventos para detalhes completos sobre como funcionam os IDs canônicos.

Endpoints RelacionadosLink permanente para esta seção

Last updated on