🏀 Basketball Reference Scraper

Get NBA and ABA data from Basketball-Reference.com with no login: full career stats by player name, a whole season's leaderboard by stat type, a team's roster and stats, a draft class with career totals, or MVP, ROY, DPOY, and All-NBA voting for any season back to 1950.

Point it at a player, a season, a team, a draft class, or an awards year, and get clean, structured stats ready for fantasy basketball, historical analysis, and sports content.

🎯 Who uses it?

🏆 Fantasy basketball players

Pull per-game averages and full season leaderboards to build rankings and find sleepers.

📚 Historical analysts

Compare eras using career per-game, totals, and advanced stats side by side.

🎓 Draft researchers

See a whole draft class's real career output, ranked by pick.

🏅 Awards and Hall of Fame projectors

Work with real MVP, DPOY, and All-NBA voting share, not just who won.

📰 Sports journalists and content creators

Get structured stats ready to drop into a chart, table, or story.

✨ What it does

• Player: resolves a name or a direct ID to full career stats: bio, per-game, totals, and advanced numbers by season, plus playoffs.
• Season: a whole year's leaderboard for one stat type (per game, totals, advanced, per 36 minutes, or per 100 possessions), with filters for team, minimum games, and minimum minutes per game.
• Team: one team-season's roster joined with that season's per-game stats.
• Draft: a full draft class with career totals and advanced metrics through the present.
• Awards: MVP, ROY, DPOY, SMOY, MIP, Clutch POY, All-NBA, All-Defense, All-Rookie, and Coach of the Year voting for one season, including real vote share.

Missing source values are returned as null, never invented.

🏆 Why this scraper

• Every mode real competitors split across two separate actors, plus three neither has. One competitor does player career stats, the other does season leaderboards. Neither has team rosters, draft classes, or awards voting.
• Real source quirks handled, not left in. A non-player "League Average" summary row that the source appends to every season leaderboard is excluded. A raw field genuinely means different things on different tables, such as career games on a draft page versus that season's team games on a Coach of the Year row, and each is labeled correctly rather than treated as one universal rename.
• Every stat table comes through complete, not only the ones that happen to be easiest to read off the page.
• No API key, no login, no browser. Reads only what a normal visitor's page load reads.

⚖️ How it compares

Checked directly against both other Basketball-Reference scrapers on Apify (their own declared input and output):

Capability	This actor	lulzasaur/basketball-reference-scraper	parseforge/basketball-reference-scraper
Player career stats (per game, totals, advanced, playoffs)	yes	yes	no
Season leaderboard (all players, one stat type)	yes	no	yes
Team rosters	yes	no	no
Draft classes	yes	no	no
Awards voting (MVP, ROY, DPOY, All-NBA, etc.)	yes	no	no
Season leaderboard filters (team, min games, min minutes)	yes	n/a	no
Declared Apify dataset schema	yes	not documented	not documented

📦 What data you get

Entity	Useful fields
Player identity & bio	Name, position, shoots, height, weight, birth date and place, high school, college, and draft info.
Career stats (player mode)	Per-game, totals, advanced, and playoff numbers, one entry per season.
Season/team/draft rows	Player, team, and the full set of stats for that table.
Awards	Category, rank, votes, points won, points possible, and award share; separate All-NBA, All-Defense, and All-Rookie team voting.
Advanced metrics	PER, Win Shares, Box Plus/Minus, and Value Over Replacement Player, under their real industry-standard names.

Every record includes scraped_at (UTC). Download your dataset from Apify as CSV, JSON, Excel, or XML.

💡 Use cases

🏆 Career stats by name

{ "mode": "player", "playerNames": ["LeBron James", "Nikola Jokić"] }

📊 A filtered season leaderboard

{ "mode": "season", "year": 2024, "statType": "per_game", "team": "BOS", "minGames": 20, "minMinutesPerGame": 15 }

🏟️ A team's full roster and stats

{ "mode": "team", "teamCode": "BOS", "teamYear": 2024 }

🎓 A draft class

{ "mode": "draft", "draftYear": 2020 }

🏅 A season's awards voting

{ "mode": "awards", "awardsYear": 2024 }

⚙️ How the input is organised

The input form is split into sections by mode:

Section	What it's for
Mode	Pick Player, Season, Team, Draft, or Awards.
Player mode	Player names or direct player IDs.
Season mode	Season year, stat type, and optional team/minimum-games/minimum-minutes filters.
Team mode	Team code and season year.
Draft mode	The draft class's year.
Awards mode	The season's year for awards voting.

Apify Free plan: every run is limited to a fixed 10-row sample. Upgrade your Apify plan to run your own settings.

💰 Pricing

Pay-per-event: a one-time 0.003 when the run starts, plus a price per result saved to your dataset. The price depends on your Apify plan tier:

Your Apify plan	Price per result
Free	0.022
Bronze	0.017
Silver	0.013
Gold / Platinum / Diamond	0.01

Approximate total cost (includes the 0.003 start fee):

Results collected	Free	Bronze	Silver	Gold+
100	$2.20	$1.70	$1.30	$1.00
1,000	$22.00	$17.00	$13.00	$10.00
10,000	$220.00	$170.00	$130.00	$100.00

New Apify accounts start with $5 in free credit.

🚀 Run it

1. Create a free Apify account with $5 in credit.
2. Open the Basketball Reference Scraper.
3. Fill in the input (or keep the prefilled example), set the maximum number of results, then click Start.
4. Export the results as CSV, Excel, JSON, or XML from the Dataset tab.

Run it programmatically through the Apify API (run-sync-get-dataset-items) or the ApifyClient for JavaScript and Python, and schedule it with Apify's built-in Scheduler.

🤖 Use with AI agents (MCP)

Give an AI agent live access to the Basketball Reference Scraper through the Model Context Protocol:

claude mcp add --transport http apify "https://mcp.apify.com?tools=normdata/basketball-reference-scraper"

Then prompt it in plain language to run the scraper and read back the results.

🔧 Troubleshooting

A player came back with an error field, why? The name didn't match a single Basketball-Reference player. Use a more complete name (e.g. "Michael Jordan" instead of "Jordan"), or paste the player ID from their own page URL (e.g. jordami01), which always resolves.

Why does one player have several rows for the same season? He was traded mid-season. Basketball-Reference lists one row per team plus a "TOT" (total) row, that's the source's own convention, not a duplicate.

My season leaderboard has fewer players than expected. Check Minimum games played and Minimum minutes per game, they drop low-usage players. Clear them for the full league.

Which field do I fill in? Only the fields marked "for

❓ FAQ

Question	Answer
Do I need an API key or login?	No. The Actor reads Basketball-Reference's public pages.
How far back does it go?	Back to the 1950 season for leaderboards and awards, and every season of a player's career.
Does it cover playoffs?	Yes, Player mode returns regular season and playoff stats.
Does it include ABA stats?	Yes, where Basketball-Reference has them.
Is the data live?	Yes, read fresh on every run, never cached.
Can I schedule it?	Yes, with Apify's built-in Scheduler, e.g. daily during the season.

🛡️ Limits & responsible use

This actor reads only Basketball-Reference.com's own public pages, with no key and no login.

An unresolved player search returns one row with an error field noting it wasn't found, rather than failing the whole run. A more complete name, or a direct player ID from the player's own URL, usually resolves it.

A player traded mid-season gets one row per team plus a "TOT" (total) row: that's the source's own real convention, not a duplicate. The trailing "League Average" summary row on season leaderboards is excluded, since it isn't a player.

Data is read live from Basketball-Reference.com on every run, never cached. This actor is independent and not affiliated with the NBA or Basketball-Reference; it reads only publicly available pages.

📧 Contact

Need a scraper for a different site, or found something wrong with this one? norm.data.scrapers@gmail.com

🧪 Local development

bun install
bun test                       # offline: table parsing, field mapping, bio parsing (real fixtures)
bun run src/main.ts             # reads storage/key_value_stores/default/INPUT.json