Reference

Football API documentation

Everything you need to get football data into your app: a quickstart, every endpoint with code in cURL, Python, JavaScript and PHP, an OpenAPI 3.1 spec and a Postman collection.

Quickstart

From zero to live football data in three steps. The Free plan gives you 2,000 requests a day (14,000 a month) with no card.

Create an account at sportapi.ai (email or Google).
Copy your API key from the API keys page. Keys start with sk_live_.
Make your first request. The program below prints today's matches with live scores. Replace YOUR_API_KEY and run it.

curl "https://sportapi.ai/api/fixtures/date/2026-10-26" \
  -H "X-Api-Key: YOUR_API_KEY"

Expected output: one line per match, for example Premier League: Arsenal 2-1 Leeds United (FT). Next: look up a match's events, lineups and stats, a league table, or get scores pushed to you over the WebSocket.

Authentication

Every data endpoint (fixtures, teams, standings, leagues, players) needs your API key in the X-Api-Key header. Create a key in your dashboard.

HTTP Header

X-Api-Key: your_api_key

curl

curl -H "X-Api-Key: your_api_key" https://sportapi.ai/api/fixtures/date/2026-10-10

Account endpoints (/api/auth/me, /api/profile) use the login token instead: Authorization: Bearer your_token. Get one from /api/auth/login or Google sign-in.

Your API key or login token (used by "Try it"):

Without a key, "Try it" on the data endpoints uses the website's own rate-limited access, so you can explore before signing up.

Base URL

https://sportapi.ai/api

All endpoints are relative to this base URL. A machine-readable OpenAPI 3.1 spec is available for code generators and tools such as Postman.

Responses & limits

Responses are JSON with a success flag. Errors come with an HTTP status and an error message: 401 missing or invalid key, 404 not found, 429 daily or monthly limit reached.

Rate limits

Each plan has a daily request limit that resets at 00:00 UTC. The Free plan also has a monthly limit of 14,000 requests per calendar month (UTC), from 1 November 2026; paid plans have no monthly cap. Every response tells you where you stand:

Response headers

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9876
X-RateLimit-Reset: 1791763200   (Unix time of the next reset)

# Free plan, from 1 November 2026:
X-RateLimit-Month-Limit: 14000
X-RateLimit-Month-Remaining: 9120
X-RateLimit-Month-Reset: 1793491200   (00:00 UTC on the 1st of next month)

Over the limit you get 429 with a Retry-After header (seconds until the reset). The JSON body has scope: day or month, so you can tell which limit you hit.

Caching with ETag

Successful GET responses carry an ETag. Send it back in If-None-Match and, if the data hasn't changed, you get an empty 304 Not Modified instead of the full body — ideal for polling fixtures and standings.

curl

curl -H "X-Api-Key: your_api_key" -H 'If-None-Match: "d1c0f0ad5808c8d8a0f13108edd63278"' https://sportapi.ai/api/leagues/24

Dates and times

kickoff_utc and updated_at are UTC (ISO 8601). date and datetime are Central European time (CET/CEST), the time zone the match calendar is kept in.

OpenAPI spec & Postman collection

Both files describe every data endpoint with parameters, response schemas and real example responses, and they are generated from the same source, so they always match this page.

OpenAPI 3.1 spec/api/openapi.jsonGenerate a typed client (openapi-generator, openapi-typescript), import into Insomnia or Swagger UI.Postman collectionsportapi.postman_collection.jsonIn Postman: Import → drop the file → set the apiKey variable on the collection. Every request has an example response.

Generate a Python client from the spec

pip install openapi-python-client
openapi-python-client generate --url https://sportapi.ai/api/openapi.json

MCP server for AI agents

Connect Claude, Cursor, VS Code and other AI agents to this API through our MCP server at https://sportapi.ai/mcp. It uses your API key and your plan limits, and gives the agent tools such as get_matches, get_standings and get_player.

Claude Code

claude mcp add --transport http sportapi https://sportapi.ai/mcp --header "X-Api-Key: YOUR_API_KEY"

Setup for every client, the full list of tools and example prompts: MCP server.

Fixtures (Matches)

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

status is one of Scheduled, LIVE, FT, AET, PENS, Postponed, Cancelled, Suspended; while a match is live, minute holds the clock ("HT" at half-time). result is 1 home win, 0 draw, -1 away win (null until played), and winner says the same in words, taking a penalty shoot-out (penalty_home/penalty_away) into account.

GET/api/fixtures/date/{date}

Get all fixtures for a specific date.

datestringDate in YYYY-MM-DD format

Try it+

curl "https://sportapi.ai/api/fixtures/date/2026-10-26" \
  -H "X-Api-Key: YOUR_API_KEY"

Response Example

{
  "success": true,
  "date": "2026-10-10",
  "data": [
    {
      "id": 13596176,
      "home_id": 311,
      "away_id": 352,
      "date": "2026-10-10",
      "datetime": "2026-10-10 13:30:00",
      "kickoff_utc": "2026-10-10T11:30:00Z",
      "updated_at": "2026-10-11T01:43:09Z",
      "home_score": 2,
      "away_score": 1,
      "result": 1,
      "status": "FT",
      "minute": null,
      "stage": "",
      "league_id": 24,
      "league_name": "Premier League",
      "league_geo": "GB-ENG",
      "league_zone": "England",
      "home_team": "Arsenal",
      "home_short": "Arsenal",
      "home_logo": "espn-359.png",
      "home_geo": "",
      "away_team": "Leeds United",
      "away_short": "Leeds",
      "away_logo": "espn-357.png",
      "away_geo": "",
      "penalty_home": null,
      "penalty_away": null,
      "winner": "home"
    }
  ]
}

GET/api/fixtures/{id}

Get detailed information about a specific fixture including match events.

idintegerFixture ID

Try it+

curl "https://sportapi.ai/api/fixtures/13596176" \
  -H "X-Api-Key: YOUR_API_KEY"

Response Example

{
  "success": true,
  "fixture": {
    "id": 13596176,
    "home_id": 311,
    "away_id": 352,
    "date": "2026-10-10",
    "datetime": "2026-10-10 13:30:00",
    "kickoff_utc": "2026-10-10T11:30:00Z",
    "updated_at": "2026-10-11T01:43:09Z",
    "home_score": 2,
    "away_score": 1,
    "ht_home": 0,
    "ht_away": 0,
    "result": 1,
    "status": "FT",
    "minute": null,
    "stage": "",
    "league_id": 24,
    "league_name": "Premier League",
    "league_geo": "GB-ENG",
    "league_zone": "England",
    "home_team": "Arsenal",
    "home_short": "Arsenal",
    "home_logo": "espn-359.png",
    "home_geo": "",
    "home_stadium": "Emirates Stadium",
    "home_city": "London",
    "home_coach": "Mikel Arteta",
    "home_founded": 1886,
    "away_team": "Leeds United",
    "away_short": "Leeds",
    "away_logo": "espn-357.png",
    "away_geo": "",
    "away_stadium": "Elland Road",
    "away_city": "Leeds",
    "away_coach": "Daniel Farke",
    "away_founded": 1919,
    "penalty_home": null,
    "penalty_away": null,
    "winner": "home",
    "events": [
      {
        "event_type": "goal",
        "team_side": "away",
        "player_name": "J. Justin",
        "minute": "55'",
        "extra_info": "Goal"
      },
      {
        "event_type": "yellow_card",
        "team_side": "away",
        "player_name": "A. Tanaka",
        "minute": "36'",
        "extra_info": null
      }
    ]
  }
}

GET/api/fixtures/{id}/events

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

idintegerFixture ID

Try it+

curl "https://sportapi.ai/api/fixtures/13596176/events" \
  -H "X-Api-Key: YOUR_API_KEY"

Response Example

{
  "success": true,
  "fixture_id": 13596176,
  "data": [
    {
      "id": 19194470,
      "event_type": "goal",
      "team_side": "away",
      "player_name": "J. Justin",
      "player_urn": "urn:bbc:sportsdata:football:player:s-6icypdqtfk2k81ax0i49j5xpl",
      "minute": "55'",
      "extra_info": "Goal"
    },
    {
      "id": 18933975,
      "event_type": "yellow_card",
      "team_side": "away",
      "player_name": "A. Tanaka",
      "player_urn": "urn:bbc:sportsdata:football:player:s-28ucbvor6b0yxreoieehudfc9",
      "minute": "36'",
      "extra_info": null
    }
  ]
}

GET/api/fixtures/{id}/stats

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

idintegerFixture ID

Try it+

curl "https://sportapi.ai/api/fixtures/13596176/stats" \
  -H "X-Api-Key: YOUR_API_KEY"

Response Example

{
  "success": true,
  "fixture_id": 13596176,
  "available": true,
  "data": {
    "home": {
      "shots": 13,
      "shots_on_target": 6,
      "shots_off_target": 7,
      "fouls": 12,
      "total_passes": 512,
      "pass_accuracy": 85.3,
      "tackles": 12,
      "tackle_success": 66.7,
      "saves": 4,
      "yellow_cards": 1
    },
    "away": {
      "shots": 11,
      "shots_on_target": 5,
      "shots_off_target": 6,
      "fouls": 20,
      "total_passes": 356,
      "pass_accuracy": 78.9,
      "tackles": 10,
      "tackle_success": 60,
      "saves": 4,
      "yellow_cards": 4
    }
  }
}

GET/api/fixtures/{id}/lineups

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

idintegerFixture ID

Try it+

curl "https://sportapi.ai/api/fixtures/13596176/lineups" \
  -H "X-Api-Key: YOUR_API_KEY"

Response Example

{
  "success": true,
  "fixture_id": 13596176,
  "available": true,
  "data": {
    "home": {
      "starters": [
        {
          "name": "David Raya",
          "position": "Goalkeeper",
          "shirt": 1,
          "is_captain": false,
          "mins_played": 90
        },
        {
          "name": "B. White",
          "position": "Defender",
          "shirt": 4,
          "is_captain": false,
          "mins_played": 63
        }
      ],
      "subs": [
        {
          "name": "P. Hincapié",
          "position": "Substitute",
          "shirt": 5,
          "is_captain": false,
          "mins_played": 8
        }
      ]
    },
    "away": {
      "starters": [
        {
          "name": "J. Trafford",
          "position": "Goalkeeper",
          "shirt": 1,
          "is_captain": false,
          "mins_played": 90
        },
        {
          "name": "J. Bogle",
          "position": "Midfielder",
          "shirt": 2,
          "is_captain": false,
          "mins_played": 86
        }
      ],
      "subs": [
        {
          "name": "S. Longstaff",
          "position": "Substitute",
          "shirt": 8,
          "is_captain": false,
          "mins_played": 0
        }
      ]
    }
  }
}

Teams

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

GET/api/teams/{id}

Get team information with recent matches and leagues.

idintegerTeam ID

Try it+

curl "https://sportapi.ai/api/teams/311" \
  -H "X-Api-Key: YOUR_API_KEY"

Response Example

{
  "success": true,
  "team": {
    "id": 311,
    "name": "Arsenal",
    "short_name": "Arsenal",
    "league_id": 24,
    "geo": "GB-ENG",
    "country": "England",
    "city": "London",
    "coach_name": "Mikel Arteta",
    "stadium_name": "Emirates Stadium",
    "founded_year": 1886,
    "logo_file": "espn-359.png"
  },
  "matches": [
    {
      "id": 16096707,
      "home_id": 311,
      "away_id": 10165,
      "date": "2026-11-07",
      "home_score": null,
      "away_score": null,
      "result": null,
      "status": "Scheduled",
      "league_id": 24,
      "league_name": "Premier League",
      "home_team": "Arsenal",
      "away_team": "Hull City"
    },
    {
      "id": 15868670,
      "home_id": 162,
      "away_id": 311,
      "date": "2026-11-04",
      "home_score": null,
      "away_score": null,
      "result": null,
      "status": "Scheduled",
      "league_id": 18,
      "league_name": "UEFA Champions League",
      "home_team": "Slavia Prague",
      "away_team": "Arsenal"
    }
  ],
  "leagues": [
    {
      "id": 24,
      "name": "Premier League"
    },
    {
      "id": 18,
      "name": "UEFA Champions League"
    }
  ]
}

GET/api/teams/{id}/logo

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

idintegerTeam ID

Try it+

curl "https://sportapi.ai/api/teams/311/logo" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -o logo.png

Response Example

Content-Type: image/png
Binary image data

GET/api/teams/slug/{slug}

Get a team by its URL slug, with its league, last results, upcoming matches and squad.

slugstringTeam slug

Try it+

curl "https://sportapi.ai/api/teams/slug/arsenal" \
  -H "X-Api-Key: YOUR_API_KEY"

Response Example

{
  "success": true,
  "team": {
    "id": 311,
    "name": "Arsenal",
    "short_name": "Arsenal",
    "slug": "arsenal",
    "country": "England",
    "city": "London",
    "geo": "GB-ENG",
    "founded_year": 1886,
    "coach_name": "Mikel Arteta",
    "stadium_name": "Emirates Stadium",
    "logo_file": "espn-359.png",
    "league": {
      "id": 24,
      "name": "Premier League",
      "slug": "premier-league"
    }
  },
  "results": [
    {
      "id": 13596176,
      "date": "2026-10-10",
      "home_score": 2,
      "away_score": 1,
      "status": "FT",
      "result": 1,
      "home_team": "Arsenal",
      "home_slug": "arsenal",
      "away_team": "Leeds United",
      "away_slug": "leeds-united",
      "league_name": "Premier League",
      "league_slug": "premier-league"
    }
  ],
  "upcoming": [
    {
      "id": 13596702,
      "date": "2026-10-13",
      "datetime": "2026-10-13 21:00:00",
      "status": "Scheduled",
      "home_team": "Arsenal",
      "home_slug": "arsenal",
      "away_team": "Lille",
      "away_slug": "lille",
      "league_name": "UEFA Champions League"
    }
  ],
  "squad": [
    {
      "full_name": "David Raya",
      "position": "Goalkeeper",
      "jersey_number": 1,
      "nationality": "ES",
      "slug": "david-raya"
    },
    {
      "full_name": "Kepa Arrizabalaga",
      "position": "Goalkeeper",
      "jersey_number": 13,
      "nationality": "ES",
      "slug": "kepa-arrizabalaga"
    }
  ]
}

GET/api/teams/{id}/squad

Get team's player roster organized by position.

idintegerTeam ID

Try it+

curl "https://sportapi.ai/api/teams/311/squad" \
  -H "X-Api-Key: YOUR_API_KEY"

Response Example

{
  "success": true,
  "squad": [
    {
      "id": 4904,
      "full_name": "David Raya",
      "position": "Goalkeeper",
      "jersey_number": 1,
      "nationality": "ES",
      "date_of_birth": "1995-09-15",
      "height": null,
      "weight": null
    },
    {
      "id": 4903,
      "full_name": "Kepa Arrizabalaga",
      "position": "Goalkeeper",
      "jersey_number": 13,
      "nationality": "ES",
      "date_of_birth": "1994-10-03",
      "height": null,
      "weight": null
    }
  ]
}

GET/api/teams/{id}/trophies

Get team's trophy and championship history.

idintegerTeam ID

Try it+

curl "https://sportapi.ai/api/teams/311/trophies" \
  -H "X-Api-Key: YOUR_API_KEY"

Response Example

{
  "success": true,
  "trophies": [
    {
      "year": 1994,
      "position": 1,
      "tournament_id": 26,
      "name": "1994 UEFA Cup Winners' Cup Final",
      "short_name": null,
      "type": "domestic_league",
      "country": null
    },
    {
      "year": 1993,
      "position": 1,
      "tournament_id": 24,
      "name": "1987 Football League Cup Final",
      "short_name": null,
      "type": "domestic_league",
      "country": null
    }
  ]
}

Standings

Get league tables and team form data.

GET/api/standings/leagues

Get list of all available leagues with standings data.

Try it+

curl "https://sportapi.ai/api/standings/leagues" \
  -H "X-Api-Key: YOUR_API_KEY"

Response Example

{
  "success": true,
  "data": [
    {
      "id": 24,
      "name": "Premier League",
      "slug": "premier-league",
      "zone": "England",
      "geo": "GB-ENG"
    },
    {
      "id": 1,
      "name": "Spanish La Liga",
      "slug": "spanish-la-liga",
      "zone": "Spain",
      "geo": "ES"
    }
  ]
}

GET/api/standings/{leagueId}

Get the current league table. form lists the last 6 matches, oldest first. You can also pass the league slug (e.g. /api/standings/premier-league); the response then includes the league.

leagueIdintegerLeague ID (or slug)

Try it+

curl "https://sportapi.ai/api/standings/24" \
  -H "X-Api-Key: YOUR_API_KEY"

Response Example

{
  "success": true,
  "data": [
    {
      "position": 1,
      "team": {
        "id": 324,
        "name": "Manchester City",
        "short_name": "Man City",
        "slug": "manchester-city",
        "logo": "espn-382.png"
      },
      "played": 5,
      "won": 5,
      "draw": 0,
      "lost": 0,
      "goals_for": 13,
      "goals_against": 5,
      "goal_difference": 8,
      "points": 15,
      "form": [
        {
          "result": "W",
          "date": "2026-09-13",
          "home_team": "Manchester United",
          "away_team": "Manchester City",
          "home_score": 0,
          "away_score": 1,
          "is_home": false
        },
        {
          "result": "W",
          "date": "2026-09-20",
          "home_team": "Manchester City",
          "away_team": "Sunderland",
          "home_score": 5,
          "away_score": 3,
          "is_home": true
        }
      ]
    },
    {
      "position": 2,
      "team": {
        "id": 311,
        "name": "Arsenal",
        "short_name": "Arsenal",
        "slug": "arsenal",
        "logo": "espn-359.png"
      },
      "played": 6,
      "won": 5,
      "draw": 0,
      "lost": 1,
      "goals_for": 10,
      "goals_against": 5,
      "goal_difference": 5,
      "points": 15,
      "form": [
        {
          "result": "L",
          "date": "2026-09-19",
          "home_team": "Brighton & Hove Albion",
          "away_team": "Arsenal",
          "home_score": 3,
          "away_score": 0,
          "is_home": false
        },
        {
          "result": "W",
          "date": "2026-10-10",
          "home_team": "Arsenal",
          "away_team": "Leeds United",
          "home_score": 2,
          "away_score": 1,
          "is_home": true
        }
      ]
    }
  ]
}

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+

curl "https://sportapi.ai/api/leagues" \
  -H "X-Api-Key: YOUR_API_KEY"

Response Example

{
  "success": true,
  "data": [
    {
      "country": "England",
      "geo": "GB-ENG",
      "leagues": [
        {
          "id": 53,
          "name": "Championship",
          "geo": "GB-ENG",
          "domestic": 1,
          "has_standings": true,
          "has_fixtures": true,
          "fixtures_count": 737,
          "teams_count": 24
        },
        {
          "id": 26,
          "name": "English Community Shield",
          "geo": "GB-ENG",
          "domestic": 1,
          "has_standings": true,
          "has_fixtures": true,
          "fixtures_count": 2,
          "teams_count": 0
        }
      ]
    }
  ]
}

GET/api/leagues/{id}

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

idintegerLeague ID

Try it+

curl "https://sportapi.ai/api/leagues/24" \
  -H "X-Api-Key: YOUR_API_KEY"

Response Example

{
  "success": true,
  "id": 24,
  "name": "Premier League",
  "geo": "GB-ENG",
  "country": "England",
  "domestic": 1,
  "teams": [
    {
      "id": 370,
      "name": "AFC Bournemouth",
      "logo_file": "espn-349.png"
    },
    {
      "id": 311,
      "name": "Arsenal",
      "logo_file": "espn-359.png"
    }
  ],
  "upcoming_fixtures": [
    {
      "id": 13596518,
      "date": "2026-10-11",
      "datetime": "2026-10-11 15:00:00",
      "home_team": "Crystal Palace",
      "away_team": "Nottingham Forest"
    }
  ],
  "recent_results": [
    {
      "id": 13596181,
      "date": "2026-10-10",
      "home_team": "Manchester United",
      "away_team": "Tottenham Hotspur",
      "home_score": 1,
      "away_score": 1
    }
  ]
}

GET/api/leagues/{id}/topscorers

Get top scorers for a specific league. Current season by default.

idintegerLeague ID

limitintegerRows to return, 1-100 (default 20)

seasonstringall = every season instead of the current one

Try it+

curl "https://sportapi.ai/api/leagues/24/topscorers?limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"

Response Example

{
  "success": true,
  "season_from": "2026-08-21",
  "data": [
    {
      "rank": 1,
      "player_name": "E. Haaland",
      "player_urn": "urn:bbc:sportsdata:football:player:s-atzboo800gv7gic2rgvgo0kq1",
      "team_id": 324,
      "team_name": "Manchester City",
      "goals": 5,
      "penalties": 0
    },
    {
      "rank": 1,
      "player_name": "João Pedro",
      "player_urn": "urn:bbc:sportsdata:football:player:s-eaqqezw2ed1u0tt3zc128mr1m",
      "team_id": 322,
      "team_name": "Chelsea",
      "goals": 5,
      "penalties": 0
    }
  ]
}

GET/api/leagues/{id}/topassists

Get top assist providers for a specific league. Current season by default.

idintegerLeague ID

limitintegerRows to return, 1-100 (default 20)

seasonstringall = every season instead of the current one

Try it+

curl "https://sportapi.ai/api/leagues/24/topassists?limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"

Response Example

{
  "success": true,
  "season_from": "2026-08-21",
  "data": [
    {
      "rank": 1,
      "player_name": "A. Semenyo",
      "player_urn": "",
      "team_id": 324,
      "team_name": "Manchester City",
      "assists": 3
    },
    {
      "rank": 1,
      "player_name": "C. Palmer",
      "player_urn": "",
      "team_id": 322,
      "team_name": "Chelsea",
      "assists": 3
    }
  ]
}

GET/api/leagues/{id}/topcards

Get players with most cards (yellow/red) in a league. Current season by default.

idintegerLeague ID

limitintegerRows to return, 1-100 (default 20)

seasonstringall = every season instead of the current one

Try it+

curl "https://sportapi.ai/api/leagues/24/topcards?limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"

Response Example

{
  "success": true,
  "season_from": "2026-08-21",
  "data": [
    {
      "rank": 1,
      "player_name": "A. Fatawu",
      "player_urn": "urn:bbc:sportsdata:football:player:s-6cx5c6bzp1hq6c1vui53mxzx0",
      "team_id": 10158,
      "team_name": "Ipswich Town",
      "yellow_cards": 3,
      "red_cards": 1,
      "total_cards": 4
    },
    {
      "rank": 1,
      "player_name": "V. Janelt",
      "player_urn": "urn:bbc:sportsdata:football:player:s-9k8gysrsy1a261nhcszo4aoyx",
      "team_id": 366,
      "team_name": "Brentford",
      "yellow_cards": 4,
      "red_cards": 0,
      "total_cards": 4
    }
  ]
}

GET/api/fixtures/h2h/{team1}/{team2}

Get head-to-head history between two teams.

team1integerFirst team ID

team2integerSecond team ID

Try it+

curl "https://sportapi.ai/api/fixtures/h2h/311/312" \
  -H "X-Api-Key: YOUR_API_KEY"

Response Example

{
  "success": true,
  "team1": 311,
  "team2": 312,
  "data": [
    {
      "id": 604,
      "home_id": 311,
      "away_id": 312,
      "date": "2026-01-08",
      "home_score": 0,
      "away_score": 0,
      "result": 0,
      "status": "FT",
      "home_team": "Arsenal",
      "away_team": "Liverpool",
      "league_name": "Premier League"
    },
    {
      "id": 577,
      "home_id": 312,
      "away_id": 311,
      "date": "2025-08-31",
      "home_score": 1,
      "away_score": 0,
      "result": 1,
      "status": "FT",
      "home_team": "Liverpool",
      "away_team": "Arsenal",
      "league_name": "Premier League"
    }
  ]
}

Players

Access player statistics and per-match performance data.

GET/api/players/{slug}

Get a player profile: bio, current team and league, career and current-season stats, recent matches and the next match.

slugstringPlayer slug

Try it+

curl "https://sportapi.ai/api/players/bukayo-saka" \
  -H "X-Api-Key: YOUR_API_KEY"

Response Example

{
  "success": true,
  "player": {
    "id": 4928,
    "full_name": "Bukayo Saka",
    "slug": "bukayo-saka",
    "position": "Forward",
    "nationality": "GB-ENG",
    "date_of_birth": "2001-09-05",
    "height": null,
    "weight": null,
    "photo_url": null,
    "jersey_number": 7,
    "team_id": 311
  },
  "team": {
    "id": 311,
    "full_name": "Arsenal",
    "slug": "arsenal",
    "country": "England",
    "geo": "GB-ENG",
    "league_id": 24
  },
  "league": {
    "id": 24,
    "name": "Premier League",
    "slug": "premier-league"
  },
  "linked": false,
  "career": null,
  "season": null,
  "rank": null,
  "matches": [],
  "recent": [],
  "next_match": {
    "date": "2026-10-13",
    "datetime": "2026-10-13 21:00:00",
    "home_team": "Arsenal",
    "home_slug": "arsenal",
    "away_team": "Lille",
    "away_slug": "lille",
    "league_name": "UEFA Champions League"
  },
  "squad": [
    {
      "full_name": "David Raya",
      "slug": "david-raya",
      "position": "Goalkeeper",
      "jersey_number": 1
    }
  ]
}

GET/api/players/stats

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

namestringFull player name

team_idintegerTeam ID the player belongs to

shirt_numberintegerOptional — helps disambiguate players with similar names

Try it+

curl "https://sportapi.ai/api/players/stats?name=Bukayo%20Saka&team_id=311&shirt_number=7" \
  -H "X-Api-Key: YOUR_API_KEY"

Response Example

{
  "success": true,
  "player": {
    "shirt_number": 7,
    "position": "Forward",
    "nationality": "GB-ENG",
    "team": {
      "id": 311,
      "name": "Arsenal"
    }
  },
  "totals": {
    "appearances": 46,
    "goals": 12,
    "assists": 6,
    "mins_played": 2775,
    "shots_total": 96,
    "total_passes": 957,
    "tackles": 42,
    "saves": 0
  },
  "matches": [
    {
      "goals": 0,
      "assists": 0,
      "mins_played": 90,
      "shots_total": 2,
      "total_passes": 34,
      "tackles": 1,
      "saves": 0,
      "position": "Attacking Midfielder",
      "shirt_number": 7,
      "is_starter": 1,
      "date": "2026-10-10",
      "home_score": 2,
      "away_score": 1,
      "home_id": 311,
      "away_id": 352,
      "home_team": "Arsenal",
      "away_team": "Leeds United",
      "league_name": "Premier League"
    }
  ]
}

Authentication Endpoints

User registration and login endpoints.

POST/api/auth/register

emailstringUser email (required)

passwordstringUser password (required)

namestringDisplay name (optional)

Try it+

curl -X POST "https://sportapi.ai/api/auth/register" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"YOUR_PASSWORD","name":"John Doe"}'

Response Example

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": { "id": 1, "email": "[email protected]" }
}

POST/api/auth/login

emailstringUser email (required)

passwordstringUser password (required)

Try it+

curl -X POST "https://sportapi.ai/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"YOUR_PASSWORD"}'

Response Example

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": { "id": 1, "email": "[email protected]" }
}

GET/api/auth/me

Get current authenticated user.

Requires Authentication

Try it+

curl "https://sportapi.ai/api/auth/me" \
  -H "Authorization: Bearer YOUR_LOGIN_TOKEN"

Response Example

{
  "success": true,
  "user": { "id": 1, "email": "[email protected]", "name": "John" }
}

GET/api/auth/google

Get Google OAuth authorization URL.

Try it+

curl "https://sportapi.ai/api/auth/google"

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+

curl "https://sportapi.ai/api/profile" \
  -H "Authorization: Bearer YOUR_LOGIN_TOKEN"

Response Example

{
  "success": true,
  "user": { "id": 1, "email": "[email protected]", "name": "John" }
}

POST/api/profile

Update user profile.

Requires Authentication

namestringNew display name

Try it+

curl -X POST "https://sportapi.ai/api/profile" \
  -H "Authorization: Bearer YOUR_LOGIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"New Name"}'

Response Example

{
  "success": true,
  "message": "Profile updated successfully"
}

POST/api/contact

Submit a contact form request.

namestringYour name (required)

emailstringYour email (required)

subjectstringSubject (optional)

messagestringYour message (required)

Try it+

curl -X POST "https://sportapi.ai/api/contact" \
  -H "Content-Type: application/json" \
  -d '{"name":"John Doe","email":"[email protected]","subject":"API Question","message":"Your message..."}'

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: Scheduled, LIVE, FT, AET, PENS, Postponed, Cancelled, Suspended. At half-time the status stays LIVE and minute is "HT". home_pen/away_pen hold the shoot-out score when there is one (REST endpoints call them penalty_home/penalty_away).

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)