Documentação da API
API REST completa para dados esportivos em tempo real. Placares ao vivo, odds de apostas com 14 mercados, estatísticas por jogador, elencos, classificação e notícias — tudo que você precisa para montar sua plataforma de apostas.
URL Base
https://magosport.com.br/api/v1
Autenticação
Toda requisição precisa de uma API Key válida. Você pode enviá-la de três formas:
Header (Recomendado)
Use o header X-API-Key: sua_key em todas as requisições.
Authorization Bearer
Use Authorization: Bearer sua_key como header padrão OAuth.
Query String
Adicione ?api_key=sua_key na URL. Útil para testes rápidos.
Exemplos de autenticação
# Via header (recomendado)
curl -H "X-API-Key: sua_api_key" https://magosport.com.br/api/v1/scoreboard/soccer
# Via Authorization Bearer
curl -H "Authorization: Bearer sua_api_key" https://magosport.com.br/api/v1/scoreboard/soccer
# Via query string
curl "https://magosport.com.br/api/v1/scoreboard/soccer?api_key=sua_api_key"
Rate Limiting
Os limites variam por plano. Os headers de resposta informam o consumo atual:
Free
60
req / hora
5,000 /mês
Starter
500
req / hora
150,000 /mês
Pro
2,000
req / hora
1,000,000 /mês
Enterprise
∞
req / hora
ilimitado/mês
Headers de resposta
X-RateLimit-Limit: 500 # Limite do seu plano (req/hora)
X-RateLimit-Remaining: 487 # Requisições disponíveis nesta janela
X-RateLimit-Reset: 2025-01-01T14:00:00+00:00 # Quando o contador reinicia
Retry-After: 60 # Apenas no erro 429: segundos para aguardar
Códigos de Erro
200
OK
Requisição bem-sucedida
401
Unauthorized
API Key ausente, inválida ou revogada
403
Forbidden
Conta suspensa ou sem permissão
404
Not Found
Endpoint ou recurso não encontrado
429
Too Many Requests
Rate limit excedido — aguarde e tente novamente
500
Server Error
Erro interno — tente novamente em instantes
Formato da Resposta
Todas as respostas seguem o mesmo envelope JSON:
Estrutura padrão
{
"status": "success", // "success" ou "error"
"code": 200, // HTTP status code
"data": { // Payload da resposta
"sport": "soccer",
"total": 5,
"games": [...]
},
"meta": {
"timestamp": "2025-01-01T12:00:00+00:00",
"response_ms": 142, // Tempo de resposta em ms
"api_version": "v1"
}
}
// Em caso de erro:
{
"status": "error",
"code": 401,
"error": {
"type": "unauthorized",
"message": "Invalid or revoked API key."
},
"meta": { ... }
}
Ligar e Esportes
Lista todos os esportes e ligas suportadas
GET
/v1/leagues
Lista todos os esportes e ligas suportadas
▼
🔒 Requer X-API-Key ou ?api_key=
Campos Retornados
sports[].sportsports[].namesports[].leagues[].idsports[].leagues[].name
💡 Use os valores de league.id como parâmetro {league} nos outros endpoints.
Exemplos de Código
curl -H "X-API-Key: SUA_API_KEY" \
"https://magosport.com.br/api/v1/leagues"
▶ Testar ao vivo
Mercados de Apostas
Lista todos os mercados disponíveis para apostas
GET
/v1/markets
Lista todos os mercados disponíveis para apostas
▼
🔒 Requer X-API-Key ou ?api_key=
Parâmetros
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| sport | string | Filtra mercados por esporte |
Campos Retornados
markets[].idmarkets[].namemarkets[].sports[]
💡 14 mercados disponíveis: result_1x2, moneyline, totals, handicap, both_teams_score, double_chance, draw_no_bet, first_half, spread, correct_score, anytime_scorer, player_props, team_totals.
Exemplos de Código
curl -H "X-API-Key: SUA_API_KEY" \
"https://magosport.com.br/api/v1/markets"
▶ Testar ao vivo
Placares
Placares completos com todos os dados em tempo real
GET
/v1/scoreboard/{sport}
Placares completos com todos os dados em tempo real
▼
🔒 Requer X-API-Key ou ?api_key=
Parâmetros
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| sport | string | soccer|basketball|football|hockey|baseball | * |
| league | string | eng.1|bra.1|nba|nfl|nhl|mlb|... | |
| date | string | Data YYYYMMDD (padrão: hoje) | |
| status | string | live|pre|post | |
| limit | integer | 1-100 |
Campos Retornados
idnamestatus.statestatus.clockstatus.periodis_livehome.display_namehome.scorehome.logohome.colorhome.records[]away.display_nameaway.scorevenue.namevenue.citybroadcasts[].namesespn_odds.over_underespn_odds.spreadsituation.downsituation.last_playleaders[].nameweather.temperature
💡 Campo situation disponível apenas em jogos ao vivo de NFL. Campo espn_odds disponível para jogos NFL/NBA/MLB. leaders mostra os melhores atletas do jogo em tempo real.
Exemplos de Código
curl -H "X-API-Key: SUA_API_KEY" \
"https://magosport.com.br/api/v1/scoreboard/soccer"
▶ Testar ao vivo
Odds de Apostas
Odds calculadas com 14 mercados por jogo
GET
/v1/odds/{sport}/{league}
Odds calculadas com 14 mercados por jogo
▼
🔒 Requer X-API-Key ou ?api_key=
Parâmetros
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| sport | string | soccer|basketball|football|hockey|baseball | * |
| league | string | eng.1|bra.1|nba|nfl|... | * |
| gameId | string | ID de jogo específico (obtido em /scoreboard) | |
| market | string | Mercado(s) separados por vírgula. Padrão: todos |
Campos Retornados
odds[].game_idodds[].home.nameodds[].away.nameodds[].markets[].marketodds[].markets[].market_nameodds[].markets[].suspendedodds[].markets[].odds[].labelodds[].markets[].odds[].valueodds[].markets[].odds[].typeodds[].espn_odds
💡 Mercados por esporte:
• Futebol: result_1x2, totals, handicap, both_teams_score, double_chance, draw_no_bet, first_half, correct_score
• Basquete/NFL/MLB/NHL: moneyline, spread, totals, player_props
Passe market=result_1x2,totals para múltiplos mercados.
Exemplos de Código
curl -H "X-API-Key: SUA_API_KEY" \
"https://magosport.com.br/api/v1/odds/soccer/bra.1"
▶ Testar ao vivo
Sumário da Partida
Box score completo com estatísticas por jogador, win probability e mais
GET
/v1/games/{sport}/{gameId}
Box score completo com estatísticas por jogador, win probability e mais
▼
🔒 Requer X-API-Key ou ?api_key=
Parâmetros
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| sport | string | soccer|basketball|football|hockey|baseball | * |
| gameId | string | ID da partida (obtido em /scoreboard) | * |
Campos Retornados
boxscore[].team.nameboxscore[].statistics[].nameboxscore[].statistics[].athletes[].nameboxscore[].statistics[].athletes[].stats{}scoring_plays[].textscoring_plays[].clockscoring_plays[].home_scorewin_probability[].home_pctwin_probability[].away_pctleadersinjuries[].athleteinjuries[].statusinjuries[].descriptionrosters[].players[].namerosters[].players[].positionagainst_spreadpredictor
💡 O campo boxscore.statistics.athletes[].stats é um objeto chave-valor com todas as estatísticas do jogador (ex: {"PTS":"28","REB":"10","AST":"8"} no NBA). Disponibilidade de campos varia por esporte.
Exemplos de Código
curl -H "X-API-Key: SUA_API_KEY" \
"https://magosport.com.br/api/v1/games/soccer/401234567"
▶ Testar ao vivo
Play-by-Play
Lance a lance completo da partida
GET
/v1/games/{sport}/{gameId}/plays
Lance a lance completo da partida
▼
🔒 Requer X-API-Key ou ?api_key=
Parâmetros
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| sport | string | soccer|basketball|football|hockey|baseball | * |
| gameId | string | ID da partida | * |
Campos Retornados
total_playsplays[].idplays[].type.textplays[].textplays[].period.displayplays[].clockplays[].team_idplays[].home_scoreplays[].away_scoreplays[].coordinate.xplays[].coordinate.yplays[].athlete_ids_involved[]
💡 Disponível apenas para jogos em andamento ou finalizados. Para futebol retorna substituições, cartões e gols. Para NFL inclui posição de campo e down/distance.
Exemplos de Código
curl -H "X-API-Key: SUA_API_KEY" \
"https://magosport.com.br/api/v1/games/soccer/401234567/plays"
▶ Testar ao vivo
Times
Lista todos os times ou detalhes de um time específico
GET
/v1/teams/{sport}
Lista todos os times ou detalhes de um time específico
▼
🔒 Requer X-API-Key ou ?api_key=
Parâmetros
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| sport | string | soccer|basketball|football|hockey|baseball | * |
| teamId | path | ID do time para detalhes (opcional) | |
| league | string | Filtrar por liga |
Campos Retornados
iddisplay_nameabbreviationlogocolorcolor_altvenue.namevenue.capacityvenue.cityrecord.overallrecord.homerecord.awaystandings.ranknext_event.namecoaches[].name
💡 Para detalhes de um time específico use: GET /v1/teams/{sport}/{teamId}
Exemplos de Código
curl -H "X-API-Key: SUA_API_KEY" \
"https://magosport.com.br/api/v1/teams/soccer"
▶ Testar ao vivo
Elenco do Time
Elenco completo com dados detalhados de cada jogador
GET
/v1/teams/{sport}/{teamId}/roster
Elenco completo com dados detalhados de cada jogador
▼
🔒 Requer X-API-Key ou ?api_key=
Parâmetros
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| sport | string | soccer|basketball|football|hockey|baseball | * |
| teamId | string | ID do time | * |
Campos Retornados
athletes[].idathletes[].nameathletes[].position.nameathletes[].jerseyathletes[].headshotathletes[].dobathletes[].ageathletes[].nationalityathletes[].heightathletes[].weightathletes[].collegeathletes[].draft.yearathletes[].draft.roundathletes[].injuries[].status
💡 Inclui foto de perfil (headshot), dados físicos, histórico de draft e lesões ativas.
Exemplos de Código
curl -H "X-API-Key: SUA_API_KEY" \
"https://magosport.com.br/api/v1/teams/soccer/123/roster"
▶ Testar ao vivo
Classificação
Tabela de classificação completa com todas as estatísticas
GET
/v1/standings/{sport}
Tabela de classificação completa com todas as estatísticas
▼
🔒 Requer X-API-Key ou ?api_key=
Parâmetros
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| sport | string | soccer|basketball|football|hockey|baseball | * |
| league | string | eng.1|bra.1|nba|... | * |
Campos Retornados
seasongroups[].namegroups[].entries[].team.namegroups[].entries[].team.logogroups[].entries[].stats.GPgroups[].entries[].stats.Wgroups[].entries[].stats.Lgroups[].entries[].stats.PTSgroups[].entries[].note
💡 Tabela organizada por grupos/conferências (quando aplicável). Para ligas de futebol inclui pontos, vitórias, empates, derrotas, gols pró/contra e saldo.
Exemplos de Código
curl -H "X-API-Key: SUA_API_KEY" \
"https://magosport.com.br/api/v1/standings/soccer"
▶ Testar ao vivo
Notícias
Notícias esportivas completas com imagens e metadados
GET
/v1/news/{sport}
Notícias esportivas completas com imagens e metadados
▼
🔒 Requer X-API-Key ou ?api_key=
Parâmetros
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| sport | string | soccer|basketball|football|hockey|baseball | * |
| league | string | Filtrar por liga | |
| limit | integer | 1-50 artigos (padrão: 20) |
Campos Retornados
articles[].headlinearticles[].descriptionarticles[].storyarticles[].bylinearticles[].publishedarticles[].linkarticles[].images[].urlarticles[].images[].captionarticles[].categories[].typearticles[].categories[].team_id
💡 Campo story contém o texto completo da notícia (quando disponível). categories permite filtrar por time ou atleta específico.
Exemplos de Código
curl -H "X-API-Key: SUA_API_KEY" \
"https://magosport.com.br/api/v1/news/soccer"
▶ Testar ao vivo
Atletas
Perfil completo de um atleta
GET
/v1/athletes/{sport}/{athleteId}
Perfil completo de um atleta
▼
🔒 Requer X-API-Key ou ?api_key=
Parâmetros
| Parâmetro | Tipo | Descrição | |
|---|---|---|---|
| sport | string | soccer|basketball|football|hockey|baseball | * |
| athleteId | string | ID do atleta | * |
Campos Retornados
idnameposition.namejerseyheadshotdobagenationalitybirthplace.cityheightweightexperiencecollegedraft.yeardraft.rounddraft.pickteam.nameinjuries[].statusinjuries[].description
💡 Os IDs dos atletas podem ser obtidos em /teams/{sport}/{teamId}/roster ou em /games/{sport}/{gameId} (líderes e rosters).
Exemplos de Código
curl -H "X-API-Key: SUA_API_KEY" \
"https://magosport.com.br/api/v1/athletes/soccer/4241479"