The wire, documented.

Live and historical football data for your applications. One REST API, predictable JSON, clear rate-limit headers — and a sandbox on every endpoint.

BASE URLhttps://api.kickoffapi.com

01Quickstart

Grab a free key, then your first call is one line. Live fixtures, right now, in JSON:

TERMINAL

$ curl -G "https://api.kickoffapi.com/api/v1/fixtures" \
    -d "live=all" \
    -H "x-api-key: YOUR_KEY"

# 200 OK · 24ms
{ "get": "fixtures", "results": 142, "response": [ … ] }

02Authentication

Every request needs your API key in the x-api-key header. Keys map to your plan and its limits — keep them server-side, never in client code, and rotate them anytime from your dashboard.

REQUEST HEADER

x-api-key: ko_live_7f3a…e91c4b20d8

03Rate limits & errors

Limits are enforced per minute and per day, by plan. Every response tells you where you stand:

Header	Meaning
X-RateLimit-Limit	Your daily request allowance
X-RateLimit-Remaining	Requests left today
X-RateLimit-Reset	Unix time the counter resets
X-Request-Id	Attach this when contacting support

Status	Meaning	What to do
401	Missing or invalid key	Check the x-api-key header
403	Endpoint not on your plan	Upgrade, or check plan features
429	Rate limit exceeded	Back off; retry after reset. Overage billing keeps daily limits soft on paid plans
500	Server error	Retry with backoff; include X-Request-Id in reports

04Endpoint reference

All endpoints are GET, return the same envelope (get · results · response[]), and respect your plan's limits. Paste your key above and hit TRY IT to copy a ready-made curl.

GET /api/v1/countries

Countries

Returns a list of all supported countries, their ISO codes, and flag image URLs.

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "get": "countries",
  "results": 171,
  "response": [
    {
      "name": "England",
      "code": "GB",
      "flag": "https://media.api-sports.io/flags/gb.svg"
    }
  ]
}

GET /api/v1/leagues

Leagues

Get available leagues and cups. Includes league type and seasons coverage.

QUERY PARAMETERS

Param	Type	Description
country OPTIONAL	string	Filter by country name (e.g., "England")
current OPTIONAL	boolean	Set to "true" to only return active leagues
type OPTIONAL	string	Filter by type: "League" or "Cup"

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "get": "leagues",
  "results": 1,
  "response": [
    {
      "id": 39,
      "name": "Premier League",
      "type": "League",
      "logo": "https://..."
    }
  ]
}

GET /api/v1/teams

Teams

Fetch full team profiles, venue information, and squad associations.

QUERY PARAMETERS

Param	Type	Description
league OPTIONAL	integer	Teams participating in this League ID
season OPTIONAL	integer	Teams participating in this Season Year
country OPTIONAL	string	Filter by country name
search OPTIONAL	string	Search teams by name (partial match)

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "get": "teams",
  "results": 1,
  "response": [
    {
      "id": 33,
      "name": "Manchester United",
      "founded": 1878,
      "logo": "https://...",
      "venue": {
        "name": "Old Trafford",
        "capacity": 74140
        }
    }
  ]
}

GET /api/v1/teams/logos

Bulk Team Logos

Fetch multiple team logos in a single request using comma-separated IDs.

QUERY PARAMETERS

Param	Type	Description
ids REQUIRED	string	Comma-separated list of Team IDs (e.g., '33,34,35')

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "get": "team-logos",
  "results": 2,
  "response": {
    "33": "https://...",
    "34": "https://..."
  }
}

GET /api/v1/players

Players

Lookup player details and basic biographical information.

QUERY PARAMETERS

Param	Type	Description
id OPTIONAL	integer	Specific Player ID
team OPTIONAL	integer	Filter players by Team ID
search OPTIONAL	string	Search players by name (partial match)

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "get": "players",
  "results": 1,
  "response": [
    {
      "id": 276,
      "name": "Neymar",
      "age": 31,
      "nationality": "Brazil",
      "photo": "https://..."
    }
  ]
}

GET /api/v1/squads

Team Squads

Get the current squad for a specific team, or the current team for a specific player.

QUERY PARAMETERS

Param	Type	Description
team OPTIONAL	integer	Team ID (e.g., 33 for Man Utd)
player OPTIONAL	integer	Player ID

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "get": "squads",
  "response": [
    {
      "team": {
        "id": 33,
        "name": "Manchester United",
        "logo": "https://..."
      },
      "players": [
        {
          "id": 909,
          "name": "M. Rashford",
          "age": 25,
          "number": 10,
          "position": "Attacker",
          "photo": "https://..."
        }
      ]
    }
  ]
}

GET /api/v1/coaches

Coaches

Fetch coach details and biographical data.

QUERY PARAMETERS

Param	Type	Description
id OPTIONAL	integer	Specific Coach ID
team OPTIONAL	integer	Determine the current coach of a specific Team ID

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "get": "coaches",
  "results": 1,
  "response": [
    {
      "id": 14,
      "name": "Pep Guardiola",
      "nationality": "Spain",
      "photo": "https://..."
    }
  ]
}

GET /api/v1/topscorers

Top Scorers

Get the top 20 goal scorers for a specific league and season.

QUERY PARAMETERS

Param	Type	Description
league REQUIRED	integer	League ID
season REQUIRED	integer	Season Year

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "get": "topscorers",
  "response": [
    {
      "player": { "id": 909, "name": "M. Rashford" },
      "statistics": [
        {
          "goals": { "total": 17, "assists": 5 },
          "games": { "appearences": 35, "minutes": 2880 }
        }
      ]
    }
  ]
}

GET /api/v1/topassists

Top Assists

Get the top 20 assist providers for a specific league and season.

QUERY PARAMETERS

Param	Type	Description
league REQUIRED	integer	League ID
season REQUIRED	integer	Season Year

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "get": "topassists",
  "response": [
    {
      "player": { "id": 619, "name": "Kevin De Bruyne" },
      "statistics": [
        {
          "goals": { "total": 7, "assists": 16 }
        }
      ]
    }
  ]
}

GET /api/v1/fixtures ▸ LIVE=ALL REQUIRES A PAID PLAN

Fixtures & Live Scores

The core endpoint for matches. Fetch historical results, upcoming schedules, or live scores in real-time.

QUERY PARAMETERS

Param	Type	Description
league OPTIONAL	integer	League ID (e.g. 39 for Premier League)
season OPTIONAL	integer	Season year (e.g. 2023)
date OPTIONAL	date	YYYY-MM-DD to get matches for a specific day
live OPTIONAL	string	Set to "all" to get currently playing live matches
team OPTIONAL	integer	Team ID to get a team's schedule
status OPTIONAL	string	Status short code (e.g. "FT", "NS", "1H", "HT")
from OPTIONAL	date	Start date range (must be combined with "to")
to OPTIONAL	date	End date range

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "get": "fixtures",
  "results": 1,
  "response": [
    {
      "id": 1035039,
      "date": "2023-08-11T19:00:00.000Z",
      "statusShort": "FT",
      "homeTeam": { "name": "Burnley", "goals": 0 },
      "awayTeam": { "name": "Manchester City", "goals": 3 }
    }
  ]
}

GET /api/v1/headtohead

Head-to-Head (H2H)

Compare the historical head-to-head match records between two specific teams.

QUERY PARAMETERS

Param	Type	Description
h2h REQUIRED	string	Format: 'team1-team2' (e.g. '33-34')
date OPTIONAL	date	Filter by specific match date
league OPTIONAL	integer	Filter H2H historical matches by League ID
season OPTIONAL	integer	Filter H2H historical matches by Season Year

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "get": "headtohead",
  "response": [
    {
      "teams": {
        "home": { "id": 33, "name": "Manchester United" },
        "away": { "id": 34, "name": "Newcastle" }
      },
      "goals": {
        "home": 2,
        "away": 0
      }
    }
  ]
}

GET /api/v1/fixtures/:id/events

Fixture Events

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

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "get": "events",
  "results": 2,
  "response": [
    {
      "time": 23,
      "teamId": 33,
      "type": "Goal",
      "detail": "Normal Goal",
      "playerName": "M. Rashford"
    }
  ]
}

GET /api/v1/fixtures/:id/lineups

Fixture Lineups

Starting XI, substitutes, formations, and coach for a specific match.

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "get": "lineups",
  "results": 2,
  "response": [
    {
      "teamId": 33,
      "formation": "4-2-3-1",
      "startXI": [
        { "playerId": 882, "playerName": "De Gea", "number": 1, "pos": "G" }
      ]
    }
  ]
}

GET /api/v1/fixtures/:id/statistics

Fixture Team Statistics

Team-level aggregate statistics for a specific match (possession, shots, passes...).

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "get": "statistics",
  "results": 2,
  "response": [
    {
      "teamId": 33,
      "statistics": {
         "Ball Possession": "54%",
         "Total Shots": 14
      }
    }
  ]
}

GET /api/v1/fixtures/:id/players

Fixture Player Statistics

Detailed player performance statistics and match ratings for a specific fixture.

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "get": "players",
  "results": 22,
  "response": [
    {
      "playerId": 276,
      "rating": "8.5",
      "minutes": 90,
      "goals": 1,
      "passes": { "total": 45, "accuracy": 88 }
    }
  ]
}

GET /api/v1/team-statistics

Team Season Statistics

Aggregate team statistics across an entire league season.

QUERY PARAMETERS

Param	Type	Description
team OPTIONAL	integer	Team ID
teamId OPTIONAL	integer	Alias for team id
league OPTIONAL	integer	League ID
leagueId OPTIONAL	integer	Alias for league id
season OPTIONAL	integer	Season Year (e.g., 2023)
year OPTIONAL	integer	Alias for season year

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "get": "team-statistics",
  "results": 1,
  "response": [
    {
      "fixtures": {
        "played": { "home": 19, "away": 19, "total": 38 }
      },
      "goals": {
        "for": { "total": { "home": 45, "away": 30, "total": 75 } }
      }
    }
  ]
}

GET /api/v1/standings

League Standings

League tables and rankings, including form and win/loss records.

QUERY PARAMETERS

Param	Type	Description
league REQUIRED	integer	League ID
season REQUIRED	integer	Season year

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "get": "standings",
  "response": [
    {
      "rank": 1,
      "team": {"name": "Arsenal", "id": 42},
      "points": 89,
      "form": "WWWWW",
      "all": { "played": 38, "win": 28, "draw": 5, "lose": 5 }
    }
  ]
}

GET /api/v1/transfers

Player Transfers

Historical transfer data for a specific player.

QUERY PARAMETERS

Param	Type	Description
player REQUIRED	integer	Player ID

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "get": "transfers",
  "response": [
    {
      "date": "2023-08-15",
      "type": "€ 90M",
      "teamIn": { "id": 85, "name": "Al Hilal" },
      "teamOut": { "id": 85, "name": "PSG" }
    }
  ]
}

GET /api/v1/odds ▸ REQUIRES ULTRA

Pre-Match Odds

Get pre-match bookmaker odds for a specific fixture.

QUERY PARAMETERS

Param	Type	Description
fixture REQUIRED	integer	Fixture ID (alias: fixtureId)
fixtureId OPTIONAL	integer	Alias for fixture ID
bookmaker OPTIONAL	integer	Filter by bookmaker ID (e.g., 8 for Bet365)
bet OPTIONAL	integer	Filter by Bet Type ID (e.g., 1 for Match Winner)

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "get": "odds",
  "response": [
    {
      "bookmaker": {"id": 8, "name": "Bet365", "image": "https://cdn.kickoffapi.com/images/bookmakers/8.png"},
      "betType": {"id": 1, "name": "Match Winner"},
      "values": [
        { "value": "Home", "odd": "1.50" },
        { "value": "Draw", "odd": "4.20" },
        { "value": "Away", "odd": "6.50" }
      ]
    }
  ]
}

GET /api/v1/odds/live ▸ REQUIRES ULTRA

Live In-Play Odds

Real-time in-play odds for currently active fixtures. Proxied directly to API-Sports for minimum latency.

QUERY PARAMETERS

Param	Type	Description
fixture REQUIRED	integer	Fixture ID (alias: fixtureId)
fixtureId OPTIONAL	integer	Alias for fixture ID
league OPTIONAL	integer	Filter by League ID (alias: leagueId)
leagueId OPTIONAL	integer	Alias for league ID
bet OPTIONAL	integer	Filter by Bet Type ID (alias: betId)
betId OPTIONAL	integer	Alias for bet ID

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "get": "odds/live",
  "response": [
    {
      "fixture": {"id": 1035039},
      "odds": [
        {
          "id": 1,
          "name": "Match Winner",
          "values": [
            { "value": "Home", "odd": "1.80" },
            { "value": "Draw", "odd": "3.20" },
            { "value": "Away", "odd": "4.50" }
          ]
        }
      ]
    }
  ]
}

GET /api/v1/predictions

Fixture Predictions

Algorithm-based match predictions, winning probabilities, and expert advice.

QUERY PARAMETERS

Param	Type	Description
fixture REQUIRED	integer	Fixture ID (alias: fixtureId)
fixtureId OPTIONAL	integer	Alias for fixture ID

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "get": "predictions",
  "response": [
    {
      "winner": { "id": 33, "name": "Manchester United" },
      "winOrDraw": true,
      "underOver": "-2.5",
      "advice": "Combo Double chance : Manchester United or draw...",
      "percent": { "home": "45%", "draw": "45%", "away": "10%" }
    }
  ]
}

GET /api/v1/injuries

Injuries & Sidelined

Get player injuries and suspensions.

QUERY PARAMETERS

Param	Type	Description
player OPTIONAL	integer	Filter by Player ID
team OPTIONAL	integer	Filter by Team ID
league OPTIONAL	integer	Filter by League ID
season OPTIONAL	integer	Filter by Season Year
fixture OPTIONAL	integer	Filter by Fixture ID

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "get": "injuries",
  "response": [
    {
      "player": {"id": 276, "name": "Neymar"},
      "type": "Knee Injury",
      "start": "2023-10-18T00:00:00.000Z",
      "end": null
    }
  ]
}

GET /api/v1/trophies

Player Trophies

Historical trophies and titles won by a player.

QUERY PARAMETERS

Param	Type	Description
player REQUIRED	integer	Player ID

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "get": "trophies",
  "response": [
    {
      "league": "Ligue 1",
      "country": "France",
      "season": "2022/2023",
      "place": "Winner"
    }
  ]
}

GET /api/v1/venues

Venues

Stadium and venue details.

QUERY PARAMETERS

Param	Type	Description
id OPTIONAL	integer	Venue ID
name OPTIONAL	string	Search by venue name
city OPTIONAL	string	Search by city

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "get": "venues",
  "response": [
    {
      "id": 556,
      "name": "Old Trafford",
      "address": "Sir Matt Busby Way",
      "city": "Manchester",
      "capacity": 74140,
      "surface": "grass",
      "image": "https://media.api-sports.io/football/venues/556.png"
    }
  ]
}

GET /api/v1/account/status

Account Status & Quota

Check your current plan, daily/monthly usage, and remaining credits.

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "plan": "PRO",
  "dailyUsage": {
    "used": 45,
    "limit": 1000,
    "remaining": 955
  },
  "monthlyUsage": {
    "used": 1250,
    "limit": 30000
  },
  "resetTime": "2024-04-03T23:59:59.999Z"
}

GET /api/v1/bookmakers

Reference: Bookmakers

List of all supported bookmakers, their respective IDs, and logo image URLs.

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "get": "bookmakers",
  "results": 2,
  "response": [
    { "id": 8, "name": "Bet365", "image": "https://cdn.kickoffapi.com/images/bookmakers/8.png" },
    { "id": 11, "name": "1xBet", "image": null }
  ]
}

GET /api/v1/bet-types

Reference: Bet Types

List of all supported bet types (markets) and their respective IDs.

EXAMPLE RESPONSE

200 OK · APPLICATION/JSON

{
  "get": "bet-types",
  "response": [
    { "id": 1, "name": "Match Winner" },
    { "id": 5, "name": "Goals Over/Under" }
  ]
}