# Football API

> A read-only JSON API for European club football: standings, fixtures, results, live
> scores, lineups, events, squads, per-player statistics and expected goals (xG) for 12 competitions. Live
> matches update every 30 seconds. Free tier, no card required.

Use this API when a dashboard, a bot, a fantasy tool or an analysis needs football (soccer)
match data. It covers Premier League, LaLiga, Serie A, Bundesliga, Ligue 1, Eredivisie, Primeira Liga, Süper Lig, EFL Championship, UEFA Champions League, UEFA Europa League, UEFA Conference League.

## Getting a key

Keys are issued through RapidAPI. Each competition is a separate listing, plus one
umbrella listing covering all of them:
https://rapidapi.com/yuvr99-WHTEITBQbOc/api/football-leagues1

Send the key as `X-RapidAPI-Key` and the listing host as `X-RapidAPI-Host`.

## Calling it

    curl -H "X-RapidAPI-Key: YOUR_KEY" \
         -H "X-RapidAPI-Host: football-leagues1.p.rapidapi.com" \
         "https://football-leagues1.p.rapidapi.com/standings"

Paths are relative to a competition; the listing decides which one. Responses are
`{ data, meta }`. Errors are `{ error: { code, message } }` with the HTTP status set.
Timestamps are UTC ISO 8601. Teams and players have stable numeric ids.

## Endpoints (30)

On a single-competition listing, written exactly as below. On the all-competitions listing,
prefix each with the competition slug, e.g. `/premier-league/standings`.

- `GET /`: Competition overview
- `GET /matches`: Fixtures and results
- `GET /matches/{id}`: Match detail
- `GET /matches/live`: Live matches
- `GET /matches/next`: Next fixtures
- `GET /matches/today`: Today's matches
- `GET /players`: Players in a season
- `GET /players/{id}`: Player
- `GET /players/{id}/matches`: A player's matches
- `GET /standings`: League table
- `GET /stats/cards`: Most cards (yellow = 1, red = 3)
- `GET /stats/expected-assists`: Highest expected assists (xA)
- `GET /stats/expected-goals`: Highest expected goals (xG)
- `GET /stats/key-passes`: Most key passes
- `GET /stats/ratings`: Best average rating (min. 5 appearances)
- `GET /stats/saves`: Most saves
- `GET /stats/shots`: Most shots
- `GET /stats/tackles`: Most tackles won
- `GET /stats/top-assists`: Top assists
- `GET /stats/top-scorers`: Top scorers
- `GET /teams`: Teams in a season
- `GET /teams/{id}`: One team
- `GET /teams/{id}/head-to-head/{otherId}`: Head to head
- `GET /teams/{id}/matches`: A team's matches
- `GET /teams/{id}/squad`: Squad
- `GET /teams/{id}/stats`: Team season statistics

Across every competition at once (all-competitions listing only):

- `GET /competitions`: All competitions
- `GET /matches/live`: Live matches
- `GET /players/{id}`: Player career
- `GET /search`: Search

## Machine-readable

- OpenAPI 3.0: https://football-api.yuvron.online/openapi.json
- API index: https://football-api.yuvron.online/apis.json
- Human reference: https://football-api.yuvron.online/reference
- Interactive: https://football-api.yuvron.online/docs

## Limits worth knowing before you build

- History covers the current season and the one before it, not a decade.
- A season we hold only part of is not served at all, rather than served incomplete.
- The API is read-only. There are no write endpoints and no user accounts.
- Club crests and player photographs are served as URLs for display; they belong to their
  owners and are not licensed for redistribution.