Understanding Race Results, Driver, Team and Track Data in v3

One of the most significant changes in Motorsport API v3 is how race results and driver data are structured. In v2, result fields were individual properties on each driver/result object. In v3, this data has moved into structured arrays that provide better organization and more detailed information.

This guide specifically addresses the question: "Where did my v2 data fields go in v3?"

Key change: Race result data now lives in the lineups array, where each lineup entry represents a driver's participation in a fixture (race/qualifying/practice).

This guide shows examples as Javascript/Node.JS code, however you can use similar approaches in your programming language of choice.

---

High-level structural changes

From single properties to arrays

In v2, many data points were direct properties on objects. In v3, most data is organised into typed arrays for better structure and extensibility.

v2 Approach (flat structure):

{
  "driver_id": 123,
  "team_id": 456,
  "position": 1,
  "driver_time": "1:32:03.456",
  "best_lap_time": "1:23.456",
  "laps": 58,
  "grid": 3
}

v3 Approach (structured arrays):

{
  "lineups": [
    {
      "player_id": 123,
      "team_id": 456,
      "grid_position": 3,
      "details": [
        {
          "type_id": 187,
          "type": { "name": "Position", "code": "position" },
          "data": { "position": 1 }
        },
        {
          "type_id": 195,
          "type": { "name": "Time", "code": "time" },
          "data": { "time": "1:32:03.456" }
        },
        {
          "type_id": 197,
          "type": { "name": "Fastest Lap", "code": "fastest-lap" },
          "data": { 
            "time": "1:23.456",
            "lap_number": 42
          }
        }
      ]
    }
  ]
}

Why this change?

Benefits of the new structure:

• Extensibility: Easy to add new data types without changing the schema

• Type safety: Each data point has an explicit type

• Consistency: Same pattern across all motorsport series

• Clarity: Clear separation between driver info and result details

---

Understanding lineups

The lineups array is the core container for all driver participation and result data in a fixture.

What is a lineup entry?

Each item in the lineups array represents one driver's participation in a specific fixture (race, qualifying, or practice session).

Lineup Structure

{
  "id": 789012,
  "fixture_id": 19444687,
  "player_id": 123,              // Driver ID
  "team_id": 456,                // Team ID
  "grid_position": 3,            // Starting position
  "details": [                   // All result data (when included)
    { /* Position */ },
    { /* Time */ },
    { /* Fastest Lap */ },
    { /* Laps Completed */ }
  ],
  "driver": {                    // Driver info (when included)
    "id": 123,
    "name": "Max Verstappen",
  }
}

Accessing lineups

Basic request:

GET /v3/motorsport/fixtures/19444687
  ?api_token=YOUR_TOKEN
  &include=lineups

With driver details:

GET /v3/motorsport/fixtures/19444687
  ?api_token=YOUR_TOKEN
  &include=lineups.driver;lineups.details.type

---

Complete field mapping: v2 → v3

Here's the definitive guide for finding your v2 fields in v3.

Core identifiers

v2 Field	v3 Location	Notes
driver_id	lineups[].player_id	Direct mapping; different IDs (see Drivers)
team_id	lineups[].team_id	Direct mapping; different IDs (see Teams)
track_id	venue_id	Now at fixture level, not driver level; different IDs (see Tracks / Venues)

Example:

v2:

{
  "driver_id": 123,
  "team_id": 456,
  "track_id": 789
}

v3:

{
  "venue_id": 789,  // At fixture level
  "lineups": [
    {
      "player_id": 123,  // Was driver_id
      "team_id": 456
    }
  ]
}

You can enrich data with normal and nested includes, like include=venue and include=lineups.driver. However, we recommend caching and/or storing data, and relating them using IDs.

Result times

v2 Field	v3 Location	Type Name	Type Code
driver_time	lineups[].details[].data.time	"Time"	time
driver_time_int	lineups[].details[].data.interval	"Interval"	interval

Finding time in v3:

// Find the Time detail
const timeDetail = lineup.details.find(d => d.type.code === 'time');
const finishTime = timeDetail?.data.time;  // "1:32.456"

Complete example:

v2:

{
  "driver_id": 123,
  "position": 1,
  "driver_time": "1:32.456",
  "driver_time_int": "1:32:03.456"
},
{
  "driver_id": 456,
  "position": 2,
  "driver_time": "1:33.356",
  "driver_time_int": "+0.900"
}

v3:

{
  "lineups": [
    {
      "player_id": 123,
      "details": [
        {
          "type_id": 187,
          "type": { "name": "Position", "code": "position" },
          "data": { "position": 1 }
        },
        {
          "type_id": 195,
          "type": { "name": "Time", "code": "time" },
          "data": { "time": "1:32.456" }
        },
        {
          "type_id": 196,
          "type": { "name": "Interval", "code": "interval" },
          "data": { "interval": "1:32:03.456" }
        }
      ]
    }
    {
      "player_id": 456,
      "details": [
        {
          "type_id": 187,
          "type": { "name": "Position", "code": "position" },
          "data": { "position": 2 }
        },
        {
          "type_id": 195,
          "type": { "name": "Time", "code": "time" },
          "data": { "time": "1:33.356" }
        },
        {
          "type_id": 196,
          "type": { "name": "Interval", "code": "interval" },
          "data": { "interval": "1:32:03.456" }
        }
      ]
    }
  ]
}

Important to note: For the "type" fields to be available, the nested include 'lineups.details.type' must be used.

Fastest lap data

v2 Field	v3 Location	Type Name	Type Code
best_lap_time	lineups[].details[].data.time	"Fastest Lap"	fastest-lap
fasted_lap_time	lineups[].details[].data.time	"Fastest Lap"	fastest-lap
fasted_lap	lineups[].details[].data.lap_number	"Fastest Lap"	fastest-lap

Important: Both fasted_lap_time and fasted_lap (lap number) are now in the same detail object with type "Fastest Lap" and keys time and lap_number. best_lap_time was a duplicate field and can also be found in this object via the key time.

Finding fastest lap in v3:

// Find the Fastest Lap detail
const fastestLapDetail = lineup.details.find(d => d.type.code === 'fastest-lap');

const fastestLapTime = fastestLapDetail?.data.time;        // "1:23.456"
const fastestLapNumber = fastestLapDetail?.data.lap_number; // 42

Complete example:

v2:

{
  "driver_id": 123,
  "best_lap_time": "1:23.456",
  "fasted_lap_time": "1:23.456",
  "fasted_lap": 42
}

v3:

{
  "lineups": [
    {
      "player_id": 123,
      "details": [
        {
          "type_id": 197,
          "type": { "name": "Fastest Lap", "code": "fastest-lap" },
          "data": {
            "time": "1:23.456",
            "lap_number": 42
          }
        }
      ]
    }
  ]
}

Laps completed

v2 Field	v3 Location	Type Name	Type Code
laps	lineups[].details[].data.laps	"Laps"	laps

Finding laps in v3:

// Find the Laps detail
const lapsDetail = lineup.details.find(d => d.type.code === 'laps');
const lapsCompleted = lapsDetail?.data.laps;  // 58

Complete example:

v2:

{
  "driver_id": 123,
  "laps": 58
}

v3:

{
  "lineups": [
    {
      "player_id": 123,
      "details": [
        {
          "type_id": 192,
          "type": { "name": "Laps", "code": "laps" },
          "data": { "laps": 58 }
        }
      ]
    }
  ]
}

Grid position

v2 Field	v3 Location	Notes
grid	lineups[].grid_position	Available as direct property, and in details array

Good To Know: Grid position is a direct property on the lineup object, which you can use instead of the object in the details array.

Complete example:

v2:

{
  "driver_id": 123,
  "grid": 3
}

v3:

{
  "lineups": [
    {
      "player_id": 123,
      "grid_position": 3  // Direct property
    }
  ]
}

v3, alternative way:

v2 Field	v3 Location	Type Name	Type Code
grid	lineups[].details[].data.position	"Grid Position"	grid-position

Pitstops

v2 Field	v3 Location	Type Name	Type Code
pit	lineups[].details[].data.stops	"Pitstops"	pitstops

Finding pitstops in v3:

// Find the Pitstops detail
const pitstopsDetail = lineup.details.find(d => d.type.code === 'pitstops');
const numberOfStops = pitstopsDetail?.data.stops;  // 2

Complete example:

v2:

{
  "driver_id": 123,
  "pit": 2
}

v3:

{
  "lineups": [
    {
      "player_id": 123,
      "details": [
        {
          "type_id": 193,
          "type": { "name": "Pitstops", "code": "pitstops" },
          "data": { "stops": 2 }
        }
      ]
    }
  ]
}

Additional detail types

Based on actual v3 data, here are the additional detail types available in lineups:

v3 Detail Type	Type Code	Data Fields	Description
Points	points	points	Championship points earned
Gap To Leader	gap-to-leader	gap	Time gap to race leader
Tyre	tyre	compound, age_since_start	Current tyre compound and age

Example - Getting tyre information:

const tyreDetail = lineup.details.find(d => d.type.code === 'tyre');
const tyreCompound = tyreDetail?.data.compound;      // "HARD", "MEDIUM", "SOFT"
const tyreAge = tyreDetail?.data.age_since_start;    // 0, 5, 10, etc.

Example - Getting gap to leader:

const gapDetail = lineup.details.find(d => d.type.code === 'gap-to-leader');
const gap = gapDetail?.data.gap;  // "25.624"

Retirement status

v2 Field	v3 Location	Type Name	Type Code
retired	lineups[].details[].data.status	"Status"	status

Status values:

• "DNF" - Did Not Finish

• "DNS" - Did Not Start

• "DSQ" - Disqualified

Finding status in v3:

// Find the Status detail
const statusDetail = lineup.details.find(d => d.type.code === 'status');
const driverStatus = statusDetail?.data.status;  // "DNF", etc.

// Check if driver retired
const didNotFinish = ['DNF', 'DNS', 'DSQ'].includes(driverStatus);

Complete Example:

v2:

{
  "driver_id": 123,
  "retired": true
}

v3:

{
  "lineups": [
    {
      "player_id": 123,
      "details": [
        {
          "type_id": 9713,
          "type": { "name": "Status", "code": "status" },
          "data": { "status": "DNF" }
        }
      ]
    }
  ]
}

The fixture-level state indicates overall race status (NS, LIVE, FULL_TIME, CANCELLED, etc.), not individual driver status.

---

Complete side-by-side comparison

v2 race result response

{
  "id": 12345,
  "stage_name": "Monaco Grand Prix - Race",
  "track_id": 789,
  "results": [
    {
      "driver_id": 37920804,
      "team_id": 276189,
      "position": 4,
      "grid": 4,
      "driver_time": "1:21.294",
      "driver_time_int": "4.273",
      "best_lap_time": "1:21.294",
      "fastest_lap": 53,
      "laps": 53,
      "pit": 1,
      "points": 12
    }
  ]
}

v3 race result response

{
  "id": 19444687,
  "name": "Monaco Grand Prix - Race",
  "venue_id": 343590,
  "state_id": 5,
  "lineups": [
    {
      "id": 14670723395,
      "fixture_id": 19444687,
      "player_id": 37920804,
      "team_id": 276189,
      "grid_position": 4,
      "driver_name": "Charles Leclerc",
      "driver_number": 16,
      "details": [
        {
          "type_id": 9711,
          "type": { "name": "Position", "code": "position" },
          "data": { "position": 4 }
        },
        {
          "type_id": 9708,
          "type": { "name": "Time", "code": "time" },
          "data": { "time": "1:21.294" }
        },
        {
          "type_id": 9733,
          "type": { "name": "Interval", "code": "interval" },
          "data": { "interval": "4.273" }
        },
        {
          "type_id": 9732,
          "type": { "name": "Gap To Leader", "code": "gap-to-leader" },
          "data": { "gap": "25.624" }
        },
        {
          "type_id": 9716,
          "type": { "name": "Fastest Lap", "code": "fastest-lap" },
          "data": {
            "time": "1:21.294",
            "lap_number": 53
          }
        },
        {
          "type_id": 9710,
          "type": { "name": "Laps", "code": "laps" },
          "data": { "laps": 53 }
        },
        {
          "type_id": 9709,
          "type": { "name": "Pitstops", "code": "pitstops" },
          "data": { "stops": 1 }
        },
        {
          "type_id": 9707,
          "type": { "name": "Points", "code": "points" },
          "data": { "points": 12 }
        },
        {
          "type_id": 9712,
          "type": { "name": "Grid Position", "code": "grid-position" },
          "data": { "position": 4 }
        },
        {
          "type_id": 9729,
          "type": { "name": "Tyre", "code": "tyre" },
          "data": {
            "compound": "HARD",
            "age_since_start": 0
          }
        }
      ]
    }
  ]
}

---

Practical code examples

Extracting race results

Goal: Get finishing position, time, and fastest lap for each driver.

async function getRaceResults(fixtureId, apiToken) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/fixtures/${fixtureId}` +
    `?api_token=${apiToken}` +
    `&include=lineups.driver;lineups.details.type`
  );
  
  const data = await response.json();
  const results = [];
  
  data.data.lineups.forEach(lineup => {
    // Helper function to find detail by type code
    const findDetail = (code) => 
      lineup.details.find(d => d.type.code === code);
    
    // Extract all result data
    const positionDetail = findDetail('position');
    const timeDetail = findDetail('time');
    const fastestLapDetail = findDetail('fastest-lap');
    const lapsDetail = findDetail('laps');
    const statusDetail = findDetail('status');
    
    results.push({
      driver_id: lineup.player_id,
      driver_name: lineup.driver?.name,
      team_id: lineup.team_id,
      position: positionDetail?.data.position,
      finish_time: timeDetail?.data.time,
      fastest_lap_time: fastestLapDetail?.data.time,
      fastest_lap_number: fastestLapDetail?.data.lap_number,
      laps_completed: lapsDetail?.data.laps,
      grid_position: lineup.grid_position,
      status: statusDetail?.data.status || 'FIN'
    });
  });
  
  // Sort by position
  return results.sort((a, b) => a.position - b.position);
}

// Usage
const raceResults = await getRaceResults(19444687, 'YOUR_TOKEN');
console.log(raceResults);

Output:

[
  {
    driver_id: 123,
    driver_name: "Max Verstappen",
    team_id: 456,
    position: 1,
    finish_time: "1:32:03.456",
    fastest_lap_time: "1:23.456",
    fastest_lap_number: 42,
    laps_completed: 58,
    grid_position: 3,
    status: "FIN"
  },
  // ... more results
]

Building a results table

function displayResultsTable(results) {
  console.log('Pos | Driver            | Team | Time        | Fastest Lap | Grid | Status');
  console.log('----+-------------------+------+-------------+-------------+------+--------');
  
  results.forEach(result => {
    const pos = result.position.toString().padStart(3);
    const driver = (result.driver_name || 'Unknown').padEnd(17);
    const team = result.team_id.toString().padStart(4);
    const time = (result.finish_time || 'DNF').padEnd(11);
    const fastLap = (result.fastest_lap_time || 'N/A').padEnd(11);
    const grid = result.grid_position.toString().padStart(4);
    const status = result.status.padEnd(6);
    
    console.log(`${pos} | ${driver} | ${team} | ${time} | ${fastLap} | ${grid} | ${status}`);
  });
}

// Usage
displayResultsTable(raceResults);

Output:

Pos | Driver            | Team | Time        | Fastest Lap | Grid | Status
----+-------------------+------+-------------+-------------+------+--------
  1 | Max Verstappen    |  456 | 1:32:03.456 | 1:23.456    |    3 | FIN   
  2 | Lewis Hamilton    |  457 | +5.234      | 1:23.789    |    1 | FIN   
  3 | Charles Leclerc   |  458 | +12.456     | 1:24.123    |    5 | FIN   

Identifying drivers who didn't finish

Since there's no direct "retired" or "DNF" status field, determine this by comparing lap counts:

function getDriversWhoDidNotFinish(lineups) {
  // Find the maximum laps completed (race winner's laps)
  const maxLaps = Math.max(...lineups.map(lineup => {
    const lapsDetail = lineup.details.find(d => d.type.code === 'laps');
    return lapsDetail?.data.laps || 0;
  }));
  
  // Find drivers who completed fewer laps than the winner
  return lineups
    .filter(lineup => {
      const lapsDetail = lineup.details.find(d => d.type.code === 'laps');
      const lapsCompleted = lapsDetail?.data.laps || 0;
      return lapsCompleted < maxLaps;
    })
    .map(lineup => ({
      driver_id: lineup.player_id,
      driver_name: lineup.driver?.name,
      laps_completed: lineup.details.find(d => d.type.code === 'laps')?.data.laps || 0,
      position: lineup.details.find(d => d.type.code === 'position')?.data.position
    }));
}

// Usage
const dnfs = getDriversWhoDidNotFinish(data.lineups);
console.log(`${dnfs.length} drivers did not finish the race`);

Finding fastest lap of the race

function getFastestLapOfRace(lineups) {
  let fastest = null;
  
  lineups.forEach(lineup => {
    const fastestLapDetail = lineup.details.find(d => d.type.code === 'fastest-lap');
    
    if (fastestLapDetail && fastestLapDetail.data.time) {
      if (!fastest || fastestLapDetail.data.time < fastest.time) {
        fastest = {
          driver_id: lineup.player_id,
          driver_name: lineup.driver?.name,
          time: fastestLapDetail.data.time,
          lap_number: fastestLapDetail.data.lap_number
        };
      }
    }
  });
  
  return fastest;
}

// Usage
const fastestLap = getFastestLapOfRace(data.lineups);
console.log(`Fastest lap: ${fastestLap.driver_name} - ${fastestLap.time} (Lap ${fastestLap.lap_number})`);

---

States & Types: Cacheable reference data

One major improvement in v3 is that states and types are now standardised across all motorsport series.

Why this matters

In v2, status codes and data types could vary. In v3, they are consistent and safe to cache long-term.

Caching strategy

Best Practice: Cache types and states for 30+ days. They rarely change and are consistent across all fixtures.

GET /v3/core/types
  ?api_token=YOUR_TOKEN

Common Lineup Detail Types:

Type ID	Name	Code	Usage
9711	Position	position	Live or final race position
9708	Time	time	Latest lap time
9733	Interval	interval	Time behind car ahead
9732	Gap To Leader	gap-to-leader	Time behind race leader
9716	Fastest Lap	fastest-lap	Fastest lap time & lap number
9710	Laps	laps	Laps completed
9709	Pitstops	pitstops	Number of pit stops
9707	Points	points	Championship points earned in this race
9712	Grid Position	grid-position	Starting grid position
9729	Tyre	tyre	Current tyre compound & age

A full detailed list can be found here: Results & Live Data Type Reference

Getting all states

GET /v3/core/states
  ?api_token=YOUR_TOKEN

Common fixture states:

State ID	State Code	Name	Additional notes
1	NS	Not Started
27	LIVE	Live	Transition to this state indicates the start of the first lap in races (excluding the formation lap) and green light in other session types
5	FT	Full Time	Known in v1 as 'Finished', indicates a chequered flag is waved in races, and full session time elapsed in other session types
12	CANCELLED	Cancelled
16	DELAYED	Delayed
18	INTERRUPTED	Interrupted	Session is paused, usually when a red flag is waved
20	DELETED	Deleted	The fixture is removed from the API, it is no longer active in standard calls but can still be fetched with filter=deleted.

Using cached types

// Cache types once
const typesCache = new Map();

async function loadTypes(apiToken, page = 1) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/core/types?api_token=${apiToken}&filter=populate&page=${page}`
  );
  const data = await response.json();
  
  data.data.forEach(type => {
    typesCache.set(type.code, type);
  });
  
  // Recursively fetch the next page, if available
  if(data.pagination.has_more) {
    await loadTypes(apiToken, page + 1);
  }
}

// Use cached types to identify details
function getDetailValue(lineup, typeCode) {
  const type = typesCache.get(typeCode);
  const detail = lineup.details.find(d => d.type_id === type.id);
  return detail?.data;
}

// Load once at application start
await loadTypes('YOUR_TOKEN');

// Use throughout application without additional API calls
const position = getDetailValue(lineup, 'position')?.position;
const fastestLap = getDetailValue(lineup, 'fastest-lap')?.time;

---

Driver information

In v2, debut information was sometimes included in driver responses. In v3, all driver-specific metadata (including debut info) is now in a dedicated metadata object.

Accessing debut data

Endpoint:

GET /v3/motorsport/drivers
  ?api_token=YOUR_TOKEN
  &include=metadata

You can also use the lineups.driver.metadata nested include on the livescores or fixture endpoints to include this data for all drivers in a live or past fixture

Response structure:

{
  "data": [
    {
      "id": 123,
      "name": "Charles Leclerc",
      "metadata": [
        {
          "id": 9082090,
          "metadatable_id": 37920804,
          "type_id": 109851,
          "value_type": "object",
          "values": {
            "season": "2018"
          }
        },
        {
          "id": 9082118,
          "metadatable_id": 37920804,
          "type_id": 109852,
          "value_type": "object",
          "values": {
            "track": "Albert Park"
          }
        },
        {
          "id": 9082145,
          "metadatable_id": 37920804,
          "type_id": 109853,
          "value_type": "object",
          "values": {
            "result": "P13"
          }
        }
      ]
    }
  ]
}

A full list of available types can be found here: Driver

Code Example: Retrieving driver information

const typesCache = new Map();

async function getDriverDetails(apiToken) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/drivers` +
      `?api_token=${apiToken}` +
      `&include=metadata` +
      `&per_page=50`
  );

  const json = await response.json();
  const drivers = Array.isArray(json.data) ? json.data : [];

  return drivers
    .map((driver) => {
      const metadata = (driver.metadata ?? []);

      const driverData = {};

      for (const meta of metadata) {
        const type = typesCache.get(meta.type_id);
        if (!type || meta.values == null) continue;

        const key = type.developer_name?.toLowerCase();
        if (!key) continue;

        let value;

        const entries = Object.entries(meta.values);

        // Single-property object - unwrap
        if (entries.length === 1) {
          value = entries[0][1];
        } else {
          // Multiple properties - keep full object
          value = meta.values;
        }

        driverData[key] = value;
      }

      return {
        driver_id: driver.id,
        driver_name: driver.name,
        ...driverData,
      };
    });
}

// Pre-load types
async function loadTypes(apiToken, page = 1) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/core/types?api_token=${apiToken}&filter=populate&page=${page}`
  );
  const data = await response.json();

  data.data.forEach(type => {
    typesCache.set(type.id, type);
  });

  // Recursively fetch the next page, if available
  if(data.pagination.has_more) {
    await loadTypes(apiToken, page + 1)
  }
}

const API_TOKEN = 'YOUR_TOKEN';

loadTypes(API_TOKEN) // Load types before retrieving data
  .then(async () => await getDriverDetails(API_TOKEN))
  .then(console.log);

---

Team information (per season)

In v3, teams now have richer season-specific information via the seasondetails include. The advantage of this, is that the season-specific data for previous seasons will stay in place.

We'll cover the car and lead information here, however the data also contain previous team names and logos, so you can retrieve the older branding for displaying historical data.

Getting teams for a specific season

v2 approach:

GET /v1/teams/season/SEASON_ID

v3 approach (Option 1 - All teams and data):

GET /v3/motorsport/teams
  ?api_token=YOUR_TOKEN
  &include=seasondetails

v3 approach (Option 2 - Specific season):

GET /v3/motorsport/teams/seasons/26733
  ?api_token=YOUR_TOKEN
  &include=seasondetails
  &filters=participantseasondetailSeasons:26733

Understanding season details

The seasondetails include provides season-specific team information:

{
  "id": 456,
  "name": "Red Bull Racing",
  "seasondetails": [
    {
      "id": 27,
      "participant_id": 276190,
      "season_id": 26733,
      "type_id": 109856,
      "data": {
        "color_code": "#0600ef"
      }
    },
    {
      "id": 38,
      "participant_id": 276190,
      "season_id": 26733,
      "type_id": 109857,
      "data": {
        "team_lead": "Laurent Mekies"
      }
    },
    {
      "id": 49,
      "participant_id": 276190,
      "season_id": 26733,
      "type_id": 109858,
      "data": {
        "technical_lead": "Pierre Wache"
      }
    },
    {
      "id": 82,
      "participant_id": 276190,
      "season_id": 26736,
      "type_id": 109854,
      "data": {
        "engine": "Red Bull Powertrains–Ford"
      }
    }
  ]
}

A full list of available types can be found here: Team

Code Example: Getting team details for the 2025 season

const typesCache = new Map();

async function getTeamDetails(seasonId, apiToken) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/teams` +
      `?api_token=${apiToken}` +
      `&include=seasondetails` +
      `&filters=participantseasondetailSeasons:${seasonId}`
  );

  const json = await response.json();
  const teams = Array.isArray(json.data) ? json.data : [];

  return teams
    .map((team) => {
      const seasonDetails = (team.seasondetails ?? []).filter(
        (sd) => sd.season_id === seasonId
      );

      const seasonData = {};

      for (const detail of seasonDetails) {
        const type = typesCache.get(detail.type_id);
        if (!type || detail.data == null) continue;

        const key = type.developer_name?.toLowerCase();
        if (!key) continue;

        let value;

        const entries = Object.entries(detail.data);

        // Single-property object - unwrap
        if (entries.length === 1) {
          value = entries[0][1];
        } else {
          // Multiple properties - keep full object
          value = detail.data;
        }

        seasonData[key] = value;
      }

      return {
        team_id: team.id,
        team_name: seasonData.team_name ?? team.name,
        ...seasonData,
      };
    });
}

// Pre-load types
async function loadTypes(apiToken, page = 1) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/core/types?api_token=${apiToken}&filter=populate&page=${page}`
  );
  const data = await response.json();

  data.data.forEach(type => {
    typesCache.set(type.id, type);
  });

  // Recursively fetch the next page, if available
  if(data.pagination.has_more) {
    await loadTypes(apiToken, page + 1)
  }
}

const API_TOKEN = 'YOUR_TOKEN';
const SEASON_ID = 25273;

loadTypes(API_TOKEN) // Load types before retrieving data
  .then(async () => await getTeamDetails(SEASON_ID, API_TOKEN))
  .then(console.log);

---

Track information

In v2, track information was included in track responses. In v3, all track-specific metadata (length, direction and type) is now in a dedicated metadata object.

Accessing track data

Endpoint:

GET /v3/motorsport/venues
  ?api_token=YOUR_TOKEN
  &include=metadata

You can also use the venue include on the livescores or fixture endpoints to include this data for any fixture

Response structure:

{
  "data": [
    {
      "id": 123,
      "name": "Hungaroring",
      "metadata": [
        {
          "id": 9079931,
          "metadatable_id": 343588,
          "type_id": 109729,
          "value_type": "object",
          "values": {
            "length": "4.381 km"
          }
        },
        {
          "id": 9079963,
          "metadatable_id": 343588,
          "type_id": 109730,
          "value_type": "object",
          "values": {
            "direction": "clockwise"
          }
        },
        {
          "id": 9079995,
          "metadatable_id": 343588,
          "type_id": 109731,
          "value_type": "object",
          "values": {
            "type": "race-circuit"
          }
        }
      ]
    }
  ]
}

A full list of available types can be found here: Venue

Code Example: Retrieving track information

const typesCache = new Map();

async function getTrackDetails(apiToken) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/motorsport/venues` +
      `?api_token=${apiToken}` +
      `&include=metadata` +
      `&per_page=50`
  );

  const json = await response.json();
  const tracks = Array.isArray(json.data) ? json.data : [];

  return tracks
    .map((venue) => {
      const metadata = (venue.metadata ?? []);

      const trackData = {};

      for (const meta of metadata) {
        const type = typesCache.get(meta.type_id);
        if (!type || meta.values == null) continue;

        const key = type.developer_name?.toLowerCase();
        if (!key) continue;

        let value;

        const entries = Object.entries(meta.values);

        // Single-property object - unwrap
        if (entries.length === 1) {
          value = entries[0][1];
        } else {
          // Multiple properties - keep full object
          value = meta.values;
        }

        trackData[key] = value;
      }

      return {
        track_id: venue.id,
        track_name: venue.name,
        ...trackData,
      };
    });
}

// Pre-load types
async function loadTypes(apiToken, page = 1) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/core/types?api_token=${apiToken}&filter=populate&page=${page}`
  );
  const data = await response.json();

  data.data.forEach(type => {
    typesCache.set(type.id, type);
  });

  // Recursively fetch the next page, if available
  if(data.pagination.has_more) {
    await loadTypes(apiToken, page + 1)
  }
}

const API_TOKEN = 'YOUR_TOKEN';

loadTypes(API_TOKEN) // Load types before retrieving data
  .then(async () => await getTrackDetails(API_TOKEN))
  .then(console.log);

---

Quick reference: Common scenarios

Scenario 1: "I need race finishing positions"

v2:

results.forEach(r => console.log(r.position));

v3:

lineups.forEach(lineup => {
  const posDetail = lineup.details.find(d => d.type.code === 'position');
  console.log(posDetail?.data.position);
});

Scenario 2: "I need to check who DNF'd"

v2:

const dnfs = results.filter(r => r.retired);

v3:

const dnfs = lineups.filter(lineup => {
  const statusDetail = lineup.details.find(d => d.type.code === 'status');
  return statusDetail?.data.status === 'DNF';
});

Scenario 3: "I need fastest lap times"

v2:

results.forEach(r => console.log(r.best_lap_time));

v3:

lineups.forEach(lineup => {
  const fastLapDetail = lineup.details.find(d => d.type.code === 'fastest-lap');
  console.log(fastLapDetail?.data.time);
});

Scenario 4: "I need starting grid positions"

v2:

results.forEach(r => console.log(r.grid));

v3:

lineups.forEach(lineup => {
  console.log(lineup.grid_position);  // Direct property!
});

Scenario 5: "I need driver IDs"

v2:

results.forEach(r => console.log(r.driver_id));

v3:

lineups.forEach(lineup => {
  console.log(lineup.player_id);  // Note: player_id, not driver_id
});

---

Migration checklist

Use this checklist when migrating from v2 to v3:

Data access

• Replace results array with lineups array

• Change driver_id to player_id

• Change track_id to venue_id (at fixture level)

• Update grid to grid_position

Result details

• Implement helper function to find details by type code

• Update time extraction: driver_time → details[type=time].data.time

• Update interval extraction: driver_time_int → details[type=interval].data.interval

• Update fastest lap: best_lap_time → details[type=fastest-lap].data.time

• Update fastest lap number: fastest_lap → details[type=fastest-lap].data.lap_number

• Update laps: laps → details[type=laps].data.laps

• Update pitstops: pit → details[type=pitstops].data.stops

• Update status: retired boolean → details[type=status].data.status enum

Includes

• Add include=lineups to fixture requests

• Add include=lineups.details.type for typed result data

• Add include=lineups.driver for driver names

• Add include=lineups.driver.metadata for debut info

Caching

• Implement types caching (30+ days)

• Implement states caching (30+ days)

• Cache type IDs for faster detail lookups

---

Getting Help

If you encounter issues or have questions during migration:

• Email: [email protected]

• Documentation: Motorsport API v3 Docs

• Migration Guide: Main Migration Page

We're here to help make your migration as smooth as possible!

---

Tip: Start by updating one endpoint at a time. Test thoroughly before moving to the next. The structure is consistent across all fixtures, so once you understand lineups and details, the pattern repeats everywhere.