Ctrlk
CricketMotorsportAPI 2 (Deprecated)WidgetsContact

📰 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 →

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:

Sprint race weekend:

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 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 and add ?include=details to retrieve sector times. See the Results & 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 [email protected].

Related pages

Last updated

Was this helpful?