Switch from football‑data.org to KickoffAPI
A call-for-call migration map: the API v4 routes you are most likely using on football-data.org, the KickoffAPI call that answers the same need, and an honest section on what does not line up one-to-one — head-to-head first among them.
Endpoints side by side
| Need | football-data.org (API v4) | KickoffAPI |
|---|---|---|
| Fixtures by league + season | GET /v4/competitions/{id}/matches?season={YEAR} (plus dateFrom, dateTo, stage, status, matchday, group) |
GET /api/v2/fixtures?league={lg_… or int}&season={YYYY} |
| Fixtures by date | GET /v4/matches?dateFrom={DATE}&dateTo={DATE} (a single date filter exists too; no filter = today's matches) |
GET /api/v2/fixtures?date=YYYY-MM-DD (range: from + to) |
| Standings | GET /v4/competitions/{id}/standings?season={YEAR} (filters: matchday, season, date) |
GET /api/v2/standings?league=…&season=… (both required) |
| Teams | GET /v4/competitions/{id}/teams?season={YEAR} · single team GET /v4/teams/{id} · list GET /v4/teams/ |
GET /api/v1/teams?league=…&season=… (v1 — v2's /api/v2/teams filters by country only) |
| Head-to-head | GET /v4/matches/{matchId}/head2head?limit={LIMIT} — needs an existing match id; returns aggregates plus the matches list |
GET /api/v2/headtohead?h2h={tm_1-tm_2} (or team1 + team2) — two team ids, no match id required |
| One fixture | GET /v4/matches/{id} — flat match object with an embedded head2head block |
GET /api/v2/fixtures/{fx_… or int} — { data, meta } with status: { long, short, elapsed } |
| Authentication | header X-Auth-Token: YOUR_ACCESS_TOKEN |
header x-api-key |
Their column was read from football-data.org's quickstart and API reference (fetched 1 October 2026); ours from KickoffAPI's published OpenAPI specs and v2 reference. Product names are trademarks of their respective owners.
curl -H "X-Auth-Token: YOUR_ACCESS_TOKEN" \ "https://api.football-data.org/v4/competitions/PL/matches?season=2025"
curl -G "https://api.kickoffapi.com/api/v2/fixtures" \ -d "league=39&season=2025&limit=25" \ -H "x-api-key: YOUR_KEY"
What is different
Envelope, ids, statuses, paging
Envelope. Their single-match response is a flat object — id, utcDate, status, homeTeam, awayTeam, score.fullTime.home/away — with head2head embedded on the single-match route. Ours is one envelope on every endpoint: { data, meta }, with score: { home, away, halftime } on the fixture row and the cursor always in meta.
Ids. Their ids are plain numbers (a match is 327117). Ours are prefixed — fx_, lg_, tm_. For legacy integer ids, GET /api/v2/resolve?entity=&legacyId= and GET /api/v2/idmap/leagues translate them.
Status. Their status is a single enum — SCHEDULED | LIVE | IN_PLAY | PAUSED | FINISHED | POSTPONED | SUSPENDED | CANCELLED. Ours is an object: status: { long, short, elapsed }, so "Match Finished" / "FT" come back together.
Season format. Their season filter takes the starting year (season=2017 means 2017-18). Ours takes season=YYYY as the season label used across our catalogue — check the value you send, not just the parameter name.
Where the two do not match up
Head-to-head. This is the real difference: their H2H route hangs off a match id (/v4/matches/{id}/head2head), and their documentation shows no two-team-id route. Ours takes two team ids straight away: /api/v2/headtohead?h2h={tm_1-tm_2}.
Teams. Theirs lists teams of a competition + season; ours lists teams of a league + season, and that call lives on v1 (/api/v1/teams) because our v2 teams endpoint filters by country only. This page shows the v1 path on purpose rather than pretending v2 covers it.
Rate limits and errors. Their docs state 10 requests/minute on the free plan (30/min Standard, 60/min above) and HTTP 400 / 403 (paid-only resources) / 404 / 429. Ours return rate-limit headers on every authenticated call rather than only after you hit 429.
What this page does not claim. It maps calls, nothing else. We have not benchmarked football-data.org for coverage, latency or uptime, and nothing here should be read as a reliability claim about them — judge that from your own traffic.
Sources: football-data.org quickstart (v4 endpoint table and filters) and API reference (auth header, rate limits, response examples); KickoffAPI's own reference. Retrieved 1 October 2026. Anything their documentation did not answer is left out rather than guessed.
Get on the wire
One header, one envelope, every league on the free tier. Your key takes 30 seconds.