Basketball-Reference APIbasketball-reference.com ↗
Access NBA player stats, team records, season leaders, and game logs from Basketball-Reference.com via 5 structured endpoints.
What is the Basketball-Reference API?
This API exposes 5 endpoints covering basketball statistics from Basketball-Reference.com, spanning player search, per-game career stats, team season records, statistical leaderboards, and individual game logs. The get_player_stats endpoint returns season-by-season shooting percentages, points, rebounds, assists, steals, blocks, and turnovers alongside career averages. Player identifiers like curryst01 or jamesle01 retrieved from search_players flow directly into the other endpoints.
curl -X GET 'https://api.parse.bot/scraper/0ca9e89b-7966-4e82-8785-1f20651c8c12/search_players?query=curry' \ -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 basketball-reference-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.
"""Walkthrough: Basketball Reference SDK — bounded, re-runnable; every call capped."""
from parse_apis.basketball_reference_com_api import BasketballReference, PlayerNotFound
client = BasketballReference()
# Search for players by name
for player in client.players.search(query="curry", limit=3):
print(player.name, player.player_id, player.seasons_active)
# Get detailed career stats for a specific player
steph = client.player(player_id="curryst01")
stats = steph.stats()
print(stats.player_name, stats.position)
print("Career PPG:", stats.career_stats.points_per_game)
for season in stats.seasons[:2]:
print(season.season, season.team, season.points_per_game)
# Get a player's game log for a season
log = steph.game_log(season="2025")
for game in log.games[:3]:
print(game.date, game.opponent, game.points, game.assists)
# Get team season stats
team = client.teams.get(team_id="LAL", season="2025")
print(team.team_name, team.record, team.conference)
print("PPG:", team.team_stats.points_per_game)
# Get season statistical leaders
leaders = client.leader_boards.get(season="2025", stat_category="pts_per_g")
print(leaders.category_name)
for entry in leaders.leaders[:3]:
print(entry.rank, entry.player_name, entry.team, entry.value)
# Typed error handling
try:
bad = client.player(player_id="nonexistent99").stats()
except PlayerNotFound as e:
print(f"Player not found: {e.player_id}")
print("exercised: players.search, player.stats, player.game_log, teams.get, leader_boards.get")
Search for basketball players by name. Returns matching players from NBA, ABA, BAA, WNBA, and international leagues with their identifiers and active seasons.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | Player name search query (partial or full name). |
{
"type": "object",
"fields": {
"players": "array of matching player results with name, player_id, url, seasons_active, and position"
},
"sample": {
"data": {
"players": [
{
"url": "https://www.basketball-reference.com/players/c/curryst01.html",
"name": "Stephen Curry (2010-2026)",
"position": "",
"player_id": "curryst01",
"seasons_active": "2010-2026"
},
{
"url": "https://www.basketball-reference.com/players/c/curryde01.html",
"name": "Dell Curry (1987-2002)",
"position": "",
"player_id": "curryde01",
"seasons_active": "1987-2002"
}
]
},
"status": "success"
}
}About the Basketball-Reference API
Player Data
The search_players endpoint accepts a partial or full player name and returns an array of matching results with each player's player_id, url, seasons_active, and listed position. This covers players from the NBA, ABA, BAA, WNBA, and international leagues. The returned player_id is the key input for get_player_stats and get_game_log.
get_player_stats delivers per-game statistics for every season a player appeared in, including shooting splits (field goal, three-point, and free throw percentages), points, rebounds, assists, steals, blocks, and turnovers. The career_stats object in the response rolls up those averages across all seasons.
Team and League Data
get_team_stats takes a three-letter team abbreviation (LAL, BOS, GSW, etc.) and a four-digit season-ending year, returning the team's win-loss record, conference finish position, head coach, conference name, and aggregate per-game team averages for that season.
get_season_leaders returns the top 20 players ranked by a chosen stat category — such as pts_per_g, trb_per_g, or ast_per_g — for a given season. Each entry includes the player's rank, name, player_id, team affiliation, and numerical value. get_game_log goes further down the individual level, returning every regular-season game for a player in a specified season with date, opponent, game result, full box score stats, and plus/minus.
The Basketball-Reference API is a managed, monitored endpoint for basketball-reference.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when basketball-reference.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 basketball-reference.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?+
- Track a player's scoring and efficiency trends across multiple seasons using
get_player_statsseason arrays. - Build a season leaderboard table for any stat category using
get_season_leaderswithpts_per_gorast_per_g. - Compare team win-loss records and per-game averages across franchises using
get_team_stats. - Identify which games a player had their best plus/minus ratings in a season via
get_game_log. - Populate a player search autocomplete by hitting
search_playerswith partial name input. - Analyze home/away splits or back-to-back performance using the date and opponent fields from
get_game_log. - Cross-reference coaching changes with team performance by pairing
coachandrecordfields fromget_team_stats.
| 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 Basketball-Reference.com have an official developer API?+
What does `get_game_log` return, and does it cover playoff games?+
get_game_log returns regular-season game entries for a player in a given season, each with date, opponent, result, points, rebounds, assists, shooting splits, and plus/minus. Playoff game logs are not currently included. The API covers regular-season data. You can fork it on Parse and revise it to add a playoff game log endpoint.What stat categories does `get_season_leaders` support?+
stat_category string such as pts_per_g (points per game), trb_per_g (rebounds per game), and ast_per_g (assists per game). The response includes a category_name field that translates the slug into a human-readable label. Other advanced categories like win shares or player efficiency rating are not currently covered. You can fork the API on Parse and revise it to add those stat identifiers.Can I retrieve advanced stats like PER, win shares, or box plus/minus from `get_player_stats`?+
get_player_stats returns per-game statistics: shooting percentages, points, rebounds, assists, steals, blocks, and turnovers, plus career averages. Advanced metrics such as PER, win shares, or box plus/minus are not currently exposed. You can fork the API on Parse and revise it to pull the advanced stats table.Does the player search cover WNBA and historical leagues?+
search_players returns results from the NBA, ABA, BAA, WNBA, and international leagues, along with each player's seasons_active range. The response does not distinguish league type as a separate filterable field, so filtering by league would need to be done on your end based on the returned data.