WhoScored APIwhoscored.com ↗
Access WhoScored player stats, team ratings, match events, lineups, league standings, and fixtures via a structured REST API with 11 endpoints.
What is the WhoScored API?
The WhoScored API provides 11 endpoints covering football player and team search, seasonal statistics, per-match events with x/y pass coordinates, lineups, league standings with form guides, and match previews. The get_match_events endpoint returns every pass, shot, and action in a completed match with origin and destination coordinates, while get_league_standings surfaces full league tables including per-team home/away splits and recent form strings.
curl -X GET 'https://api.parse.bot/scraper/fefeab4f-b650-45ef-9b05-42622fe3619a/search?query=Barcelona' \ -H 'X-API-Key: $PARSE_API_KEY'
Full-text search over WhoScored's player and team database. Returns matching players (with IDs, slugs, current team, age) and teams (with IDs, slugs, country). A query that matches only players returns an empty teams array and vice versa. Results are unordered and unpaginated — the server returns all matches in a single response.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | Search keyword (player or team name) |
{
"type": "object",
"fields": {
"teams": "array of team objects with team_id, slug, name, and country",
"players": "array of player objects with player_id, slug, name, team, and age"
},
"sample": {
"data": {
"teams": [
{
"name": "Barcelona",
"slug": "spain-barcelona",
"country": "Spain",
"team_id": 65
}
],
"players": [
{
"age": 38,
"name": "Lionel Messi",
"slug": "lionel-messi",
"team": "Inter Miami CF",
"player_id": 11119
}
]
},
"status": "success"
}
}About the WhoScored API
Search and Identity
The search endpoint accepts a free-text query and returns matched players (with player_id, slug, team, and age) and teams (with team_id, slug, name, and country). Results are unordered and unpaginated. The player_id and team_id values returned here are the keys used across every other endpoint. Note that a query matching only players returns an empty teams array, and vice versa.
Seasonal Statistics
get_player_stats returns paginated seasonal records for a single player across all tournaments they have appeared in. Each record in playerTableStats includes fields such as rating, goals, apps, assists, passSuccess, minsPlayed, and shotsPerGame, with the available column names listed in the statColumns array. get_team_stats mirrors this for teams, additionally returning possession, and the tournamentId / tournamentRegionId pair that feeds directly into get_league_standings.
Match-Level Data
For completed matches, three endpoints cover different granularities. get_match_team_stats returns side-by-side team aggregates: possession %, shots, corners, cards, tackles, interceptions, and pass accuracy. get_match_player_stats returns per-player rows for both squads including position, isFirstEleven, isManOfTheMatch, minutesPlayed, and a stats object with all per-player match metrics. get_match_events goes deeper, returning every discrete event with x, y, end_x, end_y, event_type, outcome, and qualifiers. get_match_player_actions organises actions by expanded minute with pass structure detail and a total_actions count.
Fixtures, Lineups, and Previews
list_matches retrieves the full fixture list for a team by team_id, with an optional season parameter in YYYY/YYYY format to access archived seasons. Each match record carries match_id, date, time, team IDs and names, score, status, and tournament. get_match_lineup returns formations and 11 starters per side, with a lineup_status field that is confirmed, predicted, or unavailable. get_match_preview consolidates editorial preview paragraphs, predicted_score, missing_players with their status, previous_meetings head-to-head counts, and a lineup_stat_comparison table comparing current-season metrics for each side's expected starters.
The WhoScored API is a managed, monitored endpoint for whoscored.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when whoscored.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official whoscored.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a player comparison tool using seasonal
rating,goals, andpassSuccessfields fromget_player_stats - Track team form across a season using the
formstring and home/away splits fromget_league_standings - Visualise pass maps for any completed match using
x,y,end_x,end_ycoordinates fromget_match_events - Generate pre-match reports by combining
preview_text,missing_players, andprevious_meetingsfromget_match_preview - Power a fixture calendar by querying
list_matcheswith ateam_idand optionalseasonfilter - Identify squad selection and formations ahead of kick-off using
get_match_lineupwithlineup_statusawareness - Analyse per-minute match momentum by iterating the
minutesarray fromget_match_player_actions
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does WhoScored have an official developer API?+
What does `get_match_events` return for a completed match, and how detailed is the positional data?+
x and y origin coordinates and end_x / end_y destination coordinates (0–100 scale), plus event_type, outcome, player_id, player_name, team_id, minute, and a qualifiers array. Only completed matches have full event data; in-progress or upcoming matches are not supported by this endpoint.How do I get the `tournament_id` and `region_id` values needed for `get_league_standings`?+
get_team_stats includes tournamentId and tournamentRegionId in every row of teamTableStats. Call that endpoint with any team from the competition you want, pick the relevant row, and pass those two values as tournament_id and region_id to get_league_standings. The optional season parameter accepts YYYY/YYYY format (or YYYY for calendar-year leagues); omitting it returns the current season.Does the API cover referee data, xG (expected goals), or player heat maps?+
Are archived seasons available for all endpoints, or only some?+
list_matches supports archived seasons via the season parameter in YYYY/YYYY format; when a season is archived, the endpoint makes additional requests to retrieve that data. get_league_standings also accepts a season parameter for historical tables. Endpoints like get_match_player_stats, get_match_team_stats, and get_match_events work on any completed match by match_id regardless of season, but there is no bulk historical match listing endpoint currently. You can fork this API on Parse and revise it to add a historical match listing endpoint.