---
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 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/) |

## 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/)
- [Odds & best prices](/docs/guides/odds/)
- [Live data via WebSocket](/docs/websocket/football/) (separate $3/mo addon)