Migrating from API-Football to SportMonks

Overview

API-Football and SportMonks are two of the most popular football data APIs, but they take different design philosophies. API-Football bundles many sports under one umbrella with simple per-sport endpoints, while SportMonks is football-first with deeper enrichment, nested includes, and a more flexible filtering system. Migrating between them is rarely a drop-in replacement.

Teams typically move to SportMonks for richer in-play data, custom plan flexibility, and superior league coverage, or away from API-Football when they hit the rate limits of the RapidAPI-hosted version. This guide maps every common endpoint, highlights the data-shape differences that break parsers, and gives you a checklist you can run end-to-end before cutting over traffic.

Why Migrate?

Migration is a significant investment, so the trade-offs need to be worth it. The most common reasons teams switch from API-Football to SportMonks are:

• Deeper football data — SportMonks offers player-level XG, expected goals against, lineup projections, and referee statistics that API-Football does not expose.
• Flexible nested includes — a single request can return fixtures, league, season, score, events, and lineups, reducing request count and orchestration code.
• Custom plan negotiation — SportMonks offers tailored plans for high-volume customers, while API-Football is priced per fixed tier.
• More consistent naming — SportMonks uses stable team and league IDs, avoiding the alias drift that API-Football occasionally introduces.

On the other hand, API-Football wins on breadth (it covers basketball, baseball, hockey, and more in one API) and on a generous free tier. If your product is multi-sport, a full migration may not be the right call — consider keeping API-Football for non-football sports.

Endpoint Mapping

SportMonks uses a flat resource model under /v3/football, while API-Football groups everything under /v3 with sport-specific paths. The table below maps the most common endpoints:

Data Format Differences

The response shapes differ substantially. API-Football wraps every response in { get, parameters, errors, results, paging, response }, while SportMonks returns { data, ... } with meta in the response headers. The biggest parser-breaking changes are:

• Score structure — API-Football nests scores under fixture.goals; SportMonks splits them into scores.home and scores.away with separate full-time and half-time objects.
• Status objects — API-Football uses fixture.status.short ("1H", "FT", "NS"); SportMonks uses state.name with longer labels.
• Team IDs — the same physical team will have a different ID in each provider. You must maintain an ID mapping table during migration.
• Includes vs separate calls — data that required three API-Football calls (fixture, events, lineups) can be fetched in one SportMonks call using ?include=events;lineups.

Before & After: API Calls

Fetching a fixture with lineups (API-Football)

On API-Football you fetch the fixture and the lineups in two separate requests and join them client-side:

// API-Football — two requests, manual join
const API_KEY = process.env.APIFOOTBALL_KEY;
const base = "https://v3.football.api-sports.io";

// 1. Fetch the fixture
const fixtureRes = await fetch(`${base}/fixtures?id=215662`, {
  headers: { "x-apisports-key": API_KEY },
});
const fixtureJson = await fixtureRes.json();
const fixture = fixtureJson.response[0];

// 2. Fetch the lineups separately
const lineupRes = await fetch(`${base}/fixtures/lineups?fixture=215662`, {
  headers: { "x-apisports-key": API_KEY },
});
const lineupJson = await lineupRes.json();
const lineups = lineupJson.response;

// 3. Merge by fixture id
const merged = { ...fixture, lineups };

Fetching a fixture with lineups (SportMonks)

On SportMonks the same data is one request thanks to the include parameter, and the response is flatter:

// SportMonks — one request, nested includes
const API_KEY = process.env.SPORTMONKS_KEY;
const base = "https://api.sportmonks.com/v3/football";

// Single request returns fixture + events + lineups
const res = await fetch(
  `${base}/fixtures/215662?include=events;lineups`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);
const { data } = await res.json();

// data already contains events and lineups inline
const merged = data;

Pricing Comparison

Pricing models are not directly comparable because SportMonks gates leagues behind plan tiers while API-Football offers all leagues on every paid plan. Estimate your cost for the specific leagues you need:

Migration Checklist

Best Practices

Related Guides