nascar-api

A typed Python client for NASCAR's undocumented Content Feed (CF) API. Provides access to both historical and live race data across the Cup, Xfinity, and Truck series.

Built with Pydantic for data validation and tenacity for automatic retry logic.

Installation

pip install nascar-api

Or with Poetry:

poetry add nascar-api

Quick Start

from nascar_api.repos import HistoricNascarRepo
from nascar_api.enums import Series

repo = HistoricNascarRepo()

# Get all Cup Series races from 2024
races = repo.get_races(2024, Series.CUP)

for race in races:
    print(f"{race.race_name} at {race.track_name} — Winner ID: {race.winner_driver_id}")

Features

Historical Data

from nascar_api.repos import HistoricNascarRepo
from nascar_api.enums import Series

repo = HistoricNascarRepo()

# Race schedules and results for any year/series
races = repo.get_races(2024, Series.CUP)

# Lap-by-lap timing data
lap_times = repo.get_lap_times(2024, Series.CUP, race_id=5161)

# Lap notes (cautions, incidents, flags)
lap_notes = repo.get_lap_notes(2024, Series.CUP, race_id=5161)

# Pit stop data with detailed timing and tire info
pit_stops = repo.get_pit_data(Series.CUP, race_id=5161)

# Full weekend feed (results, cautions, leaders, stages, pit reports)
weekend = repo.get_weekend_data(2024, Series.CUP, race_id=5161)

# Loop statistics (driver performance metrics)
loop_stats = repo.get_loopstats(2024, Series.CUP, race_id=5161)

Live Race Data

from nascar_api.repos import LiveNascarFeedRepo
from nascar_api.enums import Series

repo = LiveNascarFeedRepo()

# Current flag state across all active races
flags = repo.get_live_flags()

# Full live race feed (positions, speeds, pit stops, vehicle data)
feed = repo.get_live_feed()
for vehicle in feed.vehicles:
    print(f"#{vehicle.vehicle_number} — P{vehicle.running_position}, "
          f"Last Lap: {vehicle.last_lap_speed:.1f} mph")

# Live points standings
points = repo.get_live_points(Series.CUP, race_id=5161)

API Reference

Repositories

Models

Enums

Retry Behavior

All API requests automatically retry up to 3 times with a 2-second delay on transient failures (5xx errors, JSON decode errors). Requests that receive a 403 (data not available for that endpoint/year) do not retry.

Requirements

• Python 3.11+
• No API key required — NASCAR's CF API is publicly accessible

License

MIT