A RESTful NASCAR Cup Series data API covering every season since 1949: drivers, teams, tracks, race weekends, session results, and the drivers, owners and manufacturers championships. Lap-by-lap timing and stage results run from 2020, and live timing covers race weekends as they run.
**Coverage:** 1949–2026, 78 seasons.
Data is aggregated and normalized by [Blacktop](https://ocblacktop.com), which serves the same shape across every series it covers. This listing is NASCAR Cup Series only, across 25 endpoints.
## Authentication
Every request is authenticated. Send your key in the `X-JoJAPI-Key` header; the gateway holds the upstream credential and adds it on the way through. A request without a valid key returns `401 Unauthorized`.
## Endpoints
25 operations, grouped below. Every list endpoint is paginated; every detail endpoint takes the UUID that its list endpoint returns.
The `/live/` endpoints read the current state of a session that is on track and return nothing once it has finished; everything else is historical and stable. Poll live endpoints, and use the season, event and session endpoints to find the session id to poll.
### NASCAR Drivers
Every NASCAR Cup Series driver on record, with profile and career history.
| Endpoint | Description |
|---|---|
| `GET /v1/nascar/drivers` | List all NASCAR drivers |
| `GET /v1/nascar/drivers/{id}` | Get driver details by ID |
### NASCAR Teams
NASCAR Cup Series teams, with profiles and the seasons they entered.
| Endpoint | Description |
|---|---|
| `GET /v1/nascar/teams` | List all NASCAR teams |
| `GET /v1/nascar/teams/{id}` | Get team details by ID |
### NASCAR Events
The NASCAR Cup Series calendar: race weekends, the sessions inside them, and each session's results and timing.
| Endpoint | Description |
|---|---|
| `GET /v1/nascar/events` | List all NASCAR events |
| `GET /v1/nascar/events/{id}` | Get event details by ID |
| `GET /v1/nascar/events/{eventId}/sessions` | List sessions for an event |
| `GET /v1/nascar/events/{eventId}/sessions/{sessionId}` | Get a single session with results |
| `GET /v1/nascar/events/{eventId}/sessions/{sessionId}/lap-chart` | Get the lap chart for a session |
| `GET /v1/nascar/events/{eventId}/sessions/{sessionId}/lap-times` | Get individual lap times for a session |
| `GET /v1/nascar/events/{eventId}/sessions/{sessionId}/results` | Get session results only |
| `GET /v1/nascar/events/{eventId}/sessions/{sessionId}/stages` | Get stage results for a race session |
### NASCAR Seasons
NASCAR Cup Series seasons: the list of seasons, and per-season detail including the calendar and per-driver and per-team statistics.
| Endpoint | Description |
|---|---|
| `GET /v1/nascar/seasons` | List all NASCAR seasons |
| `GET /v1/nascar/seasons/{id}` | Get season details by ID |
| `GET /v1/nascar/seasons/{id}/drivers` | Get season driver statistics |
| `GET /v1/nascar/seasons/{id}/teams` | Get season team statistics |
### NASCAR Circuits
Circuits and venues on the NASCAR Cup Series calendar, past and present, with track specifications, lap records and event history.
| Endpoint | Description |
|---|---|
| `GET /v1/nascar/locations` | List all NASCAR circuit locations |
| `GET /v1/nascar/locations/{id}` | Get circuit/location details by ID |
### NASCAR Standings
NASCAR Cup Series championship standings, season by season.
| Endpoint | Description |
|---|---|
| `GET /v1/nascar/standings/drivers` | Get NASCAR driver standings |
| `GET /v1/nascar/standings/manufacturers` | Get NASCAR manufacturer standings |
| `GET /v1/nascar/standings/owners` | Get NASCAR owner standings |
### NASCAR Live
Live timing for a NASCAR Cup Series session that is on track.
| Endpoint | Description |
|---|---|
| `GET /v1/nascar/live/sessions/{sessionId}/leaderboard` | Get the live leaderboard for a NASCAR session |
| `GET /v1/nascar/live/sessions/{sessionId}/status` | Get live race/stage status for a NASCAR session |
### Bulk Export
Full-season downloads (CSV / NDJSON) of results and lap-by-lap data, streamed as one file per season.
| Endpoint | Description |
|---|---|
| `GET /v1/nascar/export/laps` | Download a full NASCAR Cup Series season of lap-by-lap data |
| `GET /v1/nascar/export/results` | Download a full NASCAR Cup Series season of session results |
## Identifiers
Every resource is addressed by a stable UUID (for example `7c9a4314-8d6f-4f6a-9bfe-2f1d56a30b6a`). IDs never change between requests, so they are safe to store. List endpoints are the way to discover IDs; detail endpoints take them as path parameters.
## Pagination
All list endpoints use page-based pagination with `page` and `limit` query parameters.
| Parameter | Type | Default | Max | Description |
|-----------|------|---------|-----|-------------|
| `page` | integer | 1 | n/a | Page number (1-indexed) |
| `limit` | integer | 20 | 50 | Results per page |
Every paginated response wraps results in a standard envelope:
```json
{
"data": [ ... ],
"meta": {
"page": 1,
"limit": 20,
"total": 920,
"totalPages": 46
}
}
```
## Rate Limits
Requests are rate-limited. Every response carries the remaining allowance in `RateLimit-*` and `X-RateLimit-*` headers (including `-Day` and `-Month` variants), and exceeding a limit returns `429 Too Many Requests`.
## Error Handling
The API uses standard HTTP status codes. Error responses follow a consistent format:
```json
{
"statusCode": 404,
"message": "Driver not found",
"error": "Not Found"
}
```
| Status Code | Description |
|-------------|-------------|
| `400` | **Bad Request**. Invalid query parameters or malformed request. |
| `401` | **Unauthorized**. Missing or invalid API key. |
| `402` | **Payment Required**. Your plan does not cover this request: the endpoint needs a higher tier, or the call came from a browser page on a plan without browser (CORS) access. The body includes `requiredTier`, `currentTier`, and `upgradeUrl`. |
| `404` | **Not Found**. The requested resource does not exist. |
| `429` | **Too Many Requests**. Rate limit exceeded. Slow down or upgrade your plan. |
| `500` | **Internal Server Error**. Something went wrong on our end. |
## Need Help?
If you run into issues, have feature requests, or want to discuss integration strategies, contact us at [[email protected]](mailto:[email protected]) or visit [ocblacktop.com](https://ocblacktop.com).