v1 API v2 API

KickoffAPI v2, documented.

Native football data API with KickoffAPI's own stable identifiers (lg_..., tm_..., fx_..., pl_...), unified { data, meta } response envelopes, Dixon-Coles match projections, xG models, AI previews, and cursor pagination.

BASE URLhttps://api.kickoffapi.com

01Quickstart

Grab a free key, then your first call is one line. Fetch native v2 fixtures with cursor pagination:

TERMINAL

$ curl -G "https://api.kickoffapi.com/api/v2/fixtures" \
    -d "limit=10" \
    -H "x-api-key: YOUR_KEY"

# 200 OK · Unified Envelope
{
  "data": [
    {
      "id": "fx_99Xy",
      "date": "2026-06-27T16:30:00.000Z",
      "status": { "long": "Match Finished", "short": "FT", "elapsed": 90 },
      "league": { "id": "lg_8K3mZ0pQ", "name": "Premier League", "season": 2026 },
      "home": { "id": "tm_a1B2c3", "name": "Arsenal", "logo": "..." },
      "away": { "id": "tm_d4E5f6", "name": "Chelsea", "logo": "..." },
      "score": { "home": 2, "away": 1, "halftime": { "home": 1, "away": 0 } }
    }
  ],
  "meta": { "count": 10, "cursor": 0, "nextCursor": "10" }
}

02Authentication

Every request requires your API key in the x-api-key HTTP header. API keys map to your subscription tier and daily quota allowance.

REQUEST HEADER

x-api-key: ko_live_7f3a…e91c4b20d8

03Rate Limits & Errors

Rate limits are returned in HTTP headers on every response. Status codes indicate success or error state:

Header	Meaning
X-RateLimit-Limit	Your daily request limit
X-RateLimit-Remaining	Requests remaining today
X-RateLimit-Reset	Unix timestamp when daily limit resets
X-Request-Id	Unique request ID for tracing

Status	Meaning	Action
200	OK	Success
400	Bad Request	Check query parameter requirements
401	Unauthorized	Missing or invalid x-api-key header
404	Not Found	Resource or native ID not found
429	Rate Limited	Daily limit exceeded; back off until reset
500	Server Error	Internal error; retry with backoff

04Endpoint Reference

All endpoints return a standardized envelope: { data, meta }. Native IDs use prefixes: lg_ (leagues), tm_ (teams), fx_ (fixtures), pl_ (players), vn_ (venues).

GET /api/v2/resolve

Translate Single Entity ID

Translates legacy API-Football integer IDs to KickoffAPI native string IDs (koId).

Parameter	Type	Required	Description
entity	string	Yes	`league` \| `team` \| `fixture` \| `player`
legacyId	integer	Yes	Legacy integer ID (e.g., 42 for Arsenal)

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": { "entity": "team", "legacyId": 42, "id": "tm_a1B2c3" },
  "meta": {}
}

GET /api/v2/idmap/leagues

Bulk League ID Mapping

Returns a complete mapping table translating legacy integer league IDs to native KickoffAPI IDs (lg_...).

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": [
    { "legacyId": 39, "id": "lg_8K3mZ0pQ", "name": "Premier League" },
    { "legacyId": 140, "id": "lg_9X2nY1rT", "name": "La Liga" }
  ],
  "meta": { "count": 2 }
}

GET /api/v2/countries

List Countries

Retrieve all supported countries with ISO country codes and flag icons.

Parameter	Type	Required	Description
limit	integer	No	Results per page (default: 50, max: 200)
cursor	integer	No	Pagination offset (default: 0)

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": [
    { "id": "cnt_1", "name": "England", "code": "GB", "flag": "https://cdn.kickoffapi.com/images/flags/gb.svg" }
  ],
  "meta": { "count": 1, "cursor": 0, "nextCursor": null }
}

GET /api/v2/leagues

List Leagues

Retrieve football leagues and cup competitions filtered by country.

Parameter	Type	Required	Description
country	string	No	Filter by country name (e.g. England)
limit	integer	No	Results per page (default 50)
cursor	integer	No	Pagination offset

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": [
    { "id": "lg_8K3mZ0pQ", "name": "Premier League", "type": "League", "country": "England", "logo": "https://cdn.kickoffapi.com/images/leagues/39.png" }
  ],
  "meta": { "count": 1, "cursor": 0, "nextCursor": null }
}

GET /api/v2/teams

List Teams

Fetch team profiles and club logos by country.

Parameter	Type	Required	Description
country	string	No	Filter by country name
limit	integer	No	Results per page
cursor	integer	No	Pagination offset

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": [
    { "id": "tm_a1B2c3", "name": "Arsenal", "country": "England", "logo": "https://cdn.kickoffapi.com/images/teams/42.png" }
  ],
  "meta": { "count": 1, "cursor": 0, "nextCursor": null }
}

GET /api/v2/players

List Players

Fetch player profiles with native string identifiers (pl_...).

Parameter	Type	Required	Description
limit	integer	No	Results per page
cursor	integer	No	Pagination offset

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": [
    { "id": "pl_x9Y8z7", "name": "Bukayo Saka", "firstname": "Bukayo", "lastname": "Saka", "nationality": "England" }
  ],
  "meta": { "count": 1, "cursor": 0, "nextCursor": "50" }
}

GET /api/v2/teams/:id/squad

Team Squads (Wikidata CC0 Roster)

Fetch self-owned CC0 Wikidata squad rosters for a team by native ID.

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": [
    { "id": "pl_saka", "name": "Bukayo Saka", "position": "Attacker" },
    { "id": "pl_rice", "name": "Declan Rice", "position": "Midfielder" }
  ],
  "meta": { "team": "tm_a1B2c3", "name": "Arsenal", "count": 2, "source": "wikidata-cc0" }
}

GET /api/v2/venues

Venues

Retrieve football stadiums, locations, capacities, and venue images.

Parameter	Type	Required	Description
search	string	No	Search venue by name (case-insensitive)
limit	integer	No	Results per page
cursor	integer	No	Pagination offset

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": [
    { "id": "vn_77K2p", "name": "Emirates Stadium", "city": "London", "capacity": 60704, "image": "https://cdn.kickoffapi.com/images/venues/494.png" }
  ],
  "meta": { "count": 1, "cursor": 0, "nextCursor": null }
}

GET /api/v2/fixtures

Fixtures & Live Scores

Query upcoming schedules, live scores, and historical match results using native IDs.

Parameter	Type	Required	Description
league	string	No	Native league ID (e.g., `lg_8K3mZ0pQ`)
season	integer	No	Season year (e.g. 2026)
date	date	No	Filter by date (YYYY-MM-DD)
team	string	No	Native team ID (e.g., `tm_a1B2c3`)
from / to	date	No	Date range filtering (YYYY-MM-DD)
limit	integer	No	Results per page (default: 50)
cursor	integer	No	Pagination offset

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": [
    {
      "id": "fx_99Xy",
      "date": "2026-06-27T16:30:00.000Z",
      "status": { "long": "Match Finished", "short": "FT", "elapsed": 90 },
      "league": { "id": "lg_8K3mZ0pQ", "name": "Premier League", "season": 2026 },
      "home": { "id": "tm_a1B2c3", "name": "Arsenal", "logo": "..." },
      "away": { "id": "tm_d4E5f6", "name": "Chelsea", "logo": "..." },
      "score": { "home": 2, "away": 1, "halftime": { "home": 1, "away": 0 } }
    }
  ],
  "meta": { "count": 1, "cursor": 0, "nextCursor": null }
}

GET /api/v2/fixtures/:id

Single Fixture Detail

Retrieve full fixture object with embedded stored AI preview & recap text.

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": {
    "id": "fx_99Xy",
    "date": "2026-06-27T16:30:00.000Z",
    "status": { "long": "Match Finished", "short": "FT", "elapsed": 90 },
    "league": { "id": "lg_8K3mZ0pQ", "name": "Premier League", "season": 2026 },
    "home": { "id": "tm_a1B2c3", "name": "Arsenal", "logo": "..." },
    "away": { "id": "tm_d4E5f6", "name": "Chelsea", "logo": "..." },
    "score": { "home": 2, "away": 1, "halftime": { "home": 1, "away": 0 } },
    "content": { "preview": "Arsenal host Chelsea in a pivotal...", "recap": "Arsenal claimed a 2-1 victory..." }
  },
  "meta": { "content": { "preview": "ollama/llama3", "recap": "ollama/llama3" }, "source": "kickoffapi-derived (grounded)" }
}

GET /api/v2/fixtures/:id/events

Fixture Events

Minute-by-minute events (goals, cards, substitutions) for a specific match.

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": [
    { "time": { "elapsed": 34, "extra": null }, "team": { "id": "tm_a1B2c3", "name": "Arsenal" }, "player": { "id": "pl_saka", "name": "B. Saka" }, "type": "Goal", "detail": "Normal Goal" }
  ],
  "meta": { "count": 1, "cursor": 0, "nextCursor": null }
}

GET /api/v2/fixtures/:id/lineups

Fixture Lineups

Starting XI, tactical formation, substitutes, and head coach for a match.

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": [
    { "team": { "id": "tm_a1B2c3", "name": "Arsenal" }, "formation": "4-3-3", "startXI": [ ... ], "substitutes": [ ... ] }
  ],
  "meta": { "count": 1, "cursor": 0, "nextCursor": null }
}

GET /api/v2/fixtures/:id/statistics

Fixture Team Statistics

Match statistics (shots on goal, possession %, passes, fouls, corners, offsides) for both teams.

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": [
    { "team": { "id": "tm_a1B2c3", "name": "Arsenal" }, "statistics": [ { "type": "Ball Possession", "value": "58%" } ] }
  ],
  "meta": { "count": 1, "cursor": 0, "nextCursor": null }
}

GET /api/v2/fixtures/:id/players

Fixture Player Statistics

Individual player statistics and ratings for a single match.

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": [
    { "player": { "id": "pl_saka", "name": "B. Saka" }, "rating": "8.2", "goals": 1, "assists": 1 }
  ],
  "meta": { "count": 1, "cursor": 0, "nextCursor": null }
}

GET /api/v2/headtohead

Head-to-Head (H2H)

Historical match records between two specific teams using native team IDs.

Parameter	Type	Required	Description
h2h	string	Yes*	Format: `tm_1-tm_2` (e.g. `tm_a1B2c3-tm_d4E5f6`)
team1 / team2	string	Yes*	Alternative: separate `team1` and `team2` parameters

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": [ { "id": "fx_99Xy", "date": "2026-06-27T16:30:00Z", "score": { "home": 2, "away": 1 } } ],
  "meta": { "count": 1, "cursor": 0, "nextCursor": null }
}

GET /api/v2/fixtures/:id/projection

Match Projections (Dixon-Coles v2)

In-house Dixon-Coles time-weighted match outcome probability projection model.

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": {
    "fixture": "fx_99Xy",
    "homeWin": 0.54,
    "draw": 0.26,
    "awayWin": 0.20,
    "expectedGoals": { "home": 1.75, "away": 1.05 }
  },
  "meta": { "model": "dixon-coles-v2", "source": "kickoffapi-derived" }
}

GET /api/v2/teams/:id/form

Team Form

Recent match form, streak sequence, goals scored/conceded, and clean sheets over last N matches.

Parameter	Type	Required	Description
season	integer	Yes	Season year (e.g. 2026)
n	integer	No	Number of recent matches (default: 5, max: 20)

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": {
    "team": "tm_a1B2c3",
    "name": "Arsenal",
    "season": 2026,
    "matches": 5,
    "points": 13,
    "sequence": "WWWDW",
    "goalsScored": 12,
    "goalsConceded": 3,
    "cleanSheets": 3
  },
  "meta": { "source": "kickoffapi-derived" }
}

GET /api/v2/insights/strength

League Attack & Defense Strength

Poisson strength parameters (attack and defense ratings) for all teams in a league season.

Parameter	Type	Required	Description
league	string	Yes	Native league ID (e.g. `lg_8K3mZ0pQ`)
season	integer	Yes	Season year

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": [
    { "team": { "id": "tm_a1B2c3", "name": "Arsenal" }, "attack": 1.45, "defense": 0.65 }
  ],
  "meta": { "league": "lg_8K3mZ0pQ", "season": 2026, "model": "poisson-strength" }
}

GET /api/v2/insights/season-sim

Monte Carlo Season Simulation

Simulate remaining season matches using Dixon-Coles Monte Carlo engine to project final standing ranks and points distributions.

Parameter	Type	Required	Description
league	string	Yes	Native league ID (e.g. `lg_8K3mZ0pQ`)
season	integer	Yes	Season year
sims	integer	No	Number of simulations (default: 1000)

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": [
    { "team": { "id": "tm_a1B2c3", "name": "Arsenal" }, "titleProb": 0.48, "top4Prob": 0.95, "projectedPoints": 87.4 }
  ],
  "meta": { "model": "dixon-coles-v2 monte-carlo", "source": "kickoffapi-derived" }
}

GET /api/v2/fixtures/:id/preview

AI Match Previews

Generate or retrieve grounded AI match preview analysis generated by KickoffAPI's local Ollama content engine.

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": {
    "id": "fx_99Xy",
    "preview": "Arsenal host Chelsea at Emirates Stadium in a critical London derby..."
  },
  "meta": { "model": "ollama/llama3", "cached": true, "source": "kickoffapi-derived (grounded)" }
}

GET /api/v2/fixtures/:id/content

Stored Match Content (Preview & Recap)

Pure database read endpoint returning pre-generated match previews and post-match recaps without triggering LLM latency.

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": {
    "id": "fx_99Xy",
    "preview": "Arsenal host Chelsea in a high-stakes fixture...",
    "recap": "Arsenal earned three points with a dramatic 2-1 victory..."
  },
  "meta": { "models": { "preview": "ollama/llama3", "recap": "ollama/llama3" }, "source": "kickoffapi-derived (grounded)" }
}

GET /api/v2/xg/model

xG Model Metadata

Retrieve information about KickoffAPI's in-house Expected Goals (xG) model, frame coordinates (StatsBomb 120x80), and features.

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": {
    "name": "KickoffAPI Shot-xG v1",
    "pitchFrame": "StatsBomb 120x80 (goal at x=120, y=40)",
    "features": ["distance", "angle", "bodyPart", "situation"]
  },
  "meta": { "note": "KickoffAPI-owned xG model." }
}

GET / POST /api/v2/xg

Calculate Shot xG

Calculate Expected Goal value for a single shot via GET parameters or a batch array of shots via POST JSON payload.

Parameter	Type	Required	Description
x	number	Yes	Shot X coordinate (0-120; goal line at 120)
y	number	Yes	Shot Y coordinate (0-80; center goal at 40)
bodyPart	string	No	`foot` \| `header` \| `other`
situation	string	No	`open_play` \| `free_kick` \| `penalty` \| `corner`

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": {
    "xg": 0.38,
    "distance": 12.0,
    "angleDegrees": 32.5,
    "inputs": { "x": 108, "y": 40, "bodyPart": "foot", "situation": "open_play" }
  },
  "meta": { "source": "kickoffapi-derived" }
}

GET /api/v2/standings

League Standings

Fetch league standings table for a specific league and season year.

Parameter	Type	Required	Description
league	string	Yes	Native league ID (e.g. `lg_8K3mZ0pQ`)
season	integer	Yes	Season year (e.g. 2026)

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": [
    { "rank": 1, "team": { "id": "tm_a1B2c3", "name": "Arsenal", "logo": "..." }, "points": 86, "goalsDiff": 45, "played": 38, "win": 27, "draw": 5, "lose": 6, "form": "WWWDW" }
  ],
  "meta": { "league": "lg_8K3mZ0pQ", "season": 2026, "count": 1 }
}

GET /api/v2/topscorers

Top Scorers

Retrieve leading goal scorers in a league season.

Parameter	Type	Required	Description
league	string	Yes	Native league ID
season	integer	Yes	Season year

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": [
    { "rank": 1, "player": { "id": "pl_haaland", "name": "Erling Haaland" }, "team": { "id": "tm_manc", "name": "Man City" }, "goals": 28 }
  ],
  "meta": { "count": 1, "cursor": 0, "nextCursor": null }
}

GET /api/v2/topassists

Top Assists

Retrieve assist leaders in a league season.

Parameter	Type	Required	Description
league	string	Yes	Native league ID
season	integer	Yes	Season year

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": [
    { "rank": 1, "player": { "id": "pl_saka", "name": "Bukayo Saka" }, "team": { "id": "tm_a1B2c3", "name": "Arsenal" }, "assists": 14 }
  ],
  "meta": { "count": 1, "cursor": 0, "nextCursor": null }
}

GET /api/v2/odds

Pre-Match Odds

Retrieve pre-match betting odds across bookmakers and betting markets.

Parameter	Type	Required	Description
fixture	string	Yes	Native fixture ID (e.g. `fx_99Xy`)
bookmaker	integer	No	Filter by bookmaker ID
bet	integer	No	Filter by bet type ID

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": [
    { "id": "odd_1", "bookmaker": { "id": 8, "name": "Bet365" }, "betType": { "id": 1, "name": "Match Winner" }, "values": [ { "value": "Home", "odd": "1.85" } ] }
  ],
  "meta": { "count": 1, "cursor": 0, "nextCursor": null }
}

GET /api/v2/odds/live

Live In-Play Odds

Retrieve live in-play betting odds for active matches.

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": [ { "id": "odd_live_1", "bookmaker": { "id": 8, "name": "Bet365" }, "values": [ { "value": "Home", "odd": "2.10" } ] } ],
  "meta": { "count": 1, "cursor": 0, "nextCursor": "50" }
}

GET /api/v2/bookmakers

Reference: Bookmakers

List of supported sports betting bookmakers and logos.

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": [
    { "id": 8, "name": "Bet365", "image": "https://cdn.kickoffapi.com/images/bookmakers/8.png" }
  ],
  "meta": { "count": 1, "cursor": 0, "nextCursor": null }
}

GET /api/v2/bet-types

Reference: Bet Types

List of supported betting market categories (Match Winner, Over/Under, Both Teams to Score, etc.).

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": [
    { "id": 1, "name": "Match Winner" },
    { "id": 5, "name": "Goals Over/Under" }
  ],
  "meta": { "count": 2, "cursor": 0, "nextCursor": null }
}

GET /api/v2/transfers

Player Transfers

Historical and active player transfers between teams.

Parameter	Type	Required	Description
player	string	No	Native player ID
team	string	No	Native team ID
limit	integer	No	Results per page
cursor	integer	No	Pagination offset

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": [ { "id": "tr_1", "date": "2026-07-01", "type": "Transfer", "player": { "id": "pl_rice" } } ],
  "meta": { "count": 1, "cursor": 0, "nextCursor": null }
}

GET /api/v2/injuries

Injuries & Sidelined Players

Player injury and suspension records per match or team.

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": [ { "id": "inj_1", "reason": "Hamstring Injury", "player": { "id": "pl_x" } } ],
  "meta": { "count": 1, "cursor": 0, "nextCursor": null }
}

GET /api/v2/coaches

Coaches

Head coach profile details and team career history.

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": [ { "id": "ch_arteta", "name": "Mikel Arteta", "nationality": "Spain" } ],
  "meta": { "count": 1, "cursor": 0, "nextCursor": null }
}

GET /api/v2/trophies

Player Trophies

Player trophy awards and career silverware achievements.

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": [ { "id": "tr_1", "league": "Premier League", "season": "2023/2024", "place": "Winner" } ],
  "meta": { "count": 1, "cursor": 0, "nextCursor": null }
}

GET /api/v2/account/status

Account Status & Quota

Query your current API key subscription tier and daily/monthly request usage counts.

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "data": {
    "account": { "id": "usr_102", "plan": "pro" },
    "usage": {
      "daily": { "used": 1420, "limit": 100000 },
      "monthly": { "used": 18450, "limit": 3000000 }
    }
  },
  "meta": { "source": "kickoffapi-auth" }
}