---
title: Football API
description: Free REST API for football — matches, live scores, leagues, standings, teams, players, odds and predictions. Base path /api/v2/.
badge: free
---

# Football API

The football API is **free** — you only need a token
([register here](/register/)). It covers 30+ leagues with deep match data:
live scores, statistics with xG and shotmaps, lineups, standings,
head-to-heads, player stats, transfers, multi-bookmaker odds (pre-match) and model
predictions.

```
Base URL:  https://sports.bzzoiro.com/api/v2/
Auth:      Authorization: Token YOUR_API_KEY
```

Two versions exist. **Use v2** — it is the actively developed one. v1
(`/api/`) remains for existing integrations: [v1 API (legacy)](/docs/football/v1/).

## Resources

| Area | Endpoints | Reference |
|---|---|---|
| Events & live | `/events/`, `/events/live/`, `/events/{id}/` + 12 sub-resources (stats, lineups, incidents, h2h, odds…) | [Events & live scores](/docs/football/events/) |
| Leagues & seasons | `/leagues/`, standings, seasons, leaderboards, best XI, venues | [Leagues, seasons & standings](/docs/football/leagues/) |
| Teams & players | `/teams/`, `/players/`, squads, fixtures, stats, transfers, World Cup squads | [Teams, players & transfers](/docs/football/teams-players/) |
| People & places | `/managers/`, `/referees/`, `/venues/` | [Managers, referees & venues](/docs/football/managers-referees-venues/) |
| Odds & predictions | `/odds/`, `/odds/best/`, `/bookmakers/`, `/predictions/` | [Odds & predictions](/docs/football/odds-predictions/) |
| Media | `/tv-channels/`, `/broadcasts/`, `/social/` | [TV, broadcasts & social](/docs/football/broadcasts-social/) |
| Coverage | `/coverage/` — what every sport holds right now, in one call | see below |

## What is there to poll

`GET /api/v2/coverage/` answers, for every sport on the platform, whether it has
fixtures ahead, how many of them are priced, and when the next and last events
are. It needs no token. Worth one call before a polling loop decides what to ask
for: hockey and basketball are out of season for months at a time, and their
fixture endpoints can only answer that with an empty list.

```bash
curl "https://sports.bzzoiro.com/api/v2/coverage/"
```

```json
{"generated_at": "2026-08-19T17:44:40+00:00", "sports": [
  {"sport": "football", "status": "in_season", "events_next_7d": 527,
   "events_next_30d": 1911, "priced_next_7d": 439, "live_now": 0,
   "next_event_at": "2026-08-19T18:00:00+00:00",
   "last_event_at": "2026-08-19T17:30:00+00:00", "docs_url": "/docs/football/"},
  {"sport": "hockey", "status": "off_season", "events_next_7d": 0,
   "events_next_30d": 0, "priced_next_7d": 0, "live_now": 0,
   "next_event_at": null, "last_event_at": "2026-06-18T00:00:00+00:00",
   "docs_url": "/docs/hockey/"}
]}
```

`status` is `in_season`, `between_events`, `off_season` or `no_fixtures`.
Add `?sport=hockey` for one sport.

## Quick example

```bash
# Live matches right now
curl -H "Authorization: Token YOUR_API_KEY" \
     "https://sports.bzzoiro.com/api/v2/events/live/"
```

## Conventions

Pagination (`limit`/`offset`, default 50, max 200), UTC ISO-8601 dates,
decimal odds and the uniform error shape are shared with every BSD API —
see [Conventions & limits](/docs/conventions/). Hot endpoints (`events`,
`leagues`, `teams`) are edge-cached ~5 s (`X-Cache-Status` header).

## Interactive reference

- [OpenAPI explorer](/docs/explorer/football/) — browse every endpoint and
  schema
- [Swagger UI](/api/docs/) · [ReDoc](/api/redoc/) · raw schema at
  [/openapi.json](/openapi.json)

## Typical workflows

- [Build a league page](/docs/guides/league-page/)
- [Get a player profile](/docs/guides/football-player-profile/)
- [Live data via WebSocket](/docs/websocket/football/) (separate $3/mo addon)