fbref.com APIfbref.com ↗
Access FBRef football data via API: player career stats, team squads, league standings, and match reports across major competitions.
curl -X GET 'https://api.parse.bot/scraper/1a8fe9ae-251c-43bc-abda-4d7469597ce8/search?query=Messi' \ -H 'X-API-Key: $PARSE_API_KEY'
Search for players or squads by name. Returns matches with their IDs and profile URLs. If an exact match is found, FBRef redirects directly to the entity page and a single result with exact=true is returned.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | Search query (player or team name) |
| entity_type | string | Type of entity to search for. Accepted values: players, squads. |
{
"type": "object",
"fields": {
"matches": "array of search result objects each containing name, url, id, and description"
},
"sample": {
"data": {
"matches": [
{
"id": "f49c4ae9",
"url": "https://fbref.com/en/players/f49c4ae9/Junior-Messias",
"name": "Junior Messias",
"description": "Junior Messias · 2019-2026 · BRA /en/players/f49c4ae9/Junior-Messias Clubs: Genoa, Crotone, Milan"
}
]
},
"status": "success"
}
}About the fbref.com API
The FBRef API exposes 5 endpoints covering football player profiles, squad statistics, league standings, and match reports drawn from FBRef.com's deep statistical database. The get_player_stats endpoint returns career-long season breakdowns including goals, assists, minutes, and per-90 metrics across every competition a player has appeared in. The search endpoint lets you resolve player and team names to the IDs required by the other endpoints.
Endpoints and Data Coverage
The API covers five distinct data surfaces. search accepts a query string and an optional entity_type filter (players or squads), returning an array of matches each with a name, url, id, and description. When FBRef identifies an exact match, the response includes a single result with exact: true. The id values returned here feed directly into get_player_stats and get_team_stats.
League Standings and Team Data
get_league_standings takes a comp_id (for example, 9 for the Premier League or 12 for La Liga) and an optional season string in YYYY-YYYY format. The response includes a standings array where each entry carries rank, team, games, wins, ties, losses, goals_for, goals_against, points, and goal difference. Omitting season returns the current season's table. get_team_stats takes a team_id (obtainable from search or standings results) and returns team_info — containing name, record, and manager — alongside a squad array with per-player rows covering position, age, games, goals, assists, cards, and per-90 metrics.
Player and Match Endpoints
get_player_stats accepts a player_id and returns a profile object (name, position, born) plus a career_stats array. Each entry in that array represents one season with a specific club and competition, providing year_id, team, comp_level, games, goals, assists, minutes played, and per-90 figures. get_match_report takes a match_id and returns a match_info object with home_team, home_score, away_team, away_score, competition, venue, and date. Match IDs can be sourced from league standings last_5_id fields or team schedule pages.
ID Resolution Workflow
All entity-specific endpoints depend on FBRef's internal ID strings rather than names. The recommended workflow is to call search first to retrieve the id for a player or squad, then pass that ID to get_player_stats or get_team_stats. Competition IDs for get_league_standings are fixed values documented in the endpoint description — for example, 20 for the Bundesliga.
- Build a season comparison tool using
career_statsentries across multiple players to track goals and assists per-90 over time. - Populate a live league table widget by polling
get_league_standingswith a specificcomp_ideach matchday. - Resolve player names to IDs via
searchas part of a fantasy football data pipeline. - Display squad depth charts by iterating over the
squadarray fromget_team_statsfor a given team and season. - Enrich a match results feed with venue, competition, and scoreline data from
get_match_report. - Track manager changes by monitoring the
managerfield inteam_infoacross consecutive seasons. - Cross-reference a player's
comp_levelhistory fromcareer_statsto filter only top-division seasons.
| 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 | 250 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 FBRef have an official developer API?+
What does `get_player_stats` return and how granular is the breakdown?+
get_player_stats returns a career_stats array where each row represents one season at one club in one competition. Fields include year_id, team, comp_level, games, goals, assists, minutes, and per-90 metrics. This means a player who appeared in both a league and a cup in the same season will have separate rows for each competition.Does the API cover advanced metrics like expected goals (xG) or passing statistics?+
Are historical seasons available for all competitions, or only recent ones?+
season parameter on get_league_standings and get_team_stats accepts any YYYY-YYYY string, so historical seasons are requestable. Coverage depth depends on what FBRef has indexed for each competition — major leagues like the Premier League and La Liga have deeper historical records than lower divisions. For competitions with limited historical data, responses may be incomplete.Does the API return player photos, contract details, or transfer history?+
profile object from get_player_stats contains name, position, and born. Contract details and transfer history are not covered by any current endpoint. You can fork this API on Parse and revise it to extract those fields if FBRef surfaces them on a player's page.