Fixtures

Included in all plans

Fixture data is available on all base plans (Starter, Growth, Pro, Enterprise) at no additional cost. Plans differ in the number of accessible leagues (5 to all leagues) and hourly API call limits (2,000 to 5,000+).

Compare plans →

Quick summary: This tutorial covers the ten fixtures endpoints available in API v3, how to retrieve match data across different timeframes and criteria, and how to enrich responses with scores, events, and lineups.

What you'll learn:

• Which of the ten fixture endpoints to use for different scenarios

• How to retrieve fixtures by date, date range, team, head-to-head, and search

• How to enrich fixture responses using includes and narrow them with filters

Time to complete: 25 minutes Skill level: Beginner Prerequisites: Authentication, Includes, Filter and Select Fields

1. When to use this feature

The fixtures endpoints are the most widely used in the API. They give you complete match data at any point in time (past, present, or future) across ten different retrieval options.

Real-world use cases

Use case 1: Match detail pages You're building a football app and a user clicks into a specific match. The fixture by ID endpoint returns everything: venue, officials, scores, and detailed metadata. Livescores would not work here because they only cover the 15-minute window around kickoff.

Use case 2: Team schedule pages You want to display all of Celtic's fixtures in September. The "Fixture by Date Range for Team" endpoint lets you pass a date range and a team ID to return only their matches in that period.

Use case 3: Historical analysis and H2H displays You want to show all past meetings between Rangers and Celtic before an upcoming derby. The Head to Head endpoint returns the full match history between any two team IDs.

Use case 4: Database sync and catch-up After downtime, you need to identify which records changed. The "Latest Updated Fixtures" endpoint returns all fixtures updated within the last 10 seconds, so you can patch only what changed.

When NOT to use this feature

• Real-time live scoreboard: Livescores are lighter and optimised for frequent polling during active matches. Use them for your live tracker, then fetch the full fixture when a user wants details.

• Full season schedule: For retrieving all fixtures in a season, the Schedules endpoint with include=fixtures is more efficient.

Recommended alternative: Livescores tutorial for real-time match tracking.

2. How to retrieve data

Understanding the endpoints

Base URL:

https://api.sportmonks.com/v3/football/fixtures

Available endpoints:

Endpoint	Path suffix	Description
GET All Fixtures	(base URL)	All fixtures in your subscription
GET Fixture by ID	/{fixture_id}	Single fixture by ID
GET Fixtures by Multiple IDs	/multi/{id1,id2}	Multiple fixtures in one request
GET Fixture by Date	/date/{YYYY-MM-DD}	All fixtures on a specific date
GET Fixture by Date Range	/between/{start}/{end}	Fixtures between two dates
GET Fixture by Date Range for Team	/between/{start}/{end}/{team_id}	A specific team's fixtures in a date range
GET Fixture by Head to Head	/head-to-head/{team_id}/{team_id}	All matches between two teams
GET Fixture by Search	/search/{query}	Fixtures matching a name search
GET Upcoming Fixtures by Market ID	/upcoming/markets/{market_id}	Upcoming fixtures with odds for a market
GET Latest Updated Fixtures	/latest	Fixtures updated within the last 10 seconds

Available parameters:

Parameter	Type	Required	Description	Example
api_token	string	Yes	Your API authentication token	YOUR_API_TOKEN
include	string	No	Related data to attach to the response	scores;participants;events
select	string	No	Specific fields to return	name,result_info
filters	string	No	Filter results by field values	fixtureLeagues:501

Step-by-step implementation

Step 1: Basic request — GET Fixture by ID

The simplest useful request: retrieving a single known fixture.

JavaScript:

Javascript

const apiToken = 'YOUR_API_TOKEN';
const fixtureId = 18535517; // Celtic vs Rangers

async function getFixture(id) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/football/fixtures/${id}?api_token=${apiToken}`
  );
  const data = await response.json();
  console.log(data);
}

getFixture(fixtureId);

Python

PHP

Step 2: GET Fixture by Date

Returns all fixtures from your subscription for a given date. Pass the date in YYYY-MM-DD format.

https://api.sportmonks.com/v3/football/fixtures/date/2022-09-03
?api_token=YOUR_API_TOKEN

JavaScript:

async function getFixturesByDate(date) {
  const response = await fetch(
    `https://api.sportmonks.com/v3/football/fixtures/date/${date}?api_token=${apiToken}`
  );
  return response.json();
}

Step 3: GET Fixtures by Date Range

Returns all fixtures between two dates. Useful for week or month views.

https://api.sportmonks.com/v3/football/fixtures/between/2022-09-01/2022-09-30
?api_token=YOUR_API_TOKEN

To restrict this to a specific team, append the team ID:

https://api.sportmonks.com/v3/football/fixtures/between/2022-09-01/2022-09-30/53
?api_token=YOUR_API_TOKEN

Step 4: Adding includes

Fixture responses return only IDs by default. Use include to attach related data in the same request.

https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_API_TOKEN&include=scores;participants;statistics.type;events;lineups

The most commonly used includes for fixtures are:

• scores : Full-time, half-time, and penalty scores

• participants : Home and away team details

• events : Goals, cards, and substitutions

• lineups : Starting XI and bench

• statistics.type : Match statistics with type labels

⚠️ Including .type on large result sets is expensive. Retrieve all types once from the Types endpoint and cache them rather than including them on every request.

Step 5: Selecting specific fields

If you only need a subset of fields, use select to reduce payload size. For example, returning only the result of Celtic vs Rangers:

https://api.sportmonks.com/v3/football/fixtures/18535517?api_token=YOUR_API_TOKEN&select=result_info

Response:

{
  "data": {
    "result_info": "Celtic won after full-time.",
    "id": 18535517
  }
}

Step 6: Complete example — fixture class

JavaScript:

Javascript

class FootballAPI {
  constructor(apiToken) {
    this.token = apiToken;
    this.baseURL = 'https://api.sportmonks.com/v3/football';
  }

  async getFixture(fixtureId, params = {}) {
    const query = new URLSearchParams({ api_token: this.token, ...params });
    const response = await fetch(
      `${this.baseURL}/fixtures/${fixtureId}?${query}`
    );
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return response.json();
  }

  async getFixturesByDateRange(startDate, endDate, teamId = null, params = {}) {
    const path = teamId
      ? `/fixtures/between/${startDate}/${endDate}/${teamId}`
      : `/fixtures/between/${startDate}/${endDate}`;
    const query = new URLSearchParams({ api_token: this.token, ...params });
    const response = await fetch(`${this.baseURL}${path}?${query}`);
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return response.json();
  }

  async getHeadToHead(teamIdA, teamIdB, params = {}) {
    const query = new URLSearchParams({ api_token: this.token, ...params });
    const response = await fetch(
      `${this.baseURL}/fixtures/head-to-head/${teamIdA}/${teamIdB}?${query}`
    );
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return response.json();
  }
}

// Usage
const api = new FootballAPI('YOUR_API_TOKEN');

// Full match details for Celtic vs Rangers
const fixture = await api.getFixture(18535517, {
  include: 'scores;participants;events;lineups'
});

// Celtic's September fixtures
const schedule = await api.getFixturesByDateRange('2022-09-01', '2022-09-30', 53);

// Old Firm history
const h2h = await api.getHeadToHead(53, 62);

Python

PHP

3. Working with the data

Understanding the response structure

{
  "data": {
    "id": 18535517,
    "sport_id": 1,
    "league_id": 501,
    "season_id": 19735,
    "stage_id": 77457866,
    "group_id": null,
    "aggregate_id": null,
    "round_id": 274719,
    "state_id": 5,
    "venue_id": 8909,
    "name": "Celtic vs Rangers",
    "starting_at": "2022-09-03 11:30:00",
    "result_info": "Celtic won after full-time.",
    "leg": "1/1",
    "details": null,
    "length": 90,
    "placeholder": false,
    "last_processed_at": "2023-03-02 17:47:38",
    "has_odds": true,
    "starting_at_timestamp": 1662204600
  }
}

Key fields:

Field	Type	Description
id	integer	Unique fixture identifier
league_id	integer	The league this fixture belongs to
season_id	integer	The season this fixture belongs to
state_id	integer	Current match state (see States reference)
name	string	Display name in "Home vs Away" format
starting_at	string	Kickoff datetime in UTC
result_info	string	Plain-text match result summary
has_odds	boolean	Whether odds data is available for this fixture
placeholder	boolean	If true, this is a placeholder fixture (e.g. TBD in a cup draw)
last_processed_at	string	Last time this fixture received a data update

Processing the data

Extract fixture results from a date range:

const data = await api.getFixturesByDateRange('2022-09-01', '2022-09-30');

const results = data.data.map(fixture => ({
  name: fixture.name,
  date: fixture.starting_at,
  result: fixture.result_info || 'Not yet played'
}));

Filter to only completed fixtures:

const completed = data.data.filter(f => f.result_info !== null);
const upcoming = data.data.filter(f => f.result_info === null);

Extract goals and cards from an enriched response:

const fixture = await api.getFixture(18535517, { include: 'events;participants' });

const events = fixture.data.events || [];
const goals = events.filter(e => e.type_id === 14);
const yellowCards = events.filter(e => e.type_id === 83);
const redCards = events.filter(e => e.type_id === 84);

4. Common pitfalls

Pitfall 1: Using livescores for historical or future fixtures

Livescores only cover the 15-minute window around a match. Requesting historical or future fixtures via livescores will return no data.

// ❌ Wrong — livescores won't have this match
const match = await fetch('/v3/football/livescores?api_token=...');

// ✅ Correct — fixtures work at any point in time
const match = await fetch('/v3/football/fixtures/18535517?api_token=...');

Pitfall 2: Including .type on large responses

Including statistics.type on a paginated endpoint like GET All Fixtures triggers a type lookup for every statistic in every fixture. This is extremely expensive.

// ❌ Wrong — slow and will likely hit rate limits
const data = await api.getFixtures({ include: 'statistics.type' });

// ✅ Correct — fetch types once and cache them
const types = await api.getTypes();
const data = await api.getFixtures({ include: 'statistics' });
// Resolve type names locally using your cached types Map

Pitfall 3: Not handling null fields

Many fixture fields are null before the match is played or if data is unavailable.

// ❌ Will throw if result_info is null
const winner = fixture.data.result_info.split(' ')[0];

// ✅ Safe access
const winner = fixture.data.result_info
  ? fixture.data.result_info.split(' ')[0]
  : 'TBD';

---

Pitfall 4: Fetching fixtures separately when includes cover it

A common pattern is to make separate requests for the fixture, then teams, then events. One request with includes handles all of this.

// ❌ Wrong — three requests when one will do
const fixture = await api.getFixture(id);
const scores = await api.getScores(id);
const events = await api.getEvents(id);

// ✅ Correct — one request, all data
const fixture = await api.getFixture(id, {
  include: 'scores;participants;events'
});

Pitfall 5: Using GET All Fixtures to find fixtures by date

GET All Fixtures returns your entire subscription, which can be thousands of records. Always use the appropriate scoped endpoint.

// ❌ Wrong — fetches everything, then filters client-side
const all = await api.getAllFixtures();
const today = all.data.filter(f => f.starting_at.startsWith('2022-09-03'));

// ✅ Correct — only fetches what you need
const today = await api.getFixturesByDate('2022-09-03');

5. Advanced usage

Advanced technique 1: Keeping your database in sync

The GET Latest Updated Fixtures endpoint returns all fixtures updated within the last 10 seconds. Poll this at a sensible interval to keep your local data current without re-fetching everything.

async function syncFixtures() {
  const r = await fetch(
    'https://api.sportmonks.com/v3/football/fixtures/latest?api_token=YOUR_TOKEN'
  );
  const data = await r.json();

  for (const fixture of data.data) {
    await db.upsert('fixtures', fixture);
  }
}

setInterval(syncFixtures, 30000);

Advanced technique 2: Head-to-head combined with statistics

For a pre-match analysis page, combine the H2H endpoint with statistics includes to show not just results but how each team performed in previous meetings.

async function getH2HAnalysis(teamA, teamB) {
  const h2h = await api.getHeadToHead(teamA, teamB, {
    include: 'scores;participants;statistics.type;events'
  });

  return h2h.data.map(fixture => ({
    name: fixture.name,
    date: fixture.starting_at,
    result: fixture.result_info,
    goals: fixture.events?.filter(e => e.type_id === 14) || [],
    stats: fixture.statistics || []
  }));
}

Advanced technique 3: Parallel requests for a match-day dashboard

When building a dashboard that shows multiple data types at once, use Promise.all to fetch in parallel rather than in sequence.

async function getMatchDayDashboard(fixtureId) {
  const [fixture, standings, h2h] = await Promise.all([
    api.getFixture(fixtureId, { include: 'scores;events;lineups;participants' }),
    api.getStandingsByLeague(501),
    api.getHeadToHead(53, 62)
  ]);

  return { fixture: fixture.data, standings: standings.data, h2h: h2h.data };
}

6. Common errors

401 Unauthorised

{ "message": "Unauthenticated." }

Cause: Missing or invalid api_token. Fix: Check the token is correct and appended to every request. Retrieve it from MySportmonks.

404 Not Found

{ "message": "No query results for model..." }

Cause: The fixture ID does not exist, or the fixture belongs to a league outside your subscription. Fix: Verify the ID via the ID Finder and confirm the league is in your plan.

429 Too Many Requests

{ "message": "Too many requests." }

Cause: Exceeded your plan's hourly call limit. Fix: Implement exponential backoff and cache reference data to reduce call volume. See the Rate Limiting guide.

CORS error (browser only)

Access to fetch has been blocked by CORS policy

Cause: Calling the API directly from the browser exposes your token. Fix: Proxy requests through your own backend.

// ✅ Backend proxy (Express example)
app.get('/api/fixtures/:id', async (req, res) => {
  const r = await fetch(
    `https://api.sportmonks.com/v3/football/fixtures/${req.params.id}?api_token=${process.env.SPORTMONKS_TOKEN}`
  );
  res.json(await r.json());
});

See also

Prerequisites

• Authentication : How to authenticate requests

• Includes : How to attach related data

• Filter and Select Fields : How to narrow responses

Real-time match data

• Livescores : Lightweight real-time updates for active matches

• States : Understanding fixture states and when to poll

Working with fixture data

• Statistics : Match and player stats accessible via fixture includes

• Lineups and Formations : Starting XI data attached via the lineups include

• Season Schedule : Organise fixtures by round and stage

• Standings : Combine with fixture filters to build league tables in context

Optimisation

• Filter and Select Fields : Optimise responses by selecting specific data

• Rate Limiting : Best practices for frequent fixture requests

• Best Practices : Build efficient applications

Related endpoints

• Fixtures Endpoints : Complete API endpoint reference

• Livescores Endpoints : Real-time data endpoints

FAQ

Q: What's the difference between fixtures and livescores?

Fixtures give you complete match data at any time (past, present, or future). Livescores are optimised for real-time polling during active matches and only return data in a 15-minute window before kickoff, when the match is inplay and until 15 minutes after the match has concluded. The response structure is identical; the difference is scope and timing.

Q: How do I find a fixture ID if I don't already have it?

Use the GET Fixture by Search endpoint with a team name, or use the ID Finder tool in MySportmonks.

Q: Can I request fixtures for leagues outside my subscription?

No. The fixtures endpoints only return data for leagues included in your active plan. If a specific league is missing, check your subscription or consider upgrading.

Q: How do I know if a fixture has been updated recently?

Check the last_processed_at field on any fixture object. You can also use the GET Latest Updated Fixtures endpoint to retrieve all fixtures updated in the last 10 seconds.

Q: How often is fixture data updated?

Fixtures are updated in near real-time during live matches. Scores, events, and lineups are typically processed within seconds of an in-game event occurring.

Q: What does placeholder: true mean?

Placeholder fixtures represent matches where the participants are not yet determined, common in knockout tournament draws. Real team data is populated once the bracket is confirmed.

Best practices summary

✅ DO:

• Use the most specific endpoint for your use case (by date, by team, by ID)

• Fetch types once from the Types endpoint and cache them locally

• Use includes to combine related data into a single request

• Proxy API calls through your backend to protect your token

• Use GET Latest Updated Fixtures for incremental database sync

❌ DON'T:

• Use livescores for historical or future fixture data

• Include .type on large paginated requests

• Call GET All Fixtures when a scoped endpoint is available

• Expose your API token in frontend code

• Make separate requests for data that includes can provide in one call