NAV Navbar
curl
  • Introduction
  • Authentication
  • Livescores
  • Seasons
  • Tracks
  • Teams
  • Drivers
  • Errors
  • Introduction

    Welcome to the documentation section for the SportMonks Formula 1 API V1.0. On this page we aim to get you started with our Formula 1 API in minutes. If there are items missing on unclear you may send us a support request

    Authentication

    SportMonks uses API token to allow access to the API. You can register a new SportMonks API key here.

    Got to https://www.sportmonks.com/settings#/api to create an API token

    SportMonks expects the API token that can be included in all API requests to the server as part of the request

    Livescores

    Make sure to replace d4ksomxFumF6veb..... with your API key.

    Get All Seasons

    Example Request:

    curl "https://f1.sportmonks.com/api/v1.0/livescores?api_token=d4ksomxFumF6..."
    -H "Accept: application/json"
    

    Example Response:

    {  
       "data": [  
          {  
             "name": "Race",
             "track_id": 2,
             "season_id": 3,
             "country_id": null,
             "time": {  
                "status": "LIVE",
                "starting_at": {  
                   "date_time": "2018-11-25 14:10:00",
                   "date": "2018-11-25",
                   "time": "14:10:00",
                   "timestamp": 1543155000,
                   "timezone": "UTC"
                }
             },
             "results": {  
                "data": [  
                   {  
                      "driver_id": 1,
                      "team_id": 13,
                      "track_id": 2,
                      "season_id": 3,
                      "stage_id": 1,
                      "position": 1,
                      "driver_time": null,
                      "laps": 55,
                      "grid": "1",
                      "pit": "1",
                      "retired": null
                   },
                   {  
                      "driver_id": 2,
                      "team_id": 11,
                      "track_id": 2,
                      "season_id": 3,
                      "stage_id": 1,
                      "position": 2,
                      "driver_time": "+2.581",
                      "laps": 55,
                      "grid": "3",
                      "pit": "1",
                      "retired": null
                   }
                ]
             }
          }
       ]
    }
    

    HTTP Request

    GET https://f1.sportmonks.com/api/v1.0/livescores?api_token=d4ksomxFumF6...

    Query Parameters

    Parameter Required Description
    api_token true This is the token that will allow you to access the API
    include false This is the relationship that can be included. eg results and track

    Response Attributes

    Name Type Description
    name string The name of the livescore sport
    track_id integer The track id of the livescore
    season_id integer The season id of the livescore
    country_id integer The country id where this livescore is taking place
    time object Details about the time when this livescore is taking place
    results object An array representing results from the track under different drivers and teams. Below are attributes of the results
    driver_id integer The driver id under this result
    team_id integer The id of the team who made this result
    track_id integer The track id of this result
    season_id integer The id of the season when this result was recorded
    stage_id integer The id of the stage where this result was recorded
    position integer The position of the team in the livescore
    driver_time string
    laps integer Laps covered under this track
    grid string
    pit string
    retired

    Get Seasons by id

    Example Request:

    curl "https://f1.sportmonks.com/api/v1.0/livescores/now?api_token=d4ksomxFumF6..."
    -H "Accept: application/json"
    

    Example Response:

    {  
       "data": [  
          {  
             "name": "Race",
             "track_id": 2,
             "season_id": 3,
             "country_id": null,
             "time": {  
                "status": "LIVE",
                "starting_at": {  
                   "date_time": "2018-11-25 14:10:00",
                   "date": "2018-11-25",
                   "time": "14:10:00",
                   "timestamp": 1543155000,
                   "timezone": "UTC"
                }
             },
             "results": {  
                "data": [  
                   {  
                      "driver_id": 1,
                      "team_id": 13,
                      "track_id": 2,
                      "season_id": 3,
                      "stage_id": 1,
                      "position": 1,
                      "driver_time": null,
                      "laps": 55,
                      "grid": "1",
                      "pit": "1",
                      "retired": null
                   },
                   {  
                      "driver_id": 2,
                      "team_id": 11,
                      "track_id": 2,
                      "season_id": 3,
                      "stage_id": 1,
                      "position": 2,
                      "driver_time": "+2.581",
                      "laps": 55,
                      "grid": "3",
                      "pit": "1",
                      "retired": null
                   }
                ]
             }
          }
       ]
    }
    

    HTTP Request

    GET https://f1.sportmonks.com/api/v1.0/livescores/now?api_token=d4ksomxFumF6...

    Query Parameters

    Parameter Required Description
    api_token true This is the token that will allow you to access the API
    include false This is the relationship that can be included. eg results and track

    Response Attributes

    Name Type Description
    name string The name of the livescore sport
    track_id integer The track id of the livescore
    season_id integer The season id of the livescore
    country_id integer The country id where this livescore is taking place
    time object Details about the time when this livescore is taking place
    results object An array representing results from the track under different drivers and teams. Below are attributes of the results
    driver_id integer The driver id under this result
    team_id integer The id of the team who made this result
    track_id integer The track id of this result
    season_id integer The id of the season when this result was recorded
    stage_id integer The id of the stage where this result was recorded
    position integer The position of the team in the livescore
    driver_time string
    laps integer Laps covered under this track
    grid string
    pit string
    retired

    Seasons

    Make sure to replace d4ksomxFumF6veb..... with your API key.

    Get All Seasons

    Example Request:

    curl "https://f1.sportmonks.com/api/v1.0/seasons?api_token=d4ksomxFumF6..."
    -H "Accept: application/json"
    

    Example Response:

    {
      "data": [
        {
          "id": 1,
          "name": "2018"
        },
        {
          "id": 2,
          "name": "2019"
        }
      ]
    }
    

    HTTP Request

    GET https://f1.sportmonks.com/api/v1.0/seasons?api_token=d4ksomxFumF6...

    Query Parameters

    Parameter Required Description
    api_token true This is the token that will allow you to access the API
    include false This is the relationship that can be included. eg tracks

    Response Attributes

    Name Type Description
    id integer The id of the season
    name string The name of the season

    Get Seasons by id

    Example Request:

    curl "https://f1.sportmonks.com/api/v1.0/seasons/1?api_token=d4ksomxFumF6..."
    -H "Accept: application/json"
    

    Example Response:

    {
      "data": {
        "id": 1,
        "name": "2018"
      }
    }
    

    HTTP Request

    GET https://f1.sportmonks.com/api/v1.0/seasons/{id}?api_token=d4ksomxFumF6...

    Query Parameters

    Parameter Required Description
    api_token true This is the token that will allow you to access the API
    include false This is the relationship that can be included. eg tracks

    Response Attributes

    Name Type Description
    id integer The id of the season
    name string The name of the season

    Tracks

    Make sure to replace d4ksomxFumF6veb..... with your API key.

    Get All Tracks

    Example Request:

    curl "https://f1.sportmonks.com/api/v1.0/tracks?api_token=d4ksomxFumF6..."
    -H "Accept: application/json"
    

    Example Response:

    {
      "data": [
        {
          "id": 1,
          "name": "Australian Grand Prix",
          "country_id": 91,
          "image_path": "https://cdn.sportmonks.com/images/path/to/track/1"
        },
        {
          "id": 2,
          "name": "Chinese Grand Prix",
          "country_id": 17,
          "image_path": "https://cdn.sportmonks.com/images/path/to/track/2"
        }
      ]
    }
    

    HTTP Request

    GET https://f1.sportmonks.com/api/v1.0/tracks?api_token=d4ksomxFumF6...

    Query Parameters

    Parameter Required Description
    api_token true This is the token that will allow you to access the API
    include false This is the relationship that can be included. eg seasons, stages, currentStage

    Response Attributes

    Name Type Description
    id integer The id of the track
    name string The name of the track
    country_id integer The country id of the track
    image_path string Path to the image of the track

    Get Tracks by id

    Example Request:

    curl "https://f1.sportmonks.com/api/v1.0/tracks/1?api_token=d4ksomxFumF6..."
    -H "Accept: application/json"
    

    Example Response:

    {
      "data": {
        "id": 1,
        "name": "Australian Grand Prix",
        "country_id": 91,
        "image_path": "https://cdn.sportmonks.com/images/path/to/track/1"
      }
    }
    

    HTTP Request

    GET https://f1.sportmonks.com/api/v1.0/tracks/{id}?api_token=d4ksomxFumF6...

    Query Parameters

    Parameter Required Description
    api_token true This is the token that will allow you to access the API
    include false This is the relationship that can be included. eg seasons, stages, currentStage

    Response Attributes

    Name Type Description
    id integer The id of the track
    name string The name of the track
    country_id integer The country id of the track
    image_path string Path to the image of the track

    Get Tracks By Season Id

    Example Request:

    curl "https://f1.sportmonks.com/api/v1.0/tracks/season/1?api_token=d4ksomxFumF6..."
    -H "Accept: application/json"
    

    Example Response:

    {
      "data": [
        {
          "id": 1,
          "name": "Australian Grand Prix",
          "country_id": 91,
          "image_path": "https://cdn.sportmonks.com/images/path/to/track/1"
        },
        {
          "id": 2,
          "name": "Chinese Grand Prix",
          "country_id": 17,
          "image_path": "https://cdn.sportmonks.com/images/path/to/track/2"
        }
      ]
    }
    

    HTTP Request

    GET https://f1.sportmonks.com/api/v1.0/tracks/season/{id}?api_token=d4ksomxFumF6...

    Query Parameters

    Parameter Required Description
    api_token true This is the token that will allow you to access the API
    include false This is the relationship that can be included. eg seasons, stages, currentStage

    Response Attributes

    Name Type Description
    id integer The id of the track
    name string The name of the track
    country_id integer The country id of the track
    image_path string Path to the image of the track

    Teams

    Make sure to replace d4ksomxFumF6veb..... with your API key.

    Get Teams By Season Id

    Example Request:

    curl "https://f1.sportmonks.com/api/v1.0/teams/season/1?api_token=d4ksomxFumF6..."
    -H "Accept: application/json"
    

    Example Response:

    {
      "data": [
        {
          "id": 1,
          "team_id": 2,
          "season_id": 1,
          "points": 55,
          "position": 2
        },
        {
          "id": 2,
          "team_id": 3,
          "season_id": 1,
          "points": 65,
          "position": 1
        }
      ]
    }
    

    HTTP Request

    GET https://f1.sportmonks.com/api/v1.0/teams/season/{id}?api_token=d4ksomxFumF6...

    Query Parameters

    Parameter Required Description
    api_token true This is the token that will allow you to access the API
    include false This is the relationship that can be included. eg team

    Response Attributes

    Name Type Description
    id integer The id of the driver
    team_id integer The id of the team
    season_id integer The id of the season
    points integer The number of points attained by the team in this season
    position integer The position of the team in this season

    Drivers

    Make sure to replace d4ksomxFumF6veb..... with your API key.

    Get Drivers By Season Id

    Example Request:

    curl "https://f1.sportmonks.com/api/v1.0/drivers/season/1?api_token=d4ksomxFumF6..."
    -H "Accept: application/json"
    

    Example Response:

    {
      "data": [
        {
          "id": 1,
          "driver_id": 2,
          "team_id": 11,
          "season_id": 1,
          "points": 320,
          "position": 2
        },
        {
          "id": 2,
          "driver_id": 3,
          "team_id": 13,
          "season_id": 1,
          "points": 308,
          "position": 1
        }
      ]
    }
    

    HTTP Request

    GET https://f1.sportmonks.com/api/v1.0/drivers/season/{id}?api_token=d4ksomxFumF6...

    Query Parameters

    Parameter Required Description
    api_token true This is the token that will allow you to access the API
    include false This is the relationship that can be included. eg driver

    Response Attributes

    Name Type Description
    id integer The id of the driver
    driver_id integer The driver's id
    team_id integer The id of the team
    season_id integer The id of the season
    points integer The number of points attained by the team in this season
    position integer The position of the team in this season

    Errors

    SportMonks uses conventional HTTP response codes to indicate the success or failure of an API request.

    In general:

    HTTP status code summary

    200 - OK - Everything worked successfully.
    
    
    400 - Bad Request   - The request was unacceptable, often due to missing a required parameter.
    
    
    401 - Unauthorized  - No valid API key provided.
    
    
    402 - Request Failed - The parameters were valid but the request failed.
    
    
    404 - Not Found - The requested resource doesnt exist
    
    
    409 - Conflict  - The request has conflicts (perhaps due to using the same idempotent key).
    
    
    429 - Too Many Requests - Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
    
    
    500, 502, 503, 504 - Server Errors