Migrating to v2

Same power. Cleaner design. More endpoints.

⚠️ v1 sunsets 01 January 2027

If you built your integration on v1, this guide is everything you need to move to v2. Same authentication. Same pricing. Better data.

What changes

	v1	v2
Coverage	1,234 leagues	300+ leagues (growing daily)
League IDs	`39`, `140`	`"en.1"`, `"es.1"`
Response envelope	`response` / `results`	`data` / `count`
Pagination	`paging.current`	`page` / `totalPages`
Images	Proxy pass-through	WebP, responsive sizing, cached
New endpoints	—	Odds, Transfers, Injuries, H2H, Top Scorers
Status	Deprecated	Active

Step 1 — League IDs

Integer IDs (39) become string codes ("en.1").

v1 ID	v2 Code	Competition
39	`en.1`	Premier League
140	`es.1`	La Liga
78	`de.1`	Bundesliga
135	`it.1`	Serie A
61	`fr.1`	Ligue 1
88	`nl.1`	Eredivisie
—	`GET /api/v2/leagues`	Full catalog

Step 2 — Endpoint paths

# Before (v1)
GET  /api/v1/fixtures?league=39&season=2024
GET  /api/v1/fixtures/1234567
GET  /api/v1/standings?league=39&season=2024
GET  /api/v1/teams?league=39&season=2024
GET  /api/v1/players?league=39&season=2024
GET  /api/v1/predictions?fixture=1234567

# After (v2)
GET  /api/v2/fixtures?league=en.1&season=2024
GET  /api/v2/fixtures/fx_a1b2c3d4
GET  /api/v2/standings?league=en.1&season=2024
GET  /api/v2/teams?league=en.1
GET  /api/v2/players?team=t_arsenal
GET  /api/v2/insights?fixture=fx_a1b2c3d4

# New endpoints (v2 only)
GET  /api/v2/odds?league=en.1
GET  /api/v2/transfers?league=en.1
GET  /api/v2/injuries?league=en.1
GET  /api/v2/topscorers?league=en.1&season=2024
GET  /api/v2/topassists?league=en.1&season=2024
GET  /api/v2/headtohead?team1=t_arsenal&team2=t_chelsea

Step 3 — Response format

// v1 response
{ "response": [ ... ],
  "results": 10,
  "paging": { "current": 1, "total": 1 } }

// v2 response
{ "data": [ ... ],
  "count": 10,
  "page": 1,
  "totalPages": 1 }

Fixture object shape

// v1 fixture
{ "fixture": { "id": 1234567 },
  "teams": {
    "home": { "id": 40, "name": "Liverpool" },
    "away": { "id": 33, "name": "Man United" }
  },
  "goals": { "home": 2, "away": 1 },
  "league": { "id": 39, "name": "Premier League" } }

// v2 fixture
{ "id": "fx_a1b2c3d4",
  "homeTeam": { "id": "t_liverpool", "name": "Liverpool", "logo": "https://..." },
  "awayTeam": { "id": "t_manchester-united", "name": "Manchester United", "logo": "https://..." },
  "homeScore": 2,
  "awayScore": 1,
  "league": { "id": "en.1", "name": "Premier League", "logo": "https://..." },
  "date": "2024-08-15T19:00:00Z",
  "status": "finished" }

Step 4 — Images

All team, player, and league images are served as WebP and respond to sizing parameters:

https://api.kickoffapi.com/images/team/en.1/arsenal?size=256&format=png
                                                   ───┬───  ───┬───
                                               size: 32|64|128|256|512    format: webp(default)|png

Pro tip: Wrap league IDs in your code once, then reuse everywhere.

const LEAGUE_IDS = {
  premier_league: 'en.1',
  la_liga:       'es.1',
  bundesliga:    'de.1',
  serie_a:       'it.1',
  ligue_1:       'fr.1',
} as const;

Migración checklist

Replace v1 → v2 in all paths
Replace integer league IDs with string codes
Parse data instead of response, count instead of results
Update fixture shape: teams.home.name → homeTeam.name, etc.
Test with one league first (en.1)
Monitor responses — contact support if you see gaps in leagues you need
Add the new endpoints (odds, transfers, H2H) to your app