# Formula 1 API
> Formula 1 reference data as an API, built on the Ergast / Jolpica F1 dataset — every driver, constructor and circuit in F1 history plus every season since 1950. Look up a driver by id or name (e.g. hamilton → Lewis Hamilton, code HAM, #44, British), a constructor/team (ferrari → Ferrari), or a circuit with its coordinates and country (monza → Autodromo Nazionale di Monza, Italy); or search across all three (e.g. "verstappen" → Jos & Max Verstappen). 879 drivers, 214 constructors, 78 circuits. Ideal for motorsport apps, fantasy F1, sports trivia and data dashboards.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/f1-api/..."
```

## Pricing
- **Free** (Free) — 4,000 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 50,000 calls/Mo, 8 req/s
- **Pro** ($14/Mo) — 250,000 calls/Mo, 20 req/s
- **Mega** ($35/Mo) — 1,000,000 calls/Mo, 50 req/s

## Endpoints

### Formula 1

#### `GET /v1/circuit` — A circuit by id or name (with coordinates)

**Parameters:**
- `id` (query, optional, string) — Circuit id, e.g. monza Example: `monza`
- `name` (query, optional, string) — Circuit name (fuzzy)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/f1-api/v1/circuit?id=monza"
```

**Response:**
```json
{
    "data": {
        "id": "monza",
        "name": "Autodromo Nazionale di Monza",
        "country": "Italy",
        "latitude": 45.6156,
        "locality": "Monza",
        "wiki_url": "https://en.wikipedia.org/wiki/Monza_Circuit",
        "longitude": 9.28111
    },
    "meta": {
        "timestamp": "2026-05-31T05:48:03.616Z",
        "request_id": "22f9557e-3d6b-417b-9263-eeb1c0ef6a3b"
    },
    "status": "ok",
    "message": "Circuit retrieved",
    "success": true
}
```

#### `GET /v1/constructor` — A constructor (team) by id or name

**Parameters:**
- `id` (query, optional, string) — Constructor id, e.g. ferrari Example: `ferrari`
- `name` (query, optional, string) — Constructor name (fuzzy)

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/f1-api/v1/constructor?id=ferrari"
```

**Response:**
```json
{
    "data": {
        "id": "ferrari",
        "name": "Ferrari",
        "wiki_url": "https://en.wikipedia.org/wiki/Scuderia_Ferrari",
        "nationality": "Italian"
    },
    "meta": {
        "timestamp": "2026-05-31T05:48:03.686Z",
        "request_id": "a4b25703-f1cd-4031-9291-36b4317c445f"
    },
    "status": "ok",
    "message": "Constructor retrieved",
    "success": true
}
```

#### `GET /v1/driver` — A driver by id or name

**Parameters:**
- `id` (query, optional, string) — Driver id, e.g. hamilton Example: `hamilton`
- `name` (query, optional, string) — Driver name (fuzzy), e.g. Senna

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/f1-api/v1/driver?id=hamilton"
```

**Response:**
```json
{
    "data": {
        "id": "hamilton",
        "code": "HAM",
        "name": "Lewis Hamilton",
        "number": "44",
        "wiki_url": "http://en.wikipedia.org/wiki/Lewis_Hamilton",
        "given_name": "Lewis",
        "family_name": "Hamilton",
        "nationality": "British",
        "date_of_birth": "1985-01-07"
    },
    "meta": {
        "timestamp": "2026-05-31T05:48:03.757Z",
        "request_id": "fdd328a7-6d51-420b-bee6-cbe8644d9362"
    },
    "status": "ok",
    "message": "Driver retrieved",
    "success": true
}
```

#### `GET /v1/search` — Search across drivers, constructors and circuits

**Parameters:**
- `q` (query, required, string) — Search term, e.g. senna Example: `senna`
- `type` (query, optional, string) — driver | constructor | circuit
- `limit` (query, optional, string) — Results per page (1-100, default 20) Example: `20`
- `offset` (query, optional, string) — Pagination offset Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/f1-api/v1/search?q=senna&limit=20&offset=0"
```

**Response:**
```json
{
    "data": {
        "type": null,
        "count": 2,
        "limit": 20,
        "query": "senna",
        "total": 2,
        "offset": 0,
        "results": [
            {
                "id": "senna",
                "code": null,
                "name": "Ayrton Senna",
                "type": "driver",
                "number": null,
                "wiki_url": "http://en.wikipedia.org/wiki/Ayrton_Senna",
                "given_name": "Ayrton",
                "family_name": "Senna",
                "nationality": "Brazilian",
                "date_of_birth": "1960-03-21"
            },
            {
                "id": "bruno_senna",
                "code": "SEN",
                "name": "Bruno Senna",
                "type": "driver",
                "number": null,
                "wiki_url": "http://en.wikipedia.org/wiki/Bruno_Senna",
                "given_name": "Bruno",
                "family_name": "Senna",
                "nationality": "Brazilian",
                "date_of_birth": "1983-10-15"
            }
        ]
    },
    "meta": {
        "timestamp": "2026-05-31T05:48:03.808Z",
        "request_id": "caee7513-f523-4e6b-b2d0-f8051fd8cd6f"
    },
    "status": "ok",
    "message": "Results listed",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Totals & season range

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/f1-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "Reference data (drivers, teams, circuits, seasons). Historical, sourced from the Ergast database.",
        "source": "Ergast / Jolpica F1 API",
        "drivers": 879,
        "seasons": {
            "last": 2026,
            "count": 77,
            "first": 1950
        },
        "circuits": 78,
        "endpoints": [
            "/v1/driver",
            "/v1/constructor",
            "/v1/circuit",
            "/v1/search",
            "/v1/meta"
        ],
        "constructors": 214
    },
    "meta": {
        "timestamp": "2026-05-31T05:48:03.855Z",
        "request_id": "0ecc79e4-6404-451d-942a-789d5b8290bf"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/f1-api
OpenAPI spec: https://www.oanor.com/api/f1-api/openapi.json