Building with AI? Give your coding tool the whole reference in one file: https://soccer-data.co/llms.txt
SOCCER DATA Docs
Sign in Get API key
// API reference

API reference

Every endpoint at a glance, plus the conventions they all share.

This section documents every Soccer Data endpoint: its parameters, the fields it returns and an example response. This page collects the rules they share and links to each one.

Basics

  • Base URL: https://api.soccer-data.co/v1
  • Method: every endpoint is a GET that returns JSON. The API is read-only.
  • Authentication: send your key in the X-Api-Key header. Your first key is made when you sign up; create more on the API keys page. Only /health works without one. See Authentication.
  • Where to call from: your server, so the key stays private.
curl "https://api.soccer-data.co/v1/competitions?search=Premier" \
  -H "X-Api-Key: YOUR_API_KEY"

const res = await fetch("https://api.soccer-data.co/v1/competitions?search=Premier", {
  headers: { "X-Api-Key": process.env.SOCCER_DATA_KEY },
});
const { data, meta } = await res.json();

import os, requests

res = requests.get(
    "https://api.soccer-data.co/v1/competitions",
    params={"search": "Premier"},
    headers={"X-Api-Key": os.environ["SOCCER_DATA_KEY"]},
)
data = res.json()["data"]

$data = Http::withHeaders(['X-Api-Key' => env('SOCCER_DATA_KEY')])
    ->get('https://api.soccer-data.co/v1/competitions', ['search' => 'Premier'])
    ->json('data');

Tip The API tester in your dashboard runs any endpoint as your signed-in account, with no key needed, so you can see real responses before writing code.

Response shapes

  • Paged lists (competitions, teams, players, matches, coverage by competition) return a data array and a meta object with page, per_page, total and total_pages.
  • Single items return one object in data.
  • Short lists (seasons, standings, squads) return a data array with no meta.
  • A few endpoints, such as shot maps and timelines, add other top-level fields next to data.

IDs

Ids are strings that start with a word saying what they name: competition_, season_, team_, player_, match_, shot_, manager_ or referee_, then 12 letters and digits. They never change, so store them freely. Find them with the search parameter on competitions, teams and players. See Data model.

Pagination

Paged lists return 20 results by default and up to 100 with per_page; /coverage/leagues returns 100 by default and up to 200. Move through pages with page and stop when it reaches meta.total_pages. See Pagination.

Errors

Errors come as an error object with code, message and status_code. Write your logic against code. Two you'll meet early:

  • 400 UNKNOWN_PARAMETER: the endpoint doesn't take that parameter. The message suggests the closest valid one and lists the parameters the endpoint takes.
  • 401 UNAUTHORIZED: the key is missing, wrong or revoked.

Errors lists every code.

Limits and plans

Every authenticated response carries X-RateLimit-* headers for the per-minute limit, X-Daily-Quota-* headers for the daily limit, and X-Cache to show whether the answer came from cache. Going over a limit returns 429 with a Retry-After header. Odds need a paid plan (Pro or Business). See Rate limits.

Endpoints

General

Endpoint Path What it's for
Health check /health Check the API is up. Needs no key and doesn't count against your limits.

Competitions

Endpoint Path What it's for
List competitions /competitions Search and filter leagues, cups and tournaments.
Get a competition /competitions/{competition_id} One competition, with its current_season_id and data flags.
List seasons /competitions/{competition_id}/seasons Every season of a competition, newest first.
List groups /competitions/{competition_id}/seasons/{season_id}/groups The groups of a tournament season.
Standings /competitions/{competition_id}/seasons/{season_id}/standings The league table, or the group tables.

Teams

Endpoint Path What it's for
List teams /teams Search teams, or list the teams in a season.
Get a team /teams/{team_id} One team's profile.
Squad /teams/{team_id}/players The current squad.
Season stats /teams/{team_id}/stats A team's record, position and form for one season.
Standings history /teams/{team_id}/standings Every competition and season where the team has a table entry.
Injuries and suspensions /teams/{team_id}/injuries-suspensions Who's out, and why.

Matches

Endpoint Path What it's for
List matches /matches Fixtures, results and live matches, with filters.
Get a match /matches/{match_id} One match, with the score breakdown, venue, referee and managers.
Lineups /matches/{match_id}/lineups Starting line-ups, substitutes and formations.
Timeline /matches/{match_id}/timeline Every event of a finished match.
Live timeline /matches/{match_id}/live-timeline Events so far, while the match is live.
Team stats /matches/{match_id}/stats Team stats and xG for a finished match.
Live team stats /matches/{match_id}/live-stats Score, clock and team stats while the match is live.
Player stats /matches/{match_id}/player-stats Every player's stats for a finished match.
Live player stats /matches/{match_id}/live-player-stats Player stats so far, while the match is live.
Shot map /matches/{match_id}/shotmap Every shot, with xG and pitch position.
Player heatmap /matches/{match_id}/players/{player_id}/heatmap Where one player touched the ball in a match.
Referee /matches/{match_id}/referee The referee and their career totals.

Players

Endpoint Path What it's for
List players /players Search players, or list a team's players.
Get a player /players/{player_id} One player's profile.
Season stats /players/{player_id}/stats A player's totals for one season.
Injuries and suspensions /players/{player_id}/injuries-suspensions A player's absences.
Season heatmap /players/{player_id}/competitions/{competition_id}/seasons/{season_id}/heatmap Where a player touched the ball across a season.

Odds

Endpoint Path What it's for
Pre-match odds /matches/{match_id}/odds Opening and latest prices per bookmaker. Pro or Business plan.
Live odds /matches/{match_id}/odds/live In-play prices while the match is live. Pro or Business plan.

Coverage

Endpoint Path What it's for
Coverage by competition /coverage/leagues Which data types each competition has.
Coverage for one competition /coverage/leagues/{competition_id} Season-by-season coverage for one competition.
Coverage summary /coverage/summary Totals across everything we cover.

For AI tools

The whole documentation, including every endpoint on this page, is also available as a single plain-text file at https://soccer-data.co/llms.txt. Point your AI coding tool at it, as described in Build with AI.