# Migrating from Formula One API (v1) to Motorsport API v3 {% hint style="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 and we'll help you {% endhint %} *** ### 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 *** ### 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 | *** ### 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: {% columns %} {% column %} {% content-ref url="migrating-from-formula-one-api-v1-to-motorsport-api-v3/stages-fixtures" %} [stages-fixtures](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/guides/migrating-from-formula-one-api-v1-to-motorsport-api-v3/stages-fixtures) {% endcontent-ref %} {% content-ref url="migrating-from-formula-one-api-v1-to-motorsport-api-v3/drivers" %} [drivers](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/guides/migrating-from-formula-one-api-v1-to-motorsport-api-v3/drivers) {% endcontent-ref %} {% content-ref url="migrating-from-formula-one-api-v1-to-motorsport-api-v3/teams" %} [teams](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/guides/migrating-from-formula-one-api-v1-to-motorsport-api-v3/teams) {% endcontent-ref %} {% endcolumn %} {% column %} {% content-ref url="migrating-from-formula-one-api-v1-to-motorsport-api-v3/tracks-venues" %} [tracks-venues](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/guides/migrating-from-formula-one-api-v1-to-motorsport-api-v3/tracks-venues) {% endcontent-ref %} {% content-ref url="migrating-from-formula-one-api-v1-to-motorsport-api-v3/seasons" %} [seasons](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/guides/migrating-from-formula-one-api-v1-to-motorsport-api-v3/seasons) {% endcontent-ref %} {% content-ref url="migrating-from-formula-one-api-v1-to-motorsport-api-v3/status-state" %} [status-state](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/guides/migrating-from-formula-one-api-v1-to-motorsport-api-v3/status-state) {% endcontent-ref %} {% endcolumn %} {% endcolumns %} *** ### 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](https://app.gitbook.com/s/z0kWjB5EvZvqGsozw8vP/entities) are part of the sport-independent [Core API](https://app.gitbook.com/o/-MJWE53IpT91aRTPjruo/s/z0kWjB5EvZvqGsozw8vP/), 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](https://app.gitbook.com/s/z0kWjB5EvZvqGsozw8vP/endpoints/types) endpoints or included with the `type` or `position` include. * Countries (`country_id`) can be retrieved using the [Countries](https://app.gitbook.com/s/z0kWjB5EvZvqGsozw8vP/endpoints/countries) endpoints or included with the `country` include. * Cities (`city_id`) can be retrieved using the [Cities](https://app.gitbook.com/s/z0kWjB5EvZvqGsozw8vP/endpoints/cities) endpoints or included using the `city` include. *** ### Endpoint Migration #### Stages / Fixtures **Related endpoints:** [`Fixtures`](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/fixtures) , [`Schedules`](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/schedules) , [`Seasons`](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/seasons) , [`Stages`](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/stages)\ **Related entities:** [`Fixtures`](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/fixture), [`Schedule`](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/schedule) , [`Season`](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/season) , [`Stage`](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/stage) **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 Livescores](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/live/get-all-livescores) endpoint instead. **Old API (v1):** ```http https://f1.sportmonks.com/api/v1.0/stages/ID ``` 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:** ```http https://api.sportmonks.com/v3/motorsport/fixtures/FIXTURE_ID ?api_token=YOUR_TOKEN &include=venue ``` **Including results only:** ```http https://api.sportmonks.com/v3/motorsport/fixtures/FIXTURE_ID ?api_token=YOUR_TOKEN &include=results ``` **Including a broad set of information (status, lap counter, track info, results):** ```http https://api.sportmonks.com/v3/motorsport/fixtures/FIXTURE_ID ?api_token=YOUR_TOKEN &include=state;metadata;venue;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 {% hint style="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 Livescores](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/live/get-all-livescores) 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](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/tutorials/retrieving-results). {% endhint %} *** ### 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. {% hint style="info" %} Also check the guide [understanding-race-results-driver-team-and-track-data-in-v3](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/guides/understanding-race-results-driver-team-and-track-data-in-v3 "mention") for more information on using result data. {% endhint %} **Old API (v1):** ```http https://f1.sportmonks.com/api/v1.0/stages/season/SEASON_ID ``` **New API (v3):** Including track info, no results (intended for schedules): ```http https://api.sportmonks.com/v3/motorsport/schedules/seasons/SEASON_ID ?api_token=YOUR_TOKEN ``` 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: ```http https://api.sportmonks.com/v3/motorsport/fixtures/FIXTURE_ID ?api_token=YOUR_TOKEN&include=results;state;venue ``` Including a broad set of information (status, track info, results, lineups): ```http https://api.sportmonks.com/v3/motorsport/fixtures/FIXTURE_ID ?api_token=YOUR_TOKEN &include=results;state;venue.metadata;metadata;lineups ``` Available includes for fixtures: `sport`, `stage`, `league`, `season`, `venue`, `state`, `lineups`, `participants`, `metadata`, `results`, `latestLaps`, `pitstops`, `latestPitstops`, `stints`, `latestStints` ### Drivers **Related endpoint:** [`Drivers`](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/drivers) **Related entity:** [`Driver`](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/driver) **Basic driver information:** Old API (v1): ```http https://f1.sportmonks.com/api/v1.0/drivers ``` New API (v3): ```http https://api.sportmonks.com/v3/motorsport/drivers ?api_token=YOUR_TOKEN ``` **Including driver metadata (debut information and other driver-specific data):** New API (v3): ```http https://api.sportmonks.com/v3/motorsport/drivers ?api_token=YOUR_TOKEN&include=metadata ``` Available includes: `sport`, `country`, `city`, `nationality`, `teams`, `latest`, `position`, `lineups`, `metadata`, `seasonDetails` **Including teams information (current team for each driver):** New API (v3): ```http https://api.sportmonks.com/v3/motorsport/drivers ?api_token=YOUR_TOKEN&include=teams ``` ### Teams **Related endpoint:** [`Teams`](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/teams) **Related entity:** [`Team`](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/team) **Basic team information:** Old API (v1): ```http https://f1.sportmonks.com/api/v1.0/teams ``` New API (v3): ```http https://api.sportmonks.com/v3/motorsport/teams ?api_token=YOUR_TOKEN ``` **Including additional team information:** New API (v3): ```http https://api.sportmonks.com/v3/motorsport/teams ?api_token=YOUR_TOKEN &include=country;latest;upcoming;seasons;seasonDetails ``` **For season-specific team information:** New API (v3): ```http https://api.sportmonks.com/v3/motorsport/teams/seasons/SEASON_ID ?api_token=YOUR_TOKEN &include=country;latest;upcoming;seasons;seasonDetails &filter=participantSeasonDetailSeasons:SEASON_ID ``` Available includes: `sport`, `country`, `players`, `latest`, `upcoming`, `seasons`, `seasonDetails` ### Standings **Related endpoint:** [`Standings`](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/standings) **Related entity:** [`Standing`](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/standing) In v3, driver and team points and positions for a season are available via dedicated standings endpoints. **Driver standings:** Old API (v1): ```http https://f1.sportmonks.com/api/v1.0/standings/drivers ``` New API (v3): ```http https://api.sportmonks.com/v3/motorsport/standings/drivers ?api_token=YOUR_TOKEN &include=participant ``` For season-specific driver standings: ```http https://api.sportmonks.com/v3/motorsport/standings/drivers/SEASON_ID ?api_token=YOUR_TOKEN &include=participant ``` **Team standings:** Old API (v1): ```http https://f1.sportmonks.com/api/v1.0/standings/teams ``` New API (v3): ```http https://api.sportmonks.com/v3/motorsport/standings/teams ?api_token=YOUR_TOKEN &include=participant ``` For season-specific team standings: ```http https://api.sportmonks.com/v3/motorsport/standings/teams/SEASON_ID ?api_token=YOUR_TOKEN &include=participant ``` **Available includes:** `sport`, `participant`, `season`, `league`, `stage` ### Tracks / Venues **Related endpoint:** [Venues](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/venues) **Related entity:** [Venue](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/venue) **All available tracks:** Old API (v1): ```http https://f1.sportmonks.com/api/v1.0/tracks ``` New API (v3): ```http https://api.sportmonks.com/v3/motorsport/venues ?api_token=YOUR_TOKEN&include=country;city ``` **Season-specific tracks:** Old API (v1): ```http https://f1.sportmonks.com/api/v1.0/tracks/season/SEASON_ID ``` New API (v3): ```http https://api.sportmonks.com/v3/motorsport/venues/seasons/SEASON_ID ?api_token=YOUR_TOKEN&include=country;city ``` **Available includes:** `country`, `fixture`, `city` ### 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 | *** ### Migration Checklist * [ ] Update all old entity IDs to new IDs using the mapping table above * [ ] Replace old F1 API endpoints with new Motorsport API v3 endpoints * [ ] Add `include` parameters to explicitly request needed data * [ ] Update code to handle the new response structure * [ ] Test used endpoints with existing data * [ ] Update error handling for new API error responses *** ### Getting Help If you have questions or encounter issues during migration: * Email: * Documentation: [Motorsport API v3 Docs](https://docs.sportmonks.com/v3/motorsport-api) * Status: This API is currently in **BETA -** However, there are no plans for major or breaking changes during these weeks. We're here to help make your migration as smooth as possible!