pynascar 0.1.0

Unofficial tools for NASCAR data

PyNASCAR

This is obviously not associated with NASCAR and is an unofficial project

Overview

pynascar is a Python package for nascar race data acquisition. Read the Full Documentation for all data functions and types.

Installation

Install via pip

pip install pynascar

updates will be made regularly until all public API endpoints are hit

Race Data Example:

You can use this package to obtain data from any existing or live race including lap times, pit stop laps and times, all in race flags and all race control messages. The full schedule as well.

from pynascar import Schedule, Race, set_options

# Create a local cache that saves the data. This is optional but we do not want to download data from NASCAR over and over
set_options(cache_enabled=True, cache_dir=".cache/pynascar", df_format="parquet")

# Get the schedule for the current year
schedule = Schedule(year= 2025, series_id = 1)

# This function isnt currently added. Will be in v 0.1.1
race_info = schedule.next_race()
race_year = race_info['race_year']
next_race_id = race_info['race_id']
race_data = Race(year = 2025, series_id = 2, race_id = next_race_id)

Documentation

coming next

Series IDs: 1 - Cup 2 - Xfinity 3 - Trucks

schedule columns:

Index(['race_id', 'series_id', 'race_season', 'race_name', 'race_type_id',
       'restrictor_plate', 'track_id', 'track_name', 'date_scheduled',
       'race_date', 'qualifying_date', 'tunein_date', 'scheduled_distance',
       'actual_distance', 'scheduled_laps', 'actual_laps', 'stage_1_laps',
       'stage_2_laps', 'stage_3_laps', 'number_of_cars_in_field',
       'pole_winner_driver_id', 'pole_winner_speed', 'number_of_lead_changes',
       'number_of_leaders', 'number_of_cautions', 'number_of_caution_laps',
       'average_speed', 'total_race_time', 'margin_of_victory', 'race_purse',
       'race_comments', 'attendance', 'infractions', 'schedule',
       'radio_broadcaster', 'television_broadcaster',
       'satellite_radio_broadcaster', 'master_race_id', 'inspection_complete',
       'playoff_round', 'is_qualifying_race', 'qualifying_race_no',
       'qualifying_race_id', 'has_qualifying', 'winner_driver_id',
       'pole_winner_laptime'],
      dtype='object')

Race Laps:

race_data.laps

Index	Driver	Car	Manufacturer	lap	time	speed	Pos
2527	Daniel Suarez	99	Chv	100	0 days 00:00:00.000000047	189.861	13
1586	Austin Cindric	2	Frd	171	0 days 00:00:00.000000046	193.861	1
3694	Justin Haley	7	Chv	54	0 days 00:00:00.000000047	190.010	39
54	Bubba Wallace	23	Tyt	1	0 days 00:00:00.000000052	172.206	3
4389	* Corey LaJoie	01	Frd	143	0 days 00:00:00.000000047	188.119	31
2679	Ty Dillon	10	Chv	50	0 days 00:00:00.000000047	191.152	34

Race Laps:

race_data.pit_stops

Driver	Lap	Manufacturer	pit_in_flag_status	pit_out_flag_status	pit_in_race_time	pit_out_race_time	total_duration	box_stop_race_time	box_leave_race_time	...	pit_stop_type	left_front_tire_changed	left_rear_tire_changed	right_front_tire_changed	right_rear_tire_changed	previous_lap_time	next_lap_time	pit_in_rank	pit_out_rank	positions_gained_lost	0	1	2	3	4
William Byron	10	Chv	2	2	666.638	882.668	11614.947	676.235	12258.555	...	OTHER	False	False	False	False	0	0	1	1	0
Austin Cindric	10	Frd	2	2	668.834	885.746	11615.829	696.015	12278.615	...	TWO_WHEEL_CHANGE_RIGHT	False	False	True	True	0	0	2	2	0
Ty Dillon	10	Chv	2	2	669.462	887.356	11616.811	688.815	12264.695	...	OTHER	False	False	False	False	0	0	3	3	0
Chase Briscoe	10	Tyt	2	2	670.433	889.714	11618.198	703.315	12283.555	...	OTHER	False	False	False	False	0	0	4	4	0
Joey Logano	10	Frd	2	2	672.424	903.406	11629.899	700.895	12294.975	...	FOUR_WHEEL_CHANGE	True	True	True	True	0	0	6	5	1

Race Events:

race_data.events

	Lap	Flag_State	Flag	note	driver_ids
0	0	8	Warm Up	To the rear: #5, #6, #7, #35, #48, #54, #88, ...	[4030, 1816, 4172, 4269, 4045, 4368, 4469, 411...
1	1	1	Green	#19 leads the field to the green on the inside...	[4228, 4180, 4228]
2	3	1	Green	#19, #23 and #2 get single file in front of th...	[4228, 4025, 4180]
3	5	1	Green	#77 reports fuel pressure issues and loses the...	[4326]

TODO

#	Item	Progress	Notes
1	Add Caching	https://progress-bar.xyz/90	Works. Needs to prevent writing when no data
2	Add Driver Stats	https://progress-bar.xyz/90	Collected for stats. Works but is inefficient. Names need to be in sync
3	Add Lap Stats	https://progress-bar.xyz/50	Laps exist within Race. Will add functions to analyze
3	Add Pit Stats	https://progress-bar.xyz/50	Pits exist within Race and Driver. Will add functions to analyze
4	Add tests	https://progress-bar.xyz/0	No work done
5	Add Laps from Practice/Qualifying	https://progress-bar.xyz/0	This end point may not exist