Make your first request

This tutorial walks through your first live call to the Motorsport API, then shows how adding an include changes the response.

10 minutes Skill level: Beginner Prerequisites: Authentication

Before you start

Make sure you have an API token. See Authentication if you do not have one yet.

Request 1: a basic request

Every request starts with the base URL for the entity you want, plus your token. Let's request all fixtures in your subscription:

https://api.sportmonks.com/v3/motorsport/fixtures?api_token=YOUR_TOKEN

Paste this into your browser, Postman, or a terminal with curl, substituting your real token. A basic response looks like this:

{
  "data": [
    {
      "id": 123456,
      "name": "Bahrain Grand Prix 2024",
      "starting_at": "2024-03-02 15:00:00",
      "state_id": 1,
      "stage_id": 5001,
      "venue_id": 12
    }
  ],
  "subscription": [
    {
      "meta": {},
      "plans": []
    }
  ],
  "rate_limit": {
    "resets_in_seconds": 3421,
    "remaining": 2997,
    "requested_entity": "Fixture"
  }
}

Notice the rate_limit object. The default plan provides 3,000 API calls per entity per hour, and the limit resets one hour after your first request to that entity.

This is a basic response: just the core fields. No driver lineups, no results, no venue details.

Request 2: add an include

To get more than the basic fields, add &include=. Let's enrich the same fixture with its state:

https://api.sportmonks.com/v3/motorsport/fixtures?api_token=YOUR_TOKEN&include=state

Each entity supports a different set of includes. You can find the available includes for each endpoint on its page under Endpoints.

Request 3: multiple includes

You can chain includes with a semicolon to enrich the response further in a single call:

https://api.sportmonks.com/v3/motorsport/fixtures
?api_token=YOUR_TOKEN&include=state;lineups;results

This single request now returns the fixture, its current state, the driver lineup, and the session results, instead of three separate calls.

Code examples

const API_TOKEN = 'YOUR_TOKEN';

async function getFixtures() {
  const url = `https://api.sportmonks.com/v3/motorsport/fixtures?api_token=${API_TOKEN}&include=state`;
  try {
    const response = await fetch(url);
    const data = await response.json();
    return data.data;
  } catch (error) {
    console.error('Error fetching fixtures:', error);
  }
}

import requests

API_TOKEN = "YOUR_TOKEN"

def get_fixtures():
    url = "https://api.sportmonks.com/v3/motorsport/fixtures"

    params = {
        "api_token": API_TOKEN,
        "include": "state",
    }

    try:
        response = requests.get(url, params=params)
        response.raise_for_status()

        data = response.json()
        return data.get("data", [])

    except requests.RequestException as error:
        print("Error fetching fixtures:", error)
        return None

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.sportmonks.com/v3/motorsport/fixtures?api_token=YOUR_TOKEN&include=state',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

Common pitfalls

Forgetting the semicolon between includes. Includes are separated with ;, not ,. A comma-separated include list silently fails or returns unexpected results depending on the endpoint.

Assuming every entity supports every include. Not all includes are available on every endpoint. Check the specific endpoint's documentation before assuming an include exists.

Treating an empty data array as an error. If your subscription does not include a particular league or season, or there are simply no fixtures matching your query, you will get a 200 response with an empty data array. This is expected behaviour, not a failure.

FAQ

Why is my response missing fields I expected? The default response only includes core fields. Add the relevant include, or check whether the field is gated behind a select= restriction. See Filter and select fields.

Can I test requests without writing code? Yes. Paste any request URL directly into a browser address bar, or use a tool like Postman.

Last updated 13 days ago

Was this helpful?