search
CricketMotorsportAPI 2 (Deprecated)WidgetsContact

Migrating from Formula One API (v2) to Motorsport API v3

This guide describes everything you need to know about migrating from the old Formula One API (v1) to the new Motorsport API v3.

circle-info

If you have questions or problems while migrating, or if you are missing something in the new Motorsport API v3, please let us know via [email protected]envelope and we'll help you

hashtag
Overview of Changes

The Motorsport API v3 represents a significant upgrade from the Formula One API v1:

  • Unified data model: While Motorsport API v3 currently only provides Formula 1 data, it is designed to allow future addition of other motorsport championships (e.g. Formula 2, Formula 3, NASCAR, etc.) within the same API structure. This is also why the 'Motorsport' name is chosen over 'Formula One'.

  • Cleaner architecture: Follows the same patterns as Football API v3

  • Granular control: Choose exactly which data to include via the include parameter

  • Better performance: Optimised queries and improved response times

  • Enhanced filtering: More flexible filtering options for complex queries

hashtag
Renamed Entities

These are the most important changes related to entity names. The new structure is consistent with the cross-sport API v3 structure.

v1 name

Example

v3 name

Stage

Practice 1, Qualification 2, Race

Fixture

Track (in Grand Prix/race weekend context)

Australian Grand Prix

Stage

Track (in track/circuit context)

Yas Marina Circuit

Venue

hashtag
Entity ID Changes

All entity IDs have been changed in the new API. You can find the reference tables for each entity type on the pages below:

calendar-clockStages / Fixtureschevron-rightuserDriverschevron-rightpeople-groupTeamschevron-right
roadTracks / Venueschevron-rightcalendarSeasonschevron-rightplay-pauseStatus / Statechevron-right

hashtag
Related core entities

Across Motorsport API v3, you may encounter certain entities that do not have any reference in the Motorsport API v3 documentation, like types, countries and cities. This is because those entities are part of the sport-independent Core API, which is included in any v3 API plan.

These are the core entities you may encounter in the Motorsport v3 API:

  • Types and positions (type_id, position_id) can be retrieved in the Types endpoints or included with the type or position include.

  • Countries (country_id) can be retrieved using the Countries endpoints or included with the country include.

  • Cities (city_id) can be retrieved using the Cities endpoints or included using the city include.

hashtag
Endpoint Migration

hashtag
Stages / Fixtures

Related endpoints: Fixturesarrow-up-right , Schedulesarrow-up-right , Seasonsarrow-up-right , Stagesarrow-up-right Related entities: Fixturesarrow-up-right, Schedulearrow-up-right , Seasonarrow-up-right , Stagearrow-up-right

Single Stage / Fixture

This endpoint includes results and some information by default. In v3, you can choose what to include tailored to your use case.

For live data purposes, it is recommended to use the GET All Livescoresarrow-up-right endpoint instead.

Old API (v1):

This endpoint included results and match information by default.

New API (v3):

In v3, you have full control over what data to include. Here are the most common scenarios:

Including track info:

Including results only:

Including a broad set of information (status, lap counter, track info, results):

Key differences:

  • Some data is no longer included by default, you must explicitly request it via the include parameter

  • More granular control over response size and performance

circle-info

In the previous version, this endpoint includes results and some information by default. In v3, you can choose what to include tailored to your use case. For live data purposes, it is recommended to use the GET All Livescoresarrow-up-right endpoint instead. There are two includes available for results. The results include contains a subset of data: position, time, interval, gap to leader and tyre. The lineups.details nested include also contains laps, pitstops, fastest lap, points and grid position. Find more info on results in this tutorial.

hashtag
Season Stages / Schedule / Results

This endpoint could be used for the schedule, results and some detailed information for the whole season. In v3, you can choose what to include on a season, or use the pre-defined schedule endpoint, tailored to your use case.

circle-info

Also check the guide Understanding Race Results & Driver Data in v3 for more information on using result data.

Old API (v1):

New API (v3):

Including track info, no results (intended for schedules):

Note: The Schedule endpoint returns stages with nested fixtures and venue data included by default. It does not support other requested includes.

For getting fixture results and other detailed information, use the Fixtures endpoint:

Including results:

Including a broad set of information (status, track info, results, lineups):

Available includes for fixtures: sport, stage, league, season, venue, state, lineups, participants, metadata, results, latestLaps, pitstops, latestPitstops, stints, latestStints

hashtag
Drivers

Related endpoint: Driversarrow-up-right

Related entity: Driverarrow-up-right

Basic driver information:

Old API (v1):

New API (v3):

Including driver metadata (debut information and other driver-specific data):

New API (v3):

Available includes: sport, country, city, nationality, teams, latest, position, lineups, metadata, seasonDetails

Including teams information (current team for each driver):

New API (v3):

hashtag
Teams

Related endpoint: Teamsarrow-up-right

Related entity: Teamarrow-up-right

Basic team information:

Old API (v1):

New API (v3):

Including additional team information:

New API (v3):

For season-specific team information:

New API (v3):

Available includes: sport, country, players, latest, upcoming, seasons, seasonDetails

hashtag
Standings

Related endpoint: Standingsarrow-up-right

Related entity: Standingarrow-up-right

In v3, driver and team points and positions for a season are available via dedicated standings endpoints.

Driver standings:

Old API (v1):

New API (v3):

For season-specific driver standings:

Team standings:

Old API (v1):

New API (v3):

For season-specific team standings:

Available includes: sport, participant, season, league, stage

hashtag
Tracks / Venues

Related endpoint: Venuesarrow-up-right

Related entity: Venuearrow-up-right

All available tracks:

Old API (v1):

New API (v3):

Season-specific tracks:

Old API (v1):

New API (v3):

Available includes: country, fixture, city

hashtag
Key Differences Summary

Aspect
Old API (v1)
New API (v3)

Data inclusion

Default (all data included in responses)

Opt-in via include parameter (only requested data)

Endpoint structure

Single endpoints per entity (e.g., /stages, /drivers, /teams)

Separate, specialised endpoints for different data types (e.g., /fixtures, /standings/drivers, /standings/teams)

Filtering capabilities

Limited filtering options

Advanced filtering support with static and dynamic filters

Response size

Large (some data included by default)

Optimised (only requested data returned)

ID mapping

Old IDs no longer valid in V3

Use new ID mappings provided in the Entity ID Changes section

Available endpoints

Limited: Stages, Teams, Drivers, Tracks, Standings, Winners

Expanded: 14 endpoint categories including Fixtures, Laps, Pitstops, Stints, Leagues, Seasons, Schedules, and States

hashtag
Migration Checklist

hashtag
Getting Help

If you have questions or encounter issues during migration:

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

Last updated

Was this helpful?