| Name | pynascar JSON |
| Version |
0.2.1
JSON |
| download |
| home_page | None |
| Summary | Unofficial tools for NASCAR data |
| upload_time | 2025-08-26 21:25:52 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | MIT |
| keywords |
nascar
motorsport
data
api
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
## PyNASCAR
###### This is obviously not associated with NASCAR and is an unofficial project
## Overview
`pynascar` is a Python package for nascar race data acquisition and hopefully analysis
## Installation
Install via pip
```bash
pip install pynascar
```
updates will be made regularly until all public API endpoints are hit
## Quickstart
You can use this package to obtain data from the schedule or from any existing or live race including lap times, pit stop laps and times, all in race flags and all race control messages.
```python
from pynascar import Schedule, Race, set_options, get_settings
from pynascar.driver import DriversData
# Enable local caching for faster repeated runs
set_options(cache_enabled=True, cache_dir=".cache/", df_format="parquet")
# Series: 1=Cup, 2=Xfinity, 3=Trucks
year = 2025
series_id = 1
race_id = 5543
# Schedules
schedule = Schedule(year, series_id)
schedule.data.head()
# Race data (use reload=True to force network fetch even if cached)
race = Race(year, series_id, race_id, reload=True)
race.telemetry.lap_times.head()
race.telemetry.pit_stops.head()
race.events.head()
# Driver season aggregates
dd = DriversData.build(2025, 1, use_cache_only=False)
summary = dd.to_dataframe()
summary.sort_values("season_avg_position").head()
```
## Available Classes
Ill replace this with proper documentation if anyone cares. Just leave an issue.
### Schedule
```python
schedule = Schedule(year, series_id)
```
```
# DataFrames:
schedule.data - Complete race schedule
Columns: race_id, race_name, race_date, track_name, series_id, winner_driver_id, scheduled_at, track_type, plus other race metadata
# Methods:
schedule.get_finished_races() - Completed races DataFrame
schedule.get_remaining_races() - Upcoming races DataFrame
schedule.most_recent_race() - Single row with latest completed race
schedule.next_race() - Single row with next scheduled race
```
### Race
```python
race = Race(year, series_id, race_id, reload=False)
```
```
# Results DataFrames:
race.results.results - Main race results
Columns: driver_id, driver_name, car_number, manufacturer, sponsor, team, team_id, qualifying_order, qualifying_position, qualifying_speed, starting_position, finishing_position, laps_completed, points, playoff_points
race.results.stage_1 - Stage 1 results (when available)
race.results.stage_2 - Stage 2 results (when available)
race.results.stage_3 - Stage 3 results (when available)
Columns: driver_id, driver_name, car_number, stage_number, position, stage_points
race.results.cautions - Caution periods
Columns: start_lap, end_lap, caution_type, comment, flag_state
race.results.lead_changes - Race leaders by lap
Columns: start_lap, end_lap, driver_name, car_number
race.results.practice - Practice session results
Columns: driver_id, driver_name, manufacturer, practice_name, position, lap_time, speed, total_laps, delta_to_leader, practice_number
race.results.qualifying - Qualifying results
Columns: driver_id, driver_name, manufacturer, qualifying_name, position, lap_time, speed, total_laps, delta_to_leader, qualifying_number
# Telemetry DataFrames:
race.telemetry.lap_times - Lap-by-lap timing data
Columns: driver_name, car_number, manufacturer, Lap, lap_time, lap_speed, position, driver_id
race.telemetry.pit_stops - Pit stop data
Columns: driver_name, 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_duration, in_travel_duration, out_travel_duration, 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, driver_id, car_number
race.telemetry.events - Race events and flags
Columns: Lap, Flag_State, Flag, note, driver_ids
# Driver Statistics DataFrames:
race.driver_data.drivers - Basic driver statistics
Columns: driver_id, driver_name, start_position, mid_position, position, closing_position, closing_laps_diff, best_position, worst_position, avg_position, passes_green_flag, passing_diff, passed_green_flag, quality_passes, fast_laps, top15_laps, lead_laps, laps, rating
race.driver_data.driver_stats_advanced - Advanced driver statistics
Columns: driver_id, driver_name, car_number, manufacturer, sponsor_name, best_lap, best_lap_speed, best_lap_time, laps_position_improved, fastest_laps_run, passes_made, times_passed, passing_differential, quality_passes, position_differential_last_10_percent
```
### DriversData
```python
dd = DriversData.build(year, series_id, use_cache_only=False)
```
```
# DataFrames:
dd.to_dataframe() - Season summary for all drivers
Columns: driver_id, driver_name, team, car_number, manufacturer, total_races, total_points, total_playoff_points, wins, top5s, top10s, total_leader_laps, total_passes_green_flag, total_passed_green_flag, plus averages of all race metrics
dd.race_dataframe(race_id) - Single race data for all drivers
Columns: All race metrics for specific race including driver_id, driver_name, team, car_number, manufacturer, race_id, finishing_position, starting_position, points, stage_points, avg_lap_speed, fastest_lap, pit_stops, etc.
dd.all_races_dataframe() - All races combined for all drivers
Columns: Same as race_dataframe() but for all races in the season
dd.driver_season_dataframe(driver_id) - All races for a specific driver
Columns: Same as race_dataframe() but filtered to one driver across all races
dd.driver_pit_stops(driver_id, race_id=None) - Pit stops for specific driver
Columns: Same as race.telemetry.pit_stops but filtered to specific driver, optionally by race
# Individual Driver Access:
dd.get_driver(driver_id) - Returns Driver object with race_data dict and pit_stops_df
```
## Documentation
Series IDs:
1 - Cup
2 - Xfinity
3 - Trucks
## Data Output Examples
### Schedule
Example output:
| race_id | series_id | race_season | race_name | track_name | date_scheduled | track_type |
|---------|-----------|-------------|--------------------------------|-----------------------------------|-----------------------|----------------|
| 5546 | 1 | 2025 | DAYTONA 500 | Daytona International Speedway | 2025-02-16T14:30:00 | superspeedway |
| 5547 | 1 | 2025 | Ambetter Health 400 | Atlanta Motor Speedway | 2025-02-23T15:00:00 | intermediate |
| 5551 | 1 | 2025 | EchoPark Automotive Grand Prix | Circuit of The Americas | 2025-03-02T15:30:00 | road course |
---
### Race Laps
| driver_name | car_number | manufacturer | lap | lap_time | lap_speed | position |
|---------------|------------|--------------|-----|----------|-----------|----------|
| Kyle Busch | 8 | Chv | 53 | 26.06s | 115.95 | 25 |
| Zane Smith | 38 | Frd | 16 | 26.07s | 115.94 | 24 |
| Austin Cindric| 2 | Frd | 17 | 29.31s | 89.47 | 29 |
---
### Pit Stops
| driver_name | lap | manufacturer | total_duration | pit_stop_type | car_number |
|---------------------|-----|--------------|----------------|---------------|------------|
| Ryan Blaney | 0 | Frd | 25.04s | OTHER | 12 |
| Shane Van Gisbergen | 0 | Chv | 24.85s | OTHER | 88 |
| Chase Briscoe | 0 | Tyt | 25.10s | OTHER | 19 |
---
### Race Events
| lap | flag_state | flag | note |
|-----|------------|---------|---------------------------------------------|
| 0 | 8 | Warm Up | To the rear: #5, #6, #7, #35, #48, ... |
| 1 | 1 | Green | #19 leads the field to the green... |
| 3 | 1 | Green | #19, #23, #2 get single file in front... |
| 5 | 1 | Green | #77 reports fuel pressure issues... |
---
### Race Driver Data
| driver_name | start_position | avg_position | best_position | worst_position | fast_laps | lead_laps | rating |
|----------------------|----------------|--------------|---------------|----------------|-----------|-----------|--------|
| Shane Van Gisbergen | 2 | 4.04 | 1 | 23 | 18 | 38 | 143.72 |
---
## Visualizations (Examples)
Below are example plots that can be generated with the package an example of that is in the examples folder:
- **Average Speed per Driver**
- **Average Position Difference**
- **Quality Passes per race**
## TODO
| # | Item | Progress | Notes |
| --- | --------------------------------- | --------------------------- | ----------------------------------------------------------------------- |
| 1 | Add Caching |  | Works. Needs to prevent writing when no data |
| 2 | Add Driver Stats |  | Collected for stats. Works but is inefficient. Names need to be in sync |
| 3 | Add Lap Stats |  | Laps exist within Race. Will add functions to analyze |
| 3 | Add Pit Stats |  | Pits exist within Race and Driver. Will add functions to analyze |
| 4 | Add tests |  | No work done |
| 5 | Add Laps from Practice/Qualifying |  | This end point may not exist |
## Acknowledgements
A few redditors found and plotted some of the routes a few years ago which is where i started with this:
https://github.com/ooohfascinating/NascarApi
Raw data
{
"_id": null,
"home_page": null,
"name": "pynascar",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "nascar, motorsport, data, api",
"author": null,
"author_email": "ab5525 <admin@jakbytes.com>",
"download_url": "https://files.pythonhosted.org/packages/a8/24/69c544ce1b49e747bd13d14068313a27a2c022756e12f71fc432b207695f/pynascar-0.2.1.tar.gz",
"platform": null,
"description": "## PyNASCAR\n\n###### This is obviously not associated with NASCAR and is an unofficial project\n\n## Overview\n\n`pynascar` is a Python package for nascar race data acquisition and hopefully analysis\n\n## Installation\n\nInstall via pip\n\n```bash\npip install pynascar\n```\n\nupdates will be made regularly until all public API endpoints are hit\n\n\n## Quickstart\n\nYou can use this package to obtain data from the schedule or from any existing or live race including lap times, pit stop laps and times, all in race flags and all race control messages.\n\n```python\nfrom pynascar import Schedule, Race, set_options, get_settings\nfrom pynascar.driver import DriversData\n\n# Enable local caching for faster repeated runs\nset_options(cache_enabled=True, cache_dir=\".cache/\", df_format=\"parquet\")\n\n# Series: 1=Cup, 2=Xfinity, 3=Trucks\nyear = 2025\nseries_id = 1\nrace_id = 5543\n\n# Schedules\nschedule = Schedule(year, series_id)\nschedule.data.head()\n\n# Race data (use reload=True to force network fetch even if cached)\nrace = Race(year, series_id, race_id, reload=True)\nrace.telemetry.lap_times.head()\nrace.telemetry.pit_stops.head()\nrace.events.head()\n\n# Driver season aggregates\ndd = DriversData.build(2025, 1, use_cache_only=False)\nsummary = dd.to_dataframe()\nsummary.sort_values(\"season_avg_position\").head()\n```\n\n## Available Classes\n\nIll replace this with proper documentation if anyone cares. Just leave an issue. \n\n### Schedule\n```python\nschedule = Schedule(year, series_id)\n```\n```\n# DataFrames:\nschedule.data - Complete race schedule\n Columns: race_id, race_name, race_date, track_name, series_id, winner_driver_id, scheduled_at, track_type, plus other race metadata\n\n# Methods:\nschedule.get_finished_races() - Completed races DataFrame\nschedule.get_remaining_races() - Upcoming races DataFrame \nschedule.most_recent_race() - Single row with latest completed race\nschedule.next_race() - Single row with next scheduled race\n```\n\n### Race\n```python\nrace = Race(year, series_id, race_id, reload=False)\n```\n```\n# Results DataFrames:\nrace.results.results - Main race results\n Columns: driver_id, driver_name, car_number, manufacturer, sponsor, team, team_id, qualifying_order, qualifying_position, qualifying_speed, starting_position, finishing_position, laps_completed, points, playoff_points\n\nrace.results.stage_1 - Stage 1 results (when available)\nrace.results.stage_2 - Stage 2 results (when available)\nrace.results.stage_3 - Stage 3 results (when available)\n Columns: driver_id, driver_name, car_number, stage_number, position, stage_points\n\nrace.results.cautions - Caution periods\n Columns: start_lap, end_lap, caution_type, comment, flag_state\n\nrace.results.lead_changes - Race leaders by lap\n Columns: start_lap, end_lap, driver_name, car_number\n\nrace.results.practice - Practice session results\n Columns: driver_id, driver_name, manufacturer, practice_name, position, lap_time, speed, total_laps, delta_to_leader, practice_number\n\nrace.results.qualifying - Qualifying results\n Columns: driver_id, driver_name, manufacturer, qualifying_name, position, lap_time, speed, total_laps, delta_to_leader, qualifying_number\n\n# Telemetry DataFrames:\nrace.telemetry.lap_times - Lap-by-lap timing data\n Columns: driver_name, car_number, manufacturer, Lap, lap_time, lap_speed, position, driver_id\n\nrace.telemetry.pit_stops - Pit stop data\n Columns: driver_name, 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_duration, in_travel_duration, out_travel_duration, 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, driver_id, car_number\n\nrace.telemetry.events - Race events and flags\n Columns: Lap, Flag_State, Flag, note, driver_ids\n\n# Driver Statistics DataFrames:\nrace.driver_data.drivers - Basic driver statistics\n Columns: driver_id, driver_name, start_position, mid_position, position, closing_position, closing_laps_diff, best_position, worst_position, avg_position, passes_green_flag, passing_diff, passed_green_flag, quality_passes, fast_laps, top15_laps, lead_laps, laps, rating\n\nrace.driver_data.driver_stats_advanced - Advanced driver statistics\n Columns: driver_id, driver_name, car_number, manufacturer, sponsor_name, best_lap, best_lap_speed, best_lap_time, laps_position_improved, fastest_laps_run, passes_made, times_passed, passing_differential, quality_passes, position_differential_last_10_percent\n```\n\n### DriversData\n```python\ndd = DriversData.build(year, series_id, use_cache_only=False)\n```\n```\n# DataFrames:\ndd.to_dataframe() - Season summary for all drivers\n Columns: driver_id, driver_name, team, car_number, manufacturer, total_races, total_points, total_playoff_points, wins, top5s, top10s, total_leader_laps, total_passes_green_flag, total_passed_green_flag, plus averages of all race metrics\n\ndd.race_dataframe(race_id) - Single race data for all drivers\n Columns: All race metrics for specific race including driver_id, driver_name, team, car_number, manufacturer, race_id, finishing_position, starting_position, points, stage_points, avg_lap_speed, fastest_lap, pit_stops, etc.\n\ndd.all_races_dataframe() - All races combined for all drivers\n Columns: Same as race_dataframe() but for all races in the season\n\ndd.driver_season_dataframe(driver_id) - All races for a specific driver\n Columns: Same as race_dataframe() but filtered to one driver across all races\n\ndd.driver_pit_stops(driver_id, race_id=None) - Pit stops for specific driver\n Columns: Same as race.telemetry.pit_stops but filtered to specific driver, optionally by race\n\n# Individual Driver Access:\ndd.get_driver(driver_id) - Returns Driver object with race_data dict and pit_stops_df\n```\n\n\n## Documentation\n\nSeries IDs:\n1 - Cup\n2 - Xfinity\n3 - Trucks\n\n\n## Data Output Examples\n\n### Schedule\nExample output:\n\n| race_id | series_id | race_season | race_name | track_name | date_scheduled | track_type |\n|---------|-----------|-------------|--------------------------------|-----------------------------------|-----------------------|----------------|\n| 5546 | 1 | 2025 | DAYTONA 500 | Daytona International Speedway | 2025-02-16T14:30:00 | superspeedway |\n| 5547 | 1 | 2025 | Ambetter Health 400 | Atlanta Motor Speedway | 2025-02-23T15:00:00 | intermediate |\n| 5551 | 1 | 2025 | EchoPark Automotive Grand Prix | Circuit of The Americas | 2025-03-02T15:30:00 | road course |\n\n\n---\n\n### Race Laps\n\n| driver_name | car_number | manufacturer | lap | lap_time | lap_speed | position |\n|---------------|------------|--------------|-----|----------|-----------|----------|\n| Kyle Busch | 8 | Chv | 53 | 26.06s | 115.95 | 25 |\n| Zane Smith | 38 | Frd | 16 | 26.07s | 115.94 | 24 |\n| Austin Cindric| 2 | Frd | 17 | 29.31s | 89.47 | 29 |\n\n---\n\n### Pit Stops\n\n| driver_name | lap | manufacturer | total_duration | pit_stop_type | car_number |\n|---------------------|-----|--------------|----------------|---------------|------------|\n| Ryan Blaney | 0 | Frd | 25.04s | OTHER | 12 |\n| Shane Van Gisbergen | 0 | Chv | 24.85s | OTHER | 88 |\n| Chase Briscoe | 0 | Tyt | 25.10s | OTHER | 19 |\n\n---\n\n### Race Events\n\n| lap | flag_state | flag | note |\n|-----|------------|---------|---------------------------------------------|\n| 0 | 8 | Warm Up | To the rear: #5, #6, #7, #35, #48, ... |\n| 1 | 1 | Green | #19 leads the field to the green... |\n| 3 | 1 | Green | #19, #23, #2 get single file in front... |\n| 5 | 1 | Green | #77 reports fuel pressure issues... |\n\n---\n\n### Race Driver Data\n\n| driver_name | start_position | avg_position | best_position | worst_position | fast_laps | lead_laps | rating |\n|----------------------|----------------|--------------|---------------|----------------|-----------|-----------|--------|\n| Shane Van Gisbergen | 2 | 4.04 | 1 | 23 | 18 | 38 | 143.72 |\n\n---\n\n## Visualizations (Examples)\n\nBelow are example plots that can be generated with the package an example of that is in the examples folder:\n\n- **Average Speed per Driver**\n\n\n- **Average Position Difference**\n\n\n- **Quality Passes per race**\n\n\n## TODO\n\n| # | Item | Progress | Notes |\n| --- | --------------------------------- | --------------------------- | ----------------------------------------------------------------------- |\n| 1 | Add Caching |  | Works. Needs to prevent writing when no data |\n| 2 | Add Driver Stats |  | Collected for stats. Works but is inefficient. Names need to be in sync |\n| 3 | Add Lap Stats |  | Laps exist within Race. Will add functions to analyze |\n| 3 | Add Pit Stats |  | Pits exist within Race and Driver. Will add functions to analyze |\n| 4 | Add tests |  | No work done |\n| 5 | Add Laps from Practice/Qualifying |  | This end point may not exist |\n\n## Acknowledgements\n\nA few redditors found and plotted some of the routes a few years ago which is where i started with this:\n\nhttps://github.com/ooohfascinating/NascarApi\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Unofficial tools for NASCAR data",
"version": "0.2.1",
"project_urls": {
"Homepage": "https://github.com/ab5525/pynascar",
"Issues": "https://github.com/ab5525/pynascar/issues",
"Repository": "https://github.com/ab5525/pynascar"
},
"split_keywords": [
"nascar",
" motorsport",
" data",
" api"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b98dfa46a959ad471c42d185ec3079f612b45797e32aa25b74a1a067546931cd",
"md5": "45aa6fc66c8b21792bd6c8dae4bf4eb5",
"sha256": "bc65ca09a7ee4f75b65b7319da13fbdbc76ebce6a69a91363cd9969c6b2ed240"
},
"downloads": -1,
"filename": "pynascar-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "45aa6fc66c8b21792bd6c8dae4bf4eb5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 22492,
"upload_time": "2025-08-26T21:25:50",
"upload_time_iso_8601": "2025-08-26T21:25:50.843685Z",
"url": "https://files.pythonhosted.org/packages/b9/8d/fa46a959ad471c42d185ec3079f612b45797e32aa25b74a1a067546931cd/pynascar-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a82469c544ce1b49e747bd13d14068313a27a2c022756e12f71fc432b207695f",
"md5": "4557d5d3e8e0520dea11c891c5a93dd7",
"sha256": "eb06edc65330ec5df2ce80831beaf55fa02aeb1479a0310dc3b8575bbd733995"
},
"downloads": -1,
"filename": "pynascar-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "4557d5d3e8e0520dea11c891c5a93dd7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 23521,
"upload_time": "2025-08-26T21:25:52",
"upload_time_iso_8601": "2025-08-26T21:25:52.300314Z",
"url": "https://files.pythonhosted.org/packages/a8/24/69c544ce1b49e747bd13d14068313a27a2c022756e12f71fc432b207695f/pynascar-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-26 21:25:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ab5525",
"github_project": "pynascar",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pynascar"
}
