# Basketball Reference Scraper | NBA Stats and History (`parseforge/basketball-reference-scraper`) Actor Pull NBA player, team, and game stats from Basketball Reference including box scores, season averages, advanced metrics, standings, awards, and historical records. Perfect for sports analytics, fantasy tools, betting models, and basketball data journalism projects. - **URL**: https://apify.com/parseforge/basketball-reference-scraper.md - **Developed by:** [ParseForge](https://apify.com/parseforge) (community) - **Categories:** Sports, News, Other - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $19.00 / 1,000 results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ![ParseForge Banner](https://github.com/ParseForge/apify-assets/blob/ad35ccc13ddd068b9d6cba33f323962e39aed5b2/banner.jpg?raw=true) ## ๐Ÿ€ Basketball Reference Scraper > ๐Ÿš€ **Export NBA player statistics in seconds.** No API key, no login, no limits on what season or stat type you pull. > ๐Ÿ•’ **Last updated:** 2026-05-22 ยท **๐Ÿ“Š 19 fields** per record ยท **500+ players per season** ยท **NBA seasons 1950-present** The Basketball Reference Scraper extracts NBA player statistics from [Basketball Reference](https://www.basketball-reference.com), the authoritative source for basketball data. Whether you need scoring leaders, advanced efficiency metrics, or raw season totals, this actor pulls the complete player table for any season and stat type you choose. Data is scraped in real-time from the official public stats pages - no caching, no stale records, no truncation. ### Coverage - **Seasons:** NBA 1950-present (75+ seasons of historical data) - **Stat types:** Per Game, Totals, Advanced - **Players per season:** 450-550 active players - **Fields per player:** 19 data points covering scoring, playmaking, defense, and shooting efficiency ### Target Audience / Use Cases | Who | Why | |-----|-----| | Sports analysts | Build season-over-season performance comparisons | | Fantasy basketball managers | Track player stats across a full season | | Data scientists | Train prediction models on historical NBA data | | Sports journalists | Pull quick stats for game previews and recaps | | Basketball researchers | Study long-term trends in the NBA | | Developers | Power sports dashboards and apps | ### ๐Ÿ“‹ What the Basketball Reference Scraper does - Fetches the full player stats table for any NBA season from 1950 to present - Supports three stat types: Per Game averages, Season Totals, and Advanced metrics - Parses all player rows including name, team, position, age, and full stat line - Handles traded players correctly (returns the combined TOT row, not duplicates) - Converts all numeric stats to proper number types (no string parsing needed) - Limits free users to 10 items as a preview; paid users get the full dataset > ๐Ÿ’ก **Why it matters:** Basketball Reference is the gold standard for NBA stats. Every number here is the same one scouts, analysts, and broadcasters rely on. Getting it programmatically means you can build tools that stay current automatically. ### ๐ŸŽฌ Full Demo ๐Ÿšง Coming soon ### โš™๏ธ Input | Field | Type | Default | Description | |-------|------|---------|-------------| | `season` | integer | `2024` | Season year (e.g. 2024 = 2023-24 season) | | `statType` | select | `per_game` | Stats type: `per_game`, `totals`, or `advanced` | | `maxItems` | integer | `20` | Max players to return (free: 10, paid: up to 1,000,000) | **Example - Per Game leaders 2024:** ```json { "season": 2024, "statType": "per_game", "maxItems": 100 } ```` **Example - Advanced stats for a historical season:** ```json { "season": 2016, "statType": "advanced", "maxItems": 500 } ``` > โš ๏ธ **Good to Know:** Free users are limited to 10 players per run as a preview. Upgrade to a paid plan to unlock the full dataset of 500+ players per season. [Create a free account w/ $5 credit](https://console.apify.com/sign-up?fpr=vmoqkp) ### ๐Ÿ“Š Output Each record in the dataset contains the following fields: | Field | Type | Description | |-------|------|-------------| | ๐Ÿ‘ค `playerName` | string | Full player name | | ๐Ÿ€ `team` | string | Team abbreviation (e.g. LAL, BOS) | | ๐Ÿ“ `position` | string | Player position (PG, SG, SF, PF, C) | | ๐ŸŽ‚ `age` | number | Player age during that season | | ๐Ÿ”— `playerUrl` | string | Link to player's page on Basketball Reference | | ๐Ÿ“… `season` | integer | Season year (e.g. 2024) | | ๐Ÿ“Š `statType` | string | Stat type scraped (per\_game/totals/advanced) | | ๐ŸŽฎ `gamesPlayed` | number | Games played | | โฑ๏ธ `minutesPerGame` | number | Minutes per game (or total minutes for totals) | | ๐Ÿ† `points` | number | Points per game (or total) | | ๐ŸŽฏ `assists` | number | Assists per game (or total) | | ๐Ÿ’ช `rebounds` | number | Total rebounds per game (or total) | | ๐Ÿ›ก๏ธ `steals` | number | Steals per game (or total) | | ๐Ÿงฑ `blocks` | number | Blocks per game (or total) | | โŒ `turnovers` | number | Turnovers per game (or total) | | ๐ŸŽณ `fieldGoalPct` | number | Field goal percentage (0-1) | | 3๏ธโƒฃ `threePointPct` | number | 3-point percentage (0-1) | | ๐Ÿ†“ `freeThrowPct` | number | Free throw percentage (0-1) | | ๐Ÿ•’ `scrapedAt` | string | ISO timestamp of when the data was collected | | โš ๏ธ `error` | string | Error message if something went wrong | **Sample records (2023-24 season, per game):** ```json [ { "playerName": "Joel Embiid", "team": "PHI", "position": "C", "age": 29, "playerUrl": "https://www.basketball-reference.com/players/e/embiijo01.html", "season": 2024, "statType": "per_game", "gamesPlayed": 39, "minutesPerGame": 33.6, "points": 34.7, "assists": 5.6, "rebounds": 11, "steals": 1.2, "blocks": 1.7, "turnovers": 3.8, "fieldGoalPct": 0.529, "threePointPct": 0.388, "freeThrowPct": 0.883, "scrapedAt": "2026-05-22T01:29:47.698Z" }, { "playerName": "Luka Donฤiฤ‡", "team": "DAL", "position": "PG", "age": 24, "playerUrl": "https://www.basketball-reference.com/players/d/doncilu01.html", "season": 2024, "statType": "per_game", "gamesPlayed": 70, "minutesPerGame": 37.5, "points": 33.9, "assists": 9.8, "rebounds": 9.2, "steals": 1.4, "blocks": 0.5, "turnovers": 4, "fieldGoalPct": 0.487, "threePointPct": 0.382, "freeThrowPct": 0.786, "scrapedAt": "2026-05-22T01:29:47.698Z" } ] ``` ### โœจ Why choose this Actor | Feature | Benefit | |---------|---------| | ๐ŸŽ๏ธ Fast scraping | Full season of 500+ players in under 5 seconds | | ๐Ÿ“… Historical depth | Any NBA season from 1950 to present | | 3๏ธโƒฃ Three stat types | Per Game, Totals, and Advanced in one actor | | ๐Ÿ”ข Clean numbers | All stats as proper floats, not strings | | ๐Ÿ”„ Deduplication | Traded players appear once (TOT row only) | | ๐ŸŒ No login required | Fully public, no credentials needed | | ๐Ÿ’ณ Pay-per-item pricing | Only pay for what you actually collect | ### ๐Ÿ“ˆ How it compares to alternatives | Feature | This Actor | Manual CSV | NBA API | |---------|-----------|-----------|---------| | Historical seasons | โœ… 75+ years | Partial | โœ… | | Advanced stats | โœ… | Partial | โŒ | | Automation ready | โœ… | โŒ | โœ… | | No auth required | โœ… | โœ… | โŒ | | Structured output | โœ… JSON/CSV/Excel | โŒ | โœ… | | Per-game + totals | โœ… | Partial | Partial | ### ๐Ÿš€ How to use 1. [Create a free Apify account](https://console.apify.com/sign-up?fpr=vmoqkp) (includes $5 credit) 2. Open the Basketball Reference Scraper actor 3. Set your `season` year (e.g. 2024) and `statType` (per\_game, totals, or advanced) 4. Set `maxItems` to how many players you want (up to 500+ for full season) 5. Click **Run** and wait a few seconds 6. Download your dataset as JSON, CSV, or Excel ### ๐Ÿ’ผ Business use cases #### Fantasy Basketball Pull the full per-game stats table weekly to track player performance trends. Build automated alerts when a player's scoring average changes by more than 20% over 10 games. Identify waiver wire pickups based on recent performance data. #### Sports Betting Analytics Aggregate season totals across multiple years to build historical baselines. Compare team-level stats by grouping player records. Identify over/under value plays by cross-referencing player stats with betting lines. #### Content Creation Auto-generate stat-based content for sports media. Pull the latest season leaders and pipe them into a CMS or newsletter template. Schedule daily runs to keep rankings current during the season. #### Academic Research Build comprehensive datasets of NBA player performance spanning decades. Study how rule changes (hand-checking ban, three-point era, load management) affect scoring and efficiency stats over time. ### ๐Ÿ”Œ Automating Basketball Reference Scraper Connect this actor to 1,500+ apps with no-code automations: - **Make (Integromat):** Trigger nightly to update a Google Sheet with the latest standings - **Zapier:** When run completes, post top scorers to a Slack channel - **Webhooks:** Pipe results directly to your database API on completion - **Apify Scheduler:** Schedule weekly runs at the start of each week to capture fresh data ### ๐ŸŒŸ Beyond business use cases #### Research Track the evolution of the three-point shot by comparing 3PA/game across decades. Study how player longevity has changed by analyzing age distributions across eras. #### Creative Projects Build a trivia game using real historical stat lines. Create "guess the player" puzzles from anonymized stat profiles. #### Non-Profit / Education Give students a real-world dataset for statistics classes. Visualize income inequality through contract vs. performance data. #### Experimentation Test ML models for predicting MVP candidates or All-Star selections. Experiment with player clustering algorithms using the advanced metrics dataset. ### ๐Ÿค– Ask an AI assistant about this scraper You can paste this README into any AI chat (Claude, ChatGPT, etc.) and ask: - "Write a Python script that uses this data to rank players by offensive efficiency" - "How do I filter this output to only show players averaging 20+ points?" - "Build a chart showing the top 10 scorers from this dataset" The structured JSON output makes it easy to plug directly into any AI-assisted analysis workflow. ### โ“ Frequently Asked Questions #### ๐Ÿ€ What seasons does this cover? Any NBA season from 1950 to the present. Use the `season` field with the year the season ended (e.g. 2024 = 2023-24 season). #### ๐Ÿ“Š What stat types are available? Three: `per_game` (averages), `totals` (cumulative season stats), and `advanced` (efficiency metrics like TS%, usage rate). #### ๐Ÿ”„ Are traded players handled correctly? Yes. For players traded mid-season, the actor returns only the combined TOT row, avoiding duplicate records. #### ๐Ÿ’พ What formats can I export? JSON, CSV, Excel, XML - all standard Apify dataset export formats. #### ๐Ÿ•’ How long does a run take? Usually 3-8 seconds for a full season. The site is fast and the table loads in a single HTTP request. #### ๐ŸŒ Does it require a login? No. Basketball Reference's stats tables are fully public. #### ๐Ÿ’ณ How is pricing calculated? Pay per item collected. Only real player records count - errors never charge you. #### ๐Ÿ“… Can I get current season stats? Yes. Set `season` to the current year (e.g. 2025 for the 2024-25 season) to get in-progress stats. #### ๐Ÿงฑ What does "advanced" stat type include? Advanced includes efficiency stats: True Shooting % (mapped to fieldGoalPct), 3PA rate (threePointPct), games, and minutes. Scoring stats (points, assists, rebounds) are null for advanced since Basketball Reference doesn't include them in that table. #### ๐Ÿ” Can I run this on a schedule? Yes. Use Apify Scheduler to trigger weekly runs automatically, keeping your dataset fresh throughout the season. #### โŒ What happens if data is unavailable for a season? The actor pushes an error record describing the issue and exits cleanly. No partial data is returned. #### ๐Ÿ†“ What's included in the free plan? 10 players per run as a preview. [Upgrade for full access](https://console.apify.com/sign-up?fpr=vmoqkp). ### ๐Ÿ”Œ Integrate with any app Export and pipe your data to: Google Sheets - Google BigQuery - PostgreSQL - MySQL - MongoDB - Airtable - Notion - Slack - Discord - Microsoft Excel - Power BI - Tableau - Looker Studio - Zapier - Make - n8n - REST APIs - AWS S3 - Azure Blob Storage - Snowflake - Redshift - dbt ### ๐Ÿ”— Recommended Actors | Actor | Description | |-------|-------------| | [Transfermarkt Scraper](https://apify.com/parseforge/transfermarkt-scraper) | Football player values and transfer history | | [SofaScore Scraper](https://apify.com/parseforge/sofascore-scraper) | Live scores and sports statistics across all leagues | | [Chess.com Scraper](https://apify.com/parseforge/chess-com-scraper) | Chess player profiles, ratings, and game history | > ๐Ÿ’ก **Pro Tip:** browse the complete [ParseForge collection](https://apify.com/parseforge) for scrapers across 100+ data sources - sports, finance, jobs, real estate, and more. *** *This actor is an independent tool and is not affiliated with or endorsed by Sports Reference LLC or Basketball Reference. Data is accessed from publicly available web pages for informational and research purposes.* # Actor input Schema ## `season` (type: `integer`): Season year (e.g. 2024 for 2023-24 season) ## `statType` (type: `string`): Type of statistics to scrape ## `maxItems` (type: `integer`): Free users: Limited to 10 items (preview). Paid users: Optional, max 1,000,000 ## Actor input object example ```json { "season": 2024, "statType": "per_game", "maxItems": 20 } ``` # Actor output Schema ## `results` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "season": 2024, "maxItems": 20 }; // Run the Actor and wait for it to finish const run = await client.actor("parseforge/basketball-reference-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`๐Ÿ’พ Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // ๐Ÿ“š Want to learn more ๐Ÿ“–? Go to โ†’ https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "season": 2024, "maxItems": 20, } # Run the Actor and wait for it to finish run = client.actor("parseforge/basketball-reference-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("๐Ÿ’พ Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # ๐Ÿ“š Want to learn more ๐Ÿ“–? Go to โ†’ https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "season": 2024, "maxItems": 20 }' | apify call parseforge/basketball-reference-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=parseforge/basketball-reference-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Basketball Reference Scraper | NBA Stats and History", "description": "Pull NBA player, team, and game stats from Basketball Reference including box scores, season averages, advanced metrics, standings, awards, and historical records. Perfect for sports analytics, fantasy tools, betting models, and basketball data journalism projects.", "version": "1.0", "x-build-id": "JIXmliBVCZ7pgnepB" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/parseforge~basketball-reference-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-parseforge-basketball-reference-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/parseforge~basketball-reference-scraper/runs": { "post": { "operationId": "runs-sync-parseforge-basketball-reference-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/parseforge~basketball-reference-scraper/run-sync": { "post": { "operationId": "run-sync-parseforge-basketball-reference-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "season", "statType" ], "properties": { "season": { "title": "Season Year", "minimum": 1950, "maximum": 2030, "type": "integer", "description": "Season year (e.g. 2024 for 2023-24 season)" }, "statType": { "title": "Stat Type", "enum": [ "per_game", "totals", "advanced" ], "type": "string", "description": "Type of statistics to scrape", "default": "per_game" }, "maxItems": { "title": "Max Items", "minimum": 1, "maximum": 1000000, "type": "integer", "description": "Free users: Limited to 10 items (preview). Paid users: Optional, max 1,000,000" } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```