🏀 NBA Play-by-Play Scraper

The best NBA play-by-play scraper on Apify — clean and analysis-ready data from 2002 onward

Stop cleaning messy basketball data. Get every NBA play since 2002 - 60+ fields, proper types, zero cleanup required.

---

🎯 What does this scraper do?

This actor extracts detailed play-by-play information from every NBA game played since 2002. It delivers clean, structured data ready for analysis or integration into your applications. No manual cleanup, no parsing nightmares, no messy nested data.

Key Benefits

• ✅ 60+ fields per play - shots, fouls, rebounds, substitutions, and more
• ✅ 2002–present - 20+ seasons of historical coverage
• ✅ Clean structure - proper types and descriptive field names
• ✅ Fast & reliable - built-in validation and error handling
• ✅ Export anywhere - JSON, CSV, Excel, XML, and more

💡 No manual cleanup. No parsing nightmares. Just clean data.

---

📦 What data can you extract?

Every play returns 60+ structured data points organized into logical categories:

Category	What's Included
🎮 Game Info	Game ID, season info, game date, game phase (regulation/overtime)
🏀 Teams	Home & away team names, cities, mascots, abbreviations
⏱️ Timing	Quarter, game clock, time remaining in quarter/half/game
🎯 Play Details	Play type, category, full description, which team performed it
📊 Scoring	Current score, point differential, who's leading, tie status
🏹 Shots	Shot type, made/missed, points attempted, court coordinates
👤 Players	Players involved in each play
💰 Betting	Point spread, home favorite status
➕ And more	Timeouts, play sequences, boolean flags

💡 See the full data dictionary for all 60+ fields below.

---

🚀 How to scrape NBA play-by-play data

Quick Start Guide

Extracting the NBA play-by-play data is simple - no coding required.

1. Create account — Sign up for a free Apify account
2. Open scraper — Go to NBA Play-by-Play Scraper
3. Select inputs — Choose a team and season year
4. Run — Click Start in the Apify Console
5. Export — Download as JSON, CSV, Excel, XML, or HTML

✨ Try it FREE - No credit card required

---

📥 Inputs

The scraper requires two simple inputs:

Input	Required	Description	Example
Season	✅	4-digit year (2002–present)	2026 → 2025-26 season
Team	✅	NBA team mascot name	Raptors, Lakers, Celtics

Option A: Use Apify Console (No Code)

The easiest way to get started — just point and click.

1. Open the NBA Play-by-Play Scraper
2. Enter a season year (defaults to latest)
3. Select a team from the dropdown
4. Click Start
5. Download results

Option B: Use the API (Programmatic)

For automation, scheduling, or integration into your pipeline:

{
  "season": 2026,
  "team": "Lakers"
}

⚠️ Note: both season and team are required fields.

---

📤 Output

Results are stored in the Storage tab as a structured dataset. View directly on the platform or download in multiple formats.

Results Preview

Once scraping completes, preview your data immediately in the Output tab:

Organized Views

We've pre-configured logical dataset views to help you explore the data more easily:

Sample JSON Output

Each play returns a clean, flat JSON object with 60+ fields. Field names are descriptive and grouped by prefix (game_, time_, score_, shot_, etc.) so you can quickly find what you need.

---

📖 Data Dictionary

Complete reference for all 60+ fields returned by this scraper. Fields are grouped by prefix for easy navigation.

Field	Type	Category	Description
game_id	integer	Game	Unique identifier for the game
game_season	integer	Game	Season year (e.g., 2026 for 2025-26 season)
game_season_type	integer	Game	Season type (1 = preseason, 2 = regular, 3 = playoffs)
game_date	string	Game	Game date and tip-off time
game_phase	string	Game	Current phase (Regulation, Overtime, etc.)
home_team_id	integer	Home Team	Unique team identifier
home_team_full	string	Home Team	Full team name (e.g., "Los Angeles Lakers")
home_team_location	string	Home Team	Team city (e.g., "Los Angeles")
home_team_mascot	string	Home Team	Team mascot (e.g., "Lakers")
home_team_abbreviation	string	Home Team	Team abbreviation (e.g., "LAL")
away_team_id	integer	Away Team	Unique team identifier
away_team_full	string	Away Team	Full team name
away_team_location	string	Away Team	Team city
away_team_mascot	string	Away Team	Team mascot
away_team_abbreviation	string	Away Team	Team abbreviation
play_sequence	integer	Sequence	Order of play within the game
play_id	integer	Sequence	Unique identifier for the play
time_quarter	integer	Timing	Current quarter (1-4, 5+ for overtime)
time_quarter_display	string	Timing	Display format (e.g., "1st Quarter")
time_half	integer	Timing	Current half (1 or 2)
time_clock	string	Timing	Game clock display (e.g., "9:18")
time_clock_minutes	integer	Timing	Minutes remaining on clock
time_clock_seconds	integer	Timing	Seconds remaining on clock
time_wallclock	string	Timing	Actual timestamp of the play (UTC)
time_remaining_quarter	integer	Timing	Seconds remaining in quarter
time_remaining_half	integer	Timing	Seconds remaining in half
time_remaining_game	integer	Timing	Seconds remaining in game
play_type_id	integer	Play	Numeric code for play type
play_type	string	Play	Specific play type (e.g., "Pullup Jump Shot")
play_category	string	Play	Standardized category (Shot, Foul, Turnover, etc.)
play_description	string	Play	Full play description
play_description_short	string	Play	Abbreviated description
play_team_id	integer	Play	Team that performed the play
play_team_full	string	Play	Full name of team that performed the play
play_team_role	string	Play	Team role (Home or Away)
is_scoring_play	boolean	Flags	Whether points were scored
is_turnover	boolean	Flags	Whether play resulted in turnover
is_foul	boolean	Flags	Whether play involved a foul
is_substitution	boolean	Flags	Whether play was a substitution
score_home	integer	Scoring	Home team score after this play
score_away	integer	Scoring	Away team score after this play
score_differential	integer	Scoring	Score difference (home - away)
score_is_tie	boolean	Scoring	Whether game is tied
score_home_leading	boolean	Scoring	Whether home team is leading
score_away_leading	boolean	Scoring	Whether away team is leading
score_leader_quarter	integer	Scoring	Which team led at end of quarter (null if ongoing)
score_leader_half	integer	Scoring	Which team led at end of half (null if ongoing)
player_primary_id	integer	Players	Primary player involved in play
player_secondary_id	integer	Players	Secondary player (e.g., assister, fouled player)
player_tertiary_id	integer	Players	Third player if applicable
shot_is_attempt	boolean	Shots	Whether play was a shot attempt
shot_attempt_type	string	Shots	"Two Points" or "Three Points"
shot_result	string	Shots	"Made" or "Missed"
shot_points_attempted	integer	Shots	Points attempted (2 or 3)
shot_coordinate_x	number	Shots	Court X coordinate
shot_coordinate_y	number	Shots	Court Y coordinate
timeout_home	boolean	Timeouts	Whether home team called timeout
timeout_away	boolean	Timeouts	Whether away team called timeout
betting_spread	number	Betting	Point spread for the game
betting_home_favorite	boolean	Betting	Whether home team is favored
betting_spread_available	boolean	Betting	Whether spread data is available
betting_home_spread	number	Betting	Home team spread value

💡 Note: Some fields may be null depending on the play type — for example, shot coordinates only appear for shot attempts. All missing values are explicit null, not empty strings.

---

🔗 Sportsverse Data Suite

Building something bigger? Our ecosystem covers comprehensive sports data. Check out our other sports scrapers:

Actor	Description	Status
🏀 NBA Play-by-Play	Every play from every game (this actor)	✅ Available
🏀 NBA Team Box Scores	Team statistics per game	✅ Available
🏀 NBA Player Box Scores	Player statistics per game	✅ Available
🏀 NCAA Basketball Play-by-Play	Every play from every college game	✅ Available
🏀 NCAA Basketball Team Box Scores	College team statistics per game	✅ Available
🏀 NCAA Basketball Player Box Scores	College player statistics	✅ Available
🏒 NHL Play-by-Play	Hockey game events	🚧 Coming Soon
🏒 NHL Box Scores	Player & team statistics	🚧 Coming Soon
🏈 NFL Play-by-Play	Football play tracking	🚧 Coming Soon
🏈 NFL Box Scores	Player & team statistics	🚧 Coming Soon
⚾ MLB Play-by-Play	Baseball game events	🚧 Coming Soon
⚾ MLB Box Scores	Player & team statistics	🚧 Coming Soon

---

🤝 Support & Feedback

Found a bug? Want a new field? Have an idea?

• 🐛 Report issues in the actor comments
• 💡 Suggest features or enhancements
• 📊 Request additional fields or output tweaks

We read every message and aim to respond quickly.

---

Built with ❤️ and lots of ☕ for the sports analytics community