# Data Model ## Understanding the Motorsport API data model > **🏎️ Motorsport API Required** > > This page and all endpoints described within require an active Motorsport API subscription (€79/mo, 3,000 API calls/hr). > > [View pricing →](https://www.sportmonks.com/formula-one-api/) The Motorsport API v3 uses a structured data model designed to represent a full motorsport season accurately. Before making your first request, it is worth taking a few minutes to understand how the core entities relate to each other - particularly because some terms have specific meanings in this API that differ from everyday usage. ### The entity hierarchy Every piece of motorsport data in the API sits within a clear hierarchy: ``` League └── Season └── Stage (a race weekend, e.g. Australian Grand Prix) └── Fixture (a single session, e.g. Practice 1, Qualifying, Race) ├── Laps ├── Pitstops └── Stints ``` Each level narrows the scope. A **League** contains multiple **Seasons**. Each Season contains multiple **Stages**. Each Stage contains multiple **Fixtures**. Session-level telemetry (laps, pitstops, stints) is always scoped to a specific Fixture. ### Core entity reference The table below defines every core entity and clarifies where its meaning may differ from common usage or from the old Formula One API v1. | Entity | What it represents | Real-world example | v1 equivalent | | ------------ | ------------------------------------------------ | -------------------------------------- | -------------------------- | | **League** | A motorsport championship | Formula 1 World Championship | Championship | | **Season** | A full competitive year within a league | 2025 F1 Season | Season | | **Stage** | A race weekend at a specific location | Australian Grand Prix | Track (Grand Prix context) | | **Fixture** | A single on-track session within a race weekend | Practice 1, Qualifying 2, Race | Stage | | **Venue** | A racing circuit | Albert Park Circuit | Track (circuit context) | | **Driver** | An individual racing driver | Max Verstappen | Driver | | **Team** | A constructor/team | Red Bull Racing | Team | | **Lap** | A single lap by a single driver in a session | Verstappen's lap 42 in the Race | - | | **Pitstop** | A single pit lane visit by a driver in a session | Hamilton's pitstop on lap 28 | - | | **Stint** | A continuous run on a single tyre compound | Leclerc's medium tyre stint, laps 1-18 | - | | **Standing** | Championship points position at a point in time | Norris P2 in Driver Standings | Standing | | **State** | The current status of a fixture | Not Started, Live, Finished | Status | > **Note on Fixture vs Stage terminology** > > This is the single most common source of confusion when working with the Motorsport API. In everyday conversation, "stage" often refers to a part of a race weekend. In this API, a **Stage is the full race weekend** and a **Fixture is a single session within it**. If you are migrating from the Formula One API v1, note that what v1 called a "Stage" is now a "Fixture" in v3. ### Fixtures: Understanding session types A race weekend (Stage) in Formula 1 typically contains between five and six Fixtures, depending on whether it is a standard weekend or a Sprint weekend. **Standard race weekend:** ``` Stage: Australian Grand Prix ├── Fixture: Practice 1 ├── Fixture: Practice 2 ├── Fixture: Practice 3 ├── Fixture: Qualifying 1 ├── Fixture: Qualifying 2 └── Fixture: Qualifying 3 / Race ``` **Sprint race weekend:** ``` Stage: Chinese Grand Prix ├── Fixture: Practice 1 ├── Fixture: Sprint Qualifying 1 ├── Fixture: Sprint Qualifying 2 ├── Fixture: Sprint Qualifying 3 ├── Fixture: Sprint Race ├── Fixture: Qualifying 1 ├── Fixture: Qualifying 2 ├── Fixture: Qualifying 3 └── Fixture: Race ``` Each Fixture has a `name` field (e.g. `"Practice 1"`) and a `leg` field that represents its position in the sequence (e.g. `"2/3"` for Practice 2 of 3). On Sprint weekends, Practice 1 returns `"1/1"` because it is the only practice session. To determine the type of session programmatically, use the `metadata` include on a fixture and check for the `IS_QUALIFICATION`, `SPRINT_RACE`, and `HAS_STANDING` metadata types. See the [Metadata & Per-Season Data Type Reference](https://docs.sportmonks.com/v3/motorsport-api/welcome/metadata-and-per-season-data-type-reference) for full type IDs. ### Venues: Circuits vs Race weekends A **Venue** is a physical racing circuit - the track itself. It is separate from the Stage (race weekend) that takes place there. This distinction matters because: * The same venue can host multiple stages across different seasons. * Venue metadata (track length, DRS zones, direction) describes the physical circuit, not a specific event. * To get the circuit for a given race weekend, include the venue on the Stage or its Fixtures: `?include=venue`. Venue metadata available via `?include=metadata`: | Field | Description | | --------------- | ----------------------------------------------- | | Track Length | Length in kilometres (3 decimal precision) | | Track Direction | Clockwise, anti-clockwise, or 50/50 | | Track Type | Race circuit or street circuit | | Grand Prix Name | The Grand Prix name associated with the circuit | | DRS Zones | Number of DRS activation zones | | Track Turns | Total number of corners | ### Results and Live Data Session results and live timing data are accessible via includes on Fixtures. There are two levels: **`results` include** - a compact subset, suitable for standings and post-race summaries: * Position * Time * Interval (gap to driver ahead) * Gap to Leader * Tyre type and age **`lineups.details` nested include** - the full result set, including: * Everything in `results`, plus: * Points scored * Grid position (races only, from 2022) * Number of laps completed * Number of pitstops * Driver status (DNS, DNF, DSQ) * Fastest lap time and number * In Pit indicator (live, from 2025) For detailed lap timing, use the dedicated [Laps endpoints](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/laps) and add `?include=details` to retrieve sector times. See the [Results & Live Data Type Reference](https://docs.sportmonks.com/v3/motorsport-api/welcome/results-and-live-data-type-reference) for all type IDs. ### Laps, Pitstops, and Stints These three entities all describe what happens during a session at the driver level. They are always scoped to a specific Fixture and driver. | Entity | Describes | Key fields | Detail include | | ----------- | ------------------------ | ------------------------------------------------------------ | ------------------------------------------------- | | **Lap** | A single lap by a driver | `lap_number`, `driver_number`, `participant_id`, `is_latest` | `details` - sector times, lap duration, timestamp | | **Pitstop** | A single pit lane visit | `fixture_id`, `participant_id`, `lap_number` | `details` - pit timestamp, pit duration | | **Stint** | A continuous tyre run | `fixture_id`, `participant_id`, `stint_number` | `details` - start/end lap numbers, stint number | All three support a `latest` variant endpoint that returns only the most recent record per driver - useful for live timing displays. ### The core API Some fields returned by the Motorsport API reference entities that live in the **Core API** rather than the Motorsport API itself. These are sport-independent and shared across all Sportmonks v3 APIs: | Field | Entity | How to resolve | | ------------------------ | --------------- | ------------------------------------------------ | | `country_id` | Country | `?include=country` or Core API `/core/countries` | | `city_id` | City | `?include=city` or Core API `/core/cities` | | `type_id`, `position_id` | Type / Position | `?include=type` or Core API `/core/types` | You do not need a separate subscription for Core API access - it is included with any v3 plan. ### What the API currently covers The Motorsport API v3 currently provides **Formula 1** data only. The API is structured to support additional motorsport championships in future (Formula 2, Formula 3, NASCAR, and others), which is why it is named "Motorsport" rather than "Formula One". When additional series are added, they will follow the same League > Season > Stage > Fixture hierarchy. > **Beta status** > > The Motorsport API v3 is currently in beta. No major or breaking changes are planned. If you have questions or encounter missing data, contact . ### Related pages * [Getting Started](https://docs.sportmonks.com/v3/motorsport-api/welcome/getting-started) * [Fixtures Endpoints](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/fixtures) * [Stages Endpoints](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/stages) * [Results & Live Data Type Reference](https://docs.sportmonks.com/v3/motorsport-api/welcome/results-and-live-data-type-reference) * [Metadata & Per-Season Data Type Reference](https://docs.sportmonks.com/v3/motorsport-api/welcome/metadata-and-per-season-data-type-reference) * [Migrating from Formula One API v1](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/guides/migrating-from-formula-one-api-v1-to-motorsport-api-v3) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.sportmonks.com/v3/motorsport-api/welcome/data-model.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.