# SportAPI

> SportAPI (sportapi.ai) is a REST JSON football (soccer) data API: live scores, fixtures and results, league standings, match events, lineups, team match statistics, top scorers, head-to-head, teams, squads and player profiles for 117 leagues and cups in 41 countries and regions. Football only. Free plan available, no card required.

Key facts:

- Base URL: `https://sportapi.ai/api`. Every endpoint is a GET that returns JSON with a `success` flag; the structure is the same for every league.
- Authentication: send your API key in the `X-Api-Key` header. Keys start with `sk_live_` and are created in the dashboard (https://sportapi.ai/dashboard) after a free sign-up.
- Plans (limits are per API key, per UTC day; reset at 00:00 UTC):
  - Free: $0, 2,000 requests/day, 1 key. From 1 November 2026 also capped at 14,000 requests per calendar month (UTC).
  - Starter: $10/month, 10,000 requests/day, 1 key.
  - Pro: $25/month, 50,000 requests/day, 3 keys.
  - Business: $50/month, 200,000 requests/day, 10 keys.
  - Paid plans have no monthly cap. Every plan includes all endpoints and all leagues.
- Rate limits: responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (and `X-RateLimit-Month-*` on the Free plan). Over the limit the API answers HTTP 429 with `Retry-After`; the JSON body has `scope`: `day` or `month`.
- Caching: successful GETs carry an `ETag`; send it back in `If-None-Match` to get an empty `304 Not Modified` when nothing changed.
- Freshness: live scores refresh every minute during matches; lineups, cards and player statistics are added about an hour after the final whistle.
- Real time: WebSocket `wss://sportapi.ai/ws?key=YOUR_API_KEY` pushes score updates, typically 30–60 seconds after a goal.
- Times: `kickoff_utc` and `updated_at` are UTC; `date` and `datetime` are Central European time (CET/CEST).
- Not provided: betting odds, expected goals (xG), possession percentages, player photos, other sports.

## Docs

- [API documentation](https://sportapi.ai/docs): quickstart, authentication, every endpoint with cURL, Python, JavaScript and PHP examples, WebSocket guide
- [OpenAPI 3.1 specification](https://sportapi.ai/api/openapi.json): machine-readable description of every data endpoint with parameters, schemas and real example responses
- [Postman collection](https://sportapi.ai/api/sportapi.postman_collection.json): import, set the `apiKey` variable, run
- [Full reference for LLMs](https://sportapi.ai/llms-full.txt): this file plus every endpoint with its parameters

## MCP server

- [MCP server for AI agents](https://sportapi.ai/mcp-server): remote MCP server at `https://sportapi.ai/mcp` (Streamable HTTP). Send your SportAPI key in the `X-Api-Key` header (or `Authorization: Bearer`). Works in Claude Code, Claude Desktop (via mcp-remote), Cursor, VS Code and other MCP clients. Tool calls count against the key's plan limits.
- Tools: `find_leagues`, `find_teams`, `find_players`, `get_matches`, `get_live_matches`, `get_match`, `get_head_to_head`, `get_standings`, `get_league`, `get_top_players`, `get_team`, `get_player`, `get_player_match_stats`.
- Claude Code: `claude mcp add --transport http sportapi https://sportapi.ai/mcp --header "X-Api-Key: YOUR_API_KEY"`

## Endpoints

- [Fixtures on a date](https://sportapi.ai/docs#fixtures): `GET /fixtures/date/{YYYY-MM-DD}` — all matches on a date with status, scores, teams and competition
- [Fixture details](https://sportapi.ai/docs#fixtures): `GET /fixtures/{id}`, `/fixtures/{id}/events`, `/fixtures/{id}/stats`, `/fixtures/{id}/lineups` — score, venue, coaches, goals, cards, substitutions, team statistics, starting XI and substitutes
- [Head to head](https://sportapi.ai/docs#leagues): `GET /fixtures/h2h/{team1}/{team2}` — previous meetings of two teams
- [Standings](https://sportapi.ai/docs#standings): `GET /standings/leagues`, `GET /standings/{league_id or slug}` — league tables with points, goal difference and form
- [Leagues](https://sportapi.ai/docs#leagues): `GET /leagues`, `/leagues/{id}`, `/leagues/{id}/topscorers`, `/topassists`, `/topcards`
- [Teams](https://sportapi.ai/docs#teams): `GET /teams/{id}`, `/teams/slug/{slug}`, `/teams/{id}/squad`, `/teams/{id}/trophies`, `/teams/{id}/logo`
- [Players](https://sportapi.ai/docs#players): `GET /players/{slug}`, `GET /players/stats?name=&team_id=` — profile, season and career statistics, per-match records

## Product

- [Football API overview](https://sportapi.ai/football-api/): what the API returns, coverage, plans and FAQ
- [Pricing](https://sportapi.ai/pricing): plans, limits and FAQ
- [Coverage](https://sportapi.ai/coverage): every league and cup with standings, top scorers, fixtures and teams
- [Free football widgets](https://sportapi.ai/widgets): embeddable league table, live scores, team fixtures and top scorers widgets; free, no API key, keep the "Football data by SportAPI" link
- [Live scores](https://sportapi.ai/realtime) and [league standings](https://sportapi.ai/standings): the data shown live on the site

## Optional

- [About](https://sportapi.ai/about)
- [Contact](https://sportapi.ai/contact)
- Language versions of the main pages: Spanish (https://sportapi.ai/es), Portuguese (https://sportapi.ai/pt), French (https://sportapi.ai/fr)