API Documentation

Complete reference for the SportAPI.ai REST API

Authentication

Some endpoints require authentication. Include your token in the Authorization header:

HTTP Header
Authorization: Bearer your_token_here

Get a token by logging in via /api/auth/login or using Google OAuth.

Base URL

https://sportapi.ai/api

All endpoints are relative to this base URL.

Fixtures (Matches)

Retrieve match data including live scores, events, and historical results.

GET/api/fixtures/date/{date}

Get all fixtures for a specific date.

ParameterTypeDescription
datestringDate in YYYY-MM-DD format
Try it+
Response Example
{
  "success": true,
  "date": "2026-01-26",
  "fixtures": [
    {
      "id": 12345,
      "home_team": "Manchester United",
      "away_team": "Liverpool",
      "home_score": 2,
      "away_score": 1,
      "status": "FT",
      "league_name": "Premier League"
    }
  ]
}
GET/api/fixtures/{id}

Get detailed information about a specific fixture including match events.

ParameterTypeDescription
idintegerFixture ID
Try it+
Response Example
{
  "success": true,
  "fixture": {
    "id": 12345,
    "home_team": "Manchester United",
    "away_team": "Liverpool",
    "home_score": 2,
    "away_score": 1,
    "events": [
      { "event_type": "goal", "player_name": "Rashford", "minute": "23" }
    ]
  }
}
GET/api/fixtures/{id}/events

Get only the events for a specific fixture (goals, cards, substitutions).

ParameterTypeDescription
idintegerFixture ID
Try it+
Response Example
{
  "success": true,
  "events": [
    { "event_type": "goal", "team_side": "home", "player_name": "Rashford", "minute": "23" }
  ]
}
GET/api/fixtures/{id}/stats

Get match statistics for a fixture: shots, passes, fouls, tackles, saves, and yellow cards per team.

ParameterTypeDescription
idintegerFixture ID
Try it+
Response Example
{
  "success": true,
  "fixture_id": 12345,
  "available": true,
  "data": {
    "home": {
      "shots": 14,
      "shots_on_target": 6,
      "shots_off_target": 8,
      "fouls": 11,
      "total_passes": 432,
      "pass_accuracy": 84.2,
      "tackles": 18,
      "tackle_success": 72.2,
      "saves": 3,
      "yellow_cards": 2
    },
    "away": {
      "shots": 8,
      "shots_on_target": 3,
      "shots_off_target": 5,
      "fouls": 14,
      "total_passes": 389,
      "pass_accuracy": 79.5,
      "tackles": 22,
      "tackle_success": 68.1,
      "saves": 5,
      "yellow_cards": 3
    }
  }
}
GET/api/fixtures/{id}/lineups

Get match lineups including starting XI and substitutes for both teams.

ParameterTypeDescription
idintegerFixture ID
Try it+
Response Example
{
  "success": true,
  "fixture_id": 12345,
  "available": true,
  "data": {
    "home": {
      "starters": [
        { "name": "De Gea", "position": "Goalkeeper", "shirt": 1, "is_captain": false, "mins_played": 90 },
        { "name": "Rashford", "position": "Forward", "shirt": 10, "is_captain": true, "mins_played": 74 }
      ],
      "subs": [
        { "name": "Sancho", "position": "Substitute", "shirt": 25, "is_captain": false, "mins_played": 16 }
      ]
    },
    "away": {
      "starters": [...],
      "subs": [...]
    }
  }
}

Teams

Access team information including details, squad, matches, and trophy history.

GET/api/teams/{id}

Get team information with recent matches and leagues.

ParameterTypeDescription
idintegerTeam ID
Try it+
Response Example
{
  "success": true,
  "team": {
    "id": 157,
    "name": "Manchester United",
    "country": "England",
    "coach_name": "Erik ten Hag",
    "stadium_name": "Old Trafford"
  },
  "matches": [...],
  "leagues": [...]
}
GET/api/teams/{id}/logo

Get team logo image. Returns PNG/SVG or placeholder shield.

ParameterTypeDescription
idintegerTeam ID
Try it+
Response Example
Content-Type: image/png
Binary image data
GET/api/teams/{id}/squad

Get team's player roster organized by position.

ParameterTypeDescription
idintegerTeam ID
Try it+
Response Example
{
  "success": true,
  "squad": [
    {
      "full_name": "Marcus Rashford",
      "position": "Forward",
      "jersey_number": 10,
      "nationality": "GB"
    }
  ]
}
GET/api/teams/{id}/trophies

Get team's trophy and championship history.

ParameterTypeDescription
idintegerTeam ID
Try it+
Response Example
{
  "success": true,
  "trophies": [
    { "year": 2023, "position": "winner", "tournament_name": "EFL Cup" }
  ]
}

Standings

Get league tables and team form data.

GET/api/standings/leagues

Get list of all available leagues with standings data.

Try it+
Response Example
{
  "success": true,
  "data": [
    { "id": 1, "name": "Premier League" },
    { "id": 2, "name": "La Liga" }
  ]
}
GET/api/standings/{leagueId}

Get full league standings with team form (last 6 matches).

ParameterTypeDescription
leagueIdintegerLeague ID
Try it+
Response Example
{
  "success": true,
  "data": {
    "league": { "id": 1, "name": "Premier League" },
    "standings": [
      {
        "position": 1,
        "team_name": "Liverpool",
        "played": 22,
        "won": 15,
        "points": 50,
        "form": ["W", "W", "D", "W", "L", "W"]
      }
    ]
  }
}

Leagues

Access league information including top scorers, assists, cards, and head-to-head match history.

GET/api/leagues

Get all leagues grouped by country with data coverage info.

Try it+
Response Example
{
  "success": true,
  "data": [
    {
      "country": "England",
      "geo": "GB",
      "leagues": [
        { "id": 1, "name": "Premier League", "fixtures_count": 380, "teams_count": 20 }
      ]
    }
  ]
}
GET/api/leagues/{id}

Get league details with teams, upcoming fixtures, and recent results.

ParameterTypeDescription
idintegerLeague ID
Try it+
Response Example
{
  "success": true,
  "league": { "id": 1, "name": "Premier League", "country": "England" },
  "teams": [...],
  "upcoming_fixtures": [...],
  "recent_results": [...]
}
GET/api/leagues/{id}/topscorers

Get top scorers for a specific league.

ParameterTypeDescription
idintegerLeague ID
Try it+
Response Example
{
  "success": true,
  "league": { "id": 1, "name": "Premier League" },
  "data": [
    { "rank": 1, "player_name": "Erling Haaland", "goals": 20, "team_name": "Manchester City" }
  ]
}
GET/api/leagues/{id}/topassists

Get top assist providers for a specific league.

ParameterTypeDescription
idintegerLeague ID
Try it+
Response Example
{
  "success": true,
  "league": { "id": 1, "name": "Premier League" },
  "data": [
    { "rank": 1, "player_name": "Kevin De Bruyne", "assists": 12, "team_name": "Manchester City" }
  ]
}
GET/api/leagues/{id}/topcards

Get players with most cards (yellow/red) in a league.

ParameterTypeDescription
idintegerLeague ID
Try it+
Response Example
{
  "success": true,
  "data": [
    { "rank": 1, "player_name": "Casemiro", "yellow_cards": 8, "red_cards": 1, "team_name": "Man Utd" }
  ]
}
GET/api/fixtures/h2h/{team1}/{team2}

Get head-to-head history between two teams.

ParameterTypeDescription
team1integerFirst team ID
team2integerSecond team ID
Try it+
Response Example
{
  "success": true,
  "team1": { "id": 157, "name": "Manchester United" },
  "team2": { "id": 160, "name": "Liverpool" },
  "summary": { "total_matches": 10, "team1_wins": 4, "team2_wins": 3, "draws": 3 },
  "fixtures": [...]
}

Players

Access player statistics and per-match performance data.

GET/api/players/stats

Get per-match statistics and career totals for a player. Lookup by player name and team ID.

ParameterTypeDescription
namestringFull player name
team_idintegerTeam ID the player belongs to
shirt_numberintegerOptional — helps disambiguate players with similar names
Try it+
Response Example
{
  "success": true,
  "player": {
    "shirt_number": 10,
    "position": "Forward",
    "nationality": "GB",
    "team": { "id": 157, "name": "Manchester United" }
  },
  "totals": {
    "appearances": 28,
    "goals": 12,
    "assists": 5,
    "mins_played": 2340,
    "shots_total": 67,
    "total_passes": 890,
    "tackles": 34,
    "saves": 0
  },
  "matches": [
    {
      "date": "2026-01-26",
      "home_team": "Manchester United",
      "away_team": "Liverpool",
      "goals": 1,
      "assists": 0,
      "mins_played": 90
    }
  ]
}

Authentication Endpoints

User registration and login endpoints.

POST/api/auth/register

Register a new user account.

ParameterTypeDescription
emailstringUser email (required)
passwordstringUser password (required)
namestringDisplay name (optional)
Try it+
Response Example
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": { "id": 1, "email": "[email protected]" }
}
POST/api/auth/login

Login with email and password.

ParameterTypeDescription
emailstringUser email (required)
passwordstringUser password (required)
Try it+
Response Example
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": { "id": 1, "email": "[email protected]" }
}
GET/api/auth/me

Get current authenticated user.

Requires Authentication
Try it+
Response Example
{
  "success": true,
  "user": { "id": 1, "email": "[email protected]", "name": "John" }
}
GET/api/auth/google

Get Google OAuth authorization URL.

Try it+
Response Example
{
  "success": true,
  "url": "https://accounts.google.com/o/oauth2/v2/auth?..."
}

User Endpoints

User profile and contact endpoints.

GET/api/profile

Get current user's profile.

Requires Authentication
Try it+
Response Example
{
  "success": true,
  "user": { "id": 1, "email": "[email protected]", "name": "John" }
}
POST/api/profile

Update user profile.

Requires Authentication
ParameterTypeDescription
namestringNew display name
Try it+
Response Example
{
  "success": true,
  "message": "Profile updated successfully"
}
POST/api/contact

Submit a contact form request.

ParameterTypeDescription
namestringYour name (required)
emailstringYour email (required)
subjectstringSubject (optional)
messagestringYour message (required)
Try it+
Response Example
{
  "success": true,
  "message": "Contact request submitted successfully"
}

WebSocket

Connect to the SportAPI WebSocket server to receive live score updates pushed to your client in real time — no polling required.

Connection

WebSocket URL
wss://sportapi.ai/ws?key=YOUR_API_KEY

Authenticate by passing your API key as a query parameter. The connection will be rejected with an error message if the key is missing or invalid.

Update Latency

Score updates are pushed within approximately 30–60 seconds of a goal being scored. This reflects our live data source refresh interval.

Client Messages

After connecting, send JSON messages to subscribe to fixtures:

Subscribe to all live fixtures
{ "action": "subscribe_all" }
Subscribe to a specific fixture
{ "action": "subscribe", "fixture_id": 12345 }
Unsubscribe from a fixture
{ "action": "unsubscribe", "fixture_id": 12345 }
Ping
{ "action": "ping" }

Server Messages

Score update
{
  "type": "score_update",
  "fixture_id": 12345,
  "home_score": 2,
  "away_score": 1,
  "home_pen": null,
  "away_pen": null,
  "status": "LIVE",
  "minute": "67'"
}

status values: LIVE, HT, FT, AET, Pen

JavaScript Example

JavaScript
const ws = new WebSocket('wss://sportapi.ai/ws?key=YOUR_API_KEY')

ws.onopen = () => {
  // Subscribe to all live matches
  ws.send(JSON.stringify({ action: 'subscribe_all' }))

  // Or subscribe to a specific fixture
  ws.send(JSON.stringify({ action: 'subscribe', fixture_id: 12345 }))
}

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data)
  if (msg.type === 'score_update') {
    console.log(`Fixture ${msg.fixture_id}: ${msg.home_score}–${msg.away_score} (${msg.status})`)
  }
}

ws.onclose = () => console.log('Disconnected')
ws.onerror = (err) => console.error('WebSocket error', err)