# Kickoffapi — API Documentation

> Real-time football data API: live scores, fixtures, lineups, statistics and odds across 900+ leagues. REST JSON + WebSocket feeds.

**Base URL:** `https://api.kickoffapi.com`

## Quickstart

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

## Authentication

Every request requires your API key in the `x-api-key` header. Keys map to a subscription plan and its limits. Get a free key (100 requests/day, no card) at https://kickoffapi.com/signup.html

## Rate limits & errors

Response headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `X-Request-Id`.
Errors: 401 (missing/invalid key), 403 (endpoint not on your plan), 429 (rate limit exceeded — back off and retry after reset), 500 (server error — retry with backoff).

## Plans

- Hobby — $0/mo — 100 requests/day, all endpoints
- Starter — $19/mo — 20,000 requests/day, real-time live scores
- Pro — $39/mo — 100,000 requests/day, deep player statistics, WebSocket feeds
- Ultra — $99/mo — 500,000 requests/day, live in-play odds
- Enterprise — custom — 99.9% uptime SLA, dedicated support (contact contact@kickoffapi.com)

All paid plans include a one-time 7-day free trial. Annual billing: 2 months free. Overage bills per block — apps are never cut off.

## Endpoint reference

All endpoints are `GET` and return the envelope `{ get, results, response[] }`.

### Core data

#### Countries

`GET /api/v1/countries`

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

#### Leagues

`GET /api/v1/leagues`

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

Parameters:
- `country` (string, optional) — Filter by country name (e.g., "England")
- `current` (boolean, optional) — Set to "true" to only return active leagues
- `type` (string, optional) — Filter by type: "League" or "Cup"

#### Teams

`GET /api/v1/teams`

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

Parameters:
- `league` (integer, optional) — Teams participating in this League ID
- `season` (integer, optional) — Teams participating in this Season Year
- `country` (string, optional) — Filter by country name
- `search` (string, optional) — Search teams by name (partial match)

#### Bulk Team Logos

`GET /api/v1/teams/logos`

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

Parameters:
- `ids` (string, required) — Comma-separated list of Team IDs (e.g., '33,34,35')

#### Players

`GET /api/v1/players`

Lookup player details and basic biographical information.

Parameters:
- `id` (integer, optional) — Specific Player ID
- `team` (integer, optional) — Filter players by Team ID
- `search` (string, optional) — Search players by name (partial match)

#### Team Squads

`GET /api/v1/squads`

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

Parameters:
- `team` (integer, optional) — Team ID (e.g., 33 for Man Utd)
- `player` (integer, optional) — Player ID

#### Coaches

`GET /api/v1/coaches`

Fetch coach details and biographical data.

Parameters:
- `id` (integer, optional) — Specific Coach ID
- `team` (integer, optional) — Determine the current coach of a specific Team ID

#### Top Scorers

`GET /api/v1/topscorers`

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

Parameters:
- `league` (integer, required) — League ID
- `season` (integer, required) — Season Year

#### Top Assists

`GET /api/v1/topassists`

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

Parameters:
- `league` (integer, required) — League ID
- `season` (integer, required) — Season Year

### Fixtures & results

#### Fixtures & Live Scores

`GET /api/v1/fixtures`

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

*Live=all requires a paid plan.*

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

#### Head-to-Head (H2H)

`GET /api/v1/headtohead`

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

Parameters:
- `h2h` (string, required) — Format: 'team1-team2' (e.g. '33-34')
- `date` (date, optional) — Filter by specific match date
- `league` (integer, optional) — Filter H2H historical matches by League ID
- `season` (integer, optional) — Filter H2H historical matches by Season Year

#### Fixture Events

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

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

#### Fixture Lineups

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

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

#### Fixture Team Statistics

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

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

#### Fixture Player Statistics

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

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

### Aggregates & historical

#### Team Season Statistics

`GET /api/v1/team-statistics`

Aggregate team statistics across an entire league season.

Parameters:
- `team` (integer, optional) — Team ID
- `teamId` (integer, optional) — Alias for team id
- `league` (integer, optional) — League ID
- `leagueId` (integer, optional) — Alias for league id
- `season` (integer, optional) — Season Year (e.g., 2023)
- `year` (integer, optional) — Alias for season year

#### League Standings

`GET /api/v1/standings`

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

Parameters:
- `league` (integer, required) — League ID
- `season` (integer, required) — Season year

#### Player Transfers

`GET /api/v1/transfers`

Historical transfer data for a specific player.

Parameters:
- `player` (integer, required) — Player ID

### Betting & odds

#### Pre-Match Odds

`GET /api/v1/odds`

Get pre-match bookmaker odds for a specific fixture.

*Requires ultra.*

Parameters:
- `fixture` (integer, required) — Fixture ID (alias: fixtureId)
- `fixtureId` (integer, optional) — Alias for fixture ID
- `bookmaker` (integer, optional) — Filter by bookmaker ID (e.g., 8 for Bet365)
- `bet` (integer, optional) — Filter by Bet Type ID (e.g., 1 for Match Winner)

#### Live In-Play Odds

`GET /api/v1/odds/live`

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

*Requires ultra.*

Parameters:
- `fixture` (integer, required) — Fixture ID (alias: fixtureId)
- `fixtureId` (integer, optional) — Alias for fixture ID
- `league` (integer, optional) — Filter by League ID (alias: leagueId)
- `leagueId` (integer, optional) — Alias for league ID
- `bet` (integer, optional) — Filter by Bet Type ID (alias: betId)
- `betId` (integer, optional) — Alias for bet ID

#### Fixture Predictions

`GET /api/v1/predictions`

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

Parameters:
- `fixture` (integer, required) — Fixture ID (alias: fixtureId)
- `fixtureId` (integer, optional) — Alias for fixture ID

### Reference

#### Injuries & Sidelined

`GET /api/v1/injuries`

Get player injuries and suspensions.

Parameters:
- `player` (integer, optional) — Filter by Player ID
- `team` (integer, optional) — Filter by Team ID
- `league` (integer, optional) — Filter by League ID
- `season` (integer, optional) — Filter by Season Year
- `fixture` (integer, optional) — Filter by Fixture ID

#### Player Trophies

`GET /api/v1/trophies`

Historical trophies and titles won by a player.

Parameters:
- `player` (integer, required) — Player ID

#### Venues

`GET /api/v1/venues`

Stadium and venue details.

Parameters:
- `id` (integer, optional) — Venue ID
- `name` (string, optional) — Search by venue name
- `city` (string, optional) — Search by city

#### Account Status & Quota

`GET /api/v1/account/status`

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

#### Reference: Bookmakers

`GET /api/v1/bookmakers`

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

#### Reference: Bet Types

`GET /api/v1/bet-types`

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

---

Full interactive docs: https://docs.kickoffapi.com/ · Pricing: https://kickoffapi.com/pricing.html · Terms: https://kickoffapi.com/terms.html