A RESTful Formula 1 data API covering every championship season since 1950: drivers, teams, circuits, race weekends, session results, lap-by-lap timing, championship standings, live race-weekend timing, and post-session telemetry. Every response follows a consistent schema, every list endpoint is paginated, and every resource is addressed by a stable UUID.
**Coverage:** 1950–2026, 77 seasons.
Data is aggregated and normalized by [Blacktop](https://ocblacktop.com), which serves the same shape across every series it covers. This listing is Formula 1 only, across 30 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
30 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.
### F1 Drivers
Every Formula 1 driver on record, with profile and career history.
| Endpoint | Description |
|---|---|
| `GET /v1/formula1/drivers` | List all Formula 1 drivers |
| `GET /v1/formula1/drivers/{id}` | Get driver details by ID |
### F1 Teams
Formula 1 teams, with profiles and the seasons they entered.
| Endpoint | Description |
|---|---|
| `GET /v1/formula1/teams` | List all Formula 1 teams |
| `GET /v1/formula1/teams/{id}` | Get team details by ID |
### F1 Events
The Formula 1 calendar: race weekends, the sessions inside them, and each session's results and timing.
| Endpoint | Description |
|---|---|
| `GET /v1/formula1/events` | List all Formula 1 events |
| `GET /v1/formula1/events/{id}` | Get event details by ID |
| `GET /v1/formula1/events/{eventId}/sessions` | List all sessions for an event |
| `GET /v1/formula1/events/{eventId}/sessions/{sessionId}` | Get session details by ID |
| `GET /v1/formula1/events/{eventId}/sessions/{sessionId}/lap-chart` | Get the lap chart for a session |
| `GET /v1/formula1/events/{eventId}/sessions/{sessionId}/lap-times` | Get individual lap times for a session |
| `GET /v1/formula1/events/{eventId}/sessions/{sessionId}/results` | Get session results |
### F1 Seasons
Formula 1 seasons: the list of seasons, and per-season detail including the calendar and per-driver and per-team statistics.
| Endpoint | Description |
|---|---|
| `GET /v1/formula1/seasons` | List all Formula 1 seasons |
| `GET /v1/formula1/seasons/{id}` | Get season details by ID |
| `GET /v1/formula1/seasons/{id}/drivers` | Get season driver statistics |
| `GET /v1/formula1/seasons/{id}/teams` | Get season constructor/team statistics |
### F1 Circuits
Circuits and venues on the Formula 1 calendar, past and present, with track specifications, lap records and event history.
| Endpoint | Description |
|---|---|
| `GET /v1/formula1/locations` | List all Formula 1 circuit locations |
| `GET /v1/formula1/locations/{id}` | Get circuit/location details by ID |
### F1 Standings
Formula 1 championship standings, season by season.
| Endpoint | Description |
|---|---|
| `GET /v1/formula1/standings/constructors` | Get Formula 1 constructor standings |
| `GET /v1/formula1/standings/drivers` | Get Formula 1 driver standings |
### F1 Timing
Live timing for a Formula 1 session that is on track: the running order, plus per-lap and per-driver snapshots.
| Endpoint | Description |
|---|---|
| `GET /v1/formula1/live/sessions/{sessionId}/timing` | Get latest timing data for a session |
| `GET /v1/formula1/live/sessions/{sessionId}/timing/drivers/{driverNumber}` | Get timing history for a specific driver |
| `GET /v1/formula1/live/sessions/{sessionId}/timing/laps/{lap}` | Get timing data for a specific lap |
### F1 Race Control
Race control messages for a Formula 1 session: penalties, investigations, safety car periods and flag notes.
| Endpoint | Description |
|---|---|
| `GET /v1/formula1/live/sessions/{sessionId}/race-control` | Get race control messages for a session |
### F1 Weather
Track and air conditions through a Formula 1 session, latest reading and full history.
| Endpoint | Description |
|---|---|
| `GET /v1/formula1/live/sessions/{sessionId}/weather` | Get latest weather for a session |
| `GET /v1/formula1/live/sessions/{sessionId}/weather/history` | Get weather history for a session |
### F1 State
Where a Formula 1 session currently stands: flag state, lap, and session status.
| Endpoint | Description |
|---|---|
| `GET /v1/formula1/live/sessions/{sessionId}/state` | Get latest session state checkpoint |
### F1 Telemetry
Post-session sub-lap telemetry: one driver's every lap cut into equal slices of track, each slice carrying mean and minimum speed, throttle, brake, DRS and the distance to the car ahead. Slices are fixed pieces of tarmac rather than fixed intervals of time, so the same index compares directly across laps and drivers. Written once a session ends, and never changed afterwards.
| Endpoint | Description |
|---|---|
| `GET /v1/formula1/events/{eventId}/sessions/{sessionId}/telemetry/positions` | Where every car was on track, through a session |
| `GET /v1/formula1/events/{eventId}/sessions/{sessionId}/telemetry/drivers/{code}` | Sub-lap telemetry for one driver in a 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/formula1/export/laps` | Download a full Formula 1 season of lap-by-lap data |
| `GET /v1/formula1/export/results` | Download a full Formula 1 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).