WhoScored APIwhoscored.com ↗
Access WhoScored football data via 5 endpoints: search players and teams, retrieve seasonal stats, match events with pass coordinates, and fixture lists.
What is the WhoScored API?
The WhoScored API exposes 5 endpoints covering player search, team search, seasonal performance statistics, and per-match event data. The get_match_events endpoint returns every in-game action for a completed match — including pass origin and destination coordinates, event type, outcome, and qualifiers — while get_player_stats and get_team_stats deliver per-tournament seasonal records for any player or team ID retrieved from the search endpoint.
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 ID Lookup
All entity lookups start with the search endpoint, which accepts a query string and returns two arrays: players (with player_id, slug, current team, and age) and teams (with team_id, slug, name, and country). Results are unordered and unpaginated. A query that matches only players returns an empty teams array and vice versa. The numeric IDs returned here are the required inputs for every other endpoint.
Seasonal Statistics
get_player_stats accepts a player_id and returns a playerTableStats array broken down by tournament and season. Each record includes rating, goals, apps, assists, passSuccess, minsPlayed, shotsPerGame, and additional columns enumerated in the statColumns array. get_team_stats mirrors this structure for teams, substituting possession and other team-level fields. Both endpoints include a paging object (currentPage, totalPages, totalResults) indicating whether multiple result pages exist.
Match Events and Fixtures
get_match_events takes a match_id and returns every event from a completed match: each object contains minute, second, player_id, player_name, team_id, event_type, outcome, spatial coordinates (x, y, end_x, end_y), and a qualifiers field with supplementary context per event type. The score, home, away, and max_minute fields are also returned at the top level. Match IDs can be sourced from list_matches, which retrieves the current-season fixture list for a given team_id, including date, time, status, home and away team identifiers, and score (null for upcoming fixtures).
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
get_player_statsto contrastrating,goals, andpassSuccessacross tournaments for two players. - Map passing networks for a specific match using
x,y,end_x,end_ycoordinates fromget_match_events. - Track a team's season schedule and results by polling
list_matchesfor fixture dates, scores, and opponent IDs. - Identify high-performing teams in a league by comparing
possession,rating, andgoalsfromget_team_statsacross multiple team IDs. - Automate scouting reports by querying
searchfor player names and then pulling full seasonal records viaget_player_stats. - Analyze pressing and defensive events by filtering
event_typeandoutcomefields inget_match_eventsfor a specific team. - Resolve team or player slugs for URL construction by using the
slugfield returned from thesearchendpoint.
| 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, and does it cover live matches?+
minute, second, player_id, player_name, team_id, event_type, outcome, pass coordinates (x, y, end_x, end_y), and per-event qualifiers. The endpoint only covers completed matches — in-progress live match data is not currently returned. You can fork this API on Parse and revise it to add a live-match polling endpoint.Can I retrieve historical seasons beyond the current season for a team's fixtures?+
list_matches endpoint returns fixtures and results for the current season. Historical season fixture lists are not currently covered. The API does surface multi-season records in get_player_stats and get_team_stats, but fixture-level history per team is outside the current scope. You can fork the API on Parse and revise it to add a historical fixtures endpoint.Are league table standings or tournament-level standings available?+
How are player and team IDs structured, and can I use them without calling search first?+
player_id or team_id) that correspond to WhoScored's internal entity identifiers. If you already know a numeric ID from a WhoScored URL, you can pass it directly to get_player_stats, get_team_stats, or list_matches without calling search first. The search endpoint is the discovery mechanism when you only have a name.