WhoScored APIwhoscored.com ↗
Access WhoScored player and team search plus seasonal performance statistics — ratings, goals, assists, pass success, possession, and more via 3 endpoints.
What is the WhoScored API?
The WhoScored API exposes 3 endpoints for querying football player and team data from WhoScored.com. Use the search endpoint to find players and teams by name, retrieving IDs and slugs you can pass to get_player_stats or get_team_stats to pull per-season records across tournaments — including match ratings, goals, assists, pass success rate, shots per game, and possession figures.
curl -X GET 'https://api.parse.bot/scraper/fefeab4f-b650-45ef-9b05-42622fe3619a/search?query=Barcelona' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace whoscored-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
from parse_apis.whoscored_football_statistics_api import WhoScored, Player, SearchResult, PlayerStats, TeamStats
ws = WhoScored()
# Search for a player
result = ws.players.search(query="Messi")
# Iterate over found players
for player in result.players:
print(player.name, player.team, player.age)
# Get detailed stats for a known player
messi = ws.player(player_id=11119)
stats = messi.stats()
for season in stats.player_table_stats:
print(season.season_name, season.tournament_name, season.rating, season.goal)
# Get team stats
barca = ws.team(team_id=65)
team_stats = barca.stats()
for tournament in team_stats.team_table_stats:
print(tournament.tournament_name, tournament.rating, tournament.possession)
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 Players and Teams
The search endpoint accepts a free-text query string and returns two arrays: players (with player_id, slug, name, team, and age) and teams (with team_id, slug, name, and country). Searches that match only players return an empty teams array, and vice versa. Results are unordered and unpaginated, so the query should be specific enough to narrow results to the target entity. The player_id and team_id values returned here are the required inputs for the stats endpoints.
Player Seasonal Statistics
get_player_stats takes a numeric player_id and returns a playerTableStats array of per-season records across every tournament the player has appeared in. Each record includes fields such as rating, goals, apps, assists, passSuccess, minsPlayed, and shotsPerGame. The statColumns array lists every column present in those records, so you can introspect what fields are available without inspecting individual rows. A paging object exposes currentPage, totalPages, and totalResults for navigating larger result sets.
Team Seasonal Statistics
get_team_stats mirrors the player stats endpoint but for teams. Pass a numeric team_id from the search results to receive teamTableStats records broken down by tournament and season. Fields include rating, goals, possession, passSuccess, apps, and cards data. The same statColumns and paging structures are present, giving consistent response shapes across both stats endpoints.
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?+
- Compare a player's season ratings and goals across multiple tournaments using
playerTableStatsrecords. - Track a club's possession percentage and pass success trends across seasons with
get_team_stats. - Build a player search tool that resolves names to WhoScored
player_idvalues via thesearchendpoint. - Identify which tournaments a player has participated in and their appearances (
apps) per competition. - Aggregate team-level goals and shots data across domestic and European tournaments in a single call.
- Feed per-season
ratingfields into a scouting or recruitment model for player comparison. - Resolve team slugs and country fields from search to enrich a football database with WhoScored identifiers.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. 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_player_stats` return, and can I filter results by a specific tournament or season?+
playerTableStats array. There is no built-in filter parameter for tournament or season — filtering must be done client-side after receiving the full result set.Does the search endpoint support partial name matching or fuzzy queries?+
search endpoint performs full-text search over WhoScored's player and team database. Results are unordered and unpaginated, so very short or ambiguous queries may return a large mixed array. There is no explicit fuzzy or prefix-match parameter — the behavior reflects the source site's search logic.Does this API cover match-level data, such as individual match ratings or lineups?+
get_player_stats and get_team_stats, plus name-based lookup via search. Match-level records, lineups, and event data are not exposed. You can fork this API on Parse and revise it to add an endpoint for match-level statistics.Is historical data available for players who have moved clubs, or only their current team?+
search endpoint returns a player's current team at query time. However, get_player_stats returns records across all seasons and tournaments in WhoScored's database for that player, so historical performance from previous clubs is included in the playerTableStats array as long as WhoScored has the data on file.