# Football Charts

> Transparent football (soccer) statistics and model predictions across 90+ leagues. A Dixon-Coles
> scoreline model produces one joint distribution per match, from which 1X2, over/under and BTTS
> probabilities are derived; season outcomes come from 10,000-run Monte Carlo simulations rerun
> daily. Every model signal is logged before kickoff and settled publicly — wins and losses alike.
> Free read-only REST API and a hosted MCP server, both keyed with the same free API key.
> Probabilities and statistics, not betting advice. 18+.

Generated by API Evangelist on 2026-09-04 from apis.yml and the artifacts in this repository.
The provider does not publish an llms.txt of its own (https://www.football-charts.com/llms.txt -> 404).

## Getting started

- [Developer API & MCP server](https://www.football-charts.com/developers): the single developer
  page — key registration form, MCP connector setup, REST examples, endpoint list, free-vs-paid.
- Register a key: `POST https://footballcharts-backend.onrender.com/api/v1/keys/register/` with
  `{"email": "you@example.com"}`. The key (`fc_...`) is shown once. Free, read-only, replaceable.
- Authenticate: `Authorization: Bearer fc_<key>` or `X-API-Key: fc_<key>`.
- Attribution is required: "Data by football-charts.com".

## APIs

- [Football Charts REST API](https://www.football-charts.com/developers): read-only JSON over
  `https://footballcharts-backend.onrender.com/api/v1`. The API describes itself anonymously at
  `GET /api/v1/` — name, version, auth, free-tier limits and the full endpoint list.
- [Football Charts MCP Server](https://mcp.football-charts.com/mcp): hosted Model Context Protocol
  server, protocol 2025-06-18, ten read-only tools. `tools/list` answers anonymously; tool calls
  need the key. Also runnable locally as `npx -y footballcharts-mcp` with `FC_API_KEY` set.

## REST endpoints

- `GET /api/v1/leagues/` — leagues and the seasons your key can query. Call this first.
- `GET /api/v1/leagues/{league}/table/?season=&view=classic|luck|goals` — standings.
- `GET /api/v1/leagues/{league}/results/?season=&team=` — finished matches, FT/HT, first-goal minute.
- `GET /api/v1/leagues/{league}/fixtures/` — upcoming matches with model probabilities.
- `GET /api/v1/leagues/{league}/projection/` — Monte Carlo season projection.
- `GET /api/v1/leagues/{league}/goal-timing/?season=&team=` — goals per 15-minute bin.
- `GET /api/v1/leagues/{league}/teams/?season=` — teams in table order.
- `GET /api/v1/leagues/{league}/teams/{team}/?season=` — one team: match log, goal timing, stats.
- `GET /api/v1/matches/{slug}/` — one match, full probability block across markets.
- `GET /api/v1/track-record/` — the settled public prediction ledger.
- `POST /api/v1/keys/register/` — issue a free key.

## MCP tools

- `list_leagues` — all leagues + available seasons. Call first to resolve league keys.
- `get_league_table` — standings: points, W/D/L, goals, form.
- `get_rankings` — the table re-ranked luck-adjusted or by goals.
- `get_results` — finished matches with FT/HT scores and first-goal minute.
- `get_fixtures` — upcoming matches with model probabilities.
- `get_match` — one match: full probability block across markets.
- `get_season_projection` — title / top-4 / relegation %, points ranges.
- `get_team` — one team: match log, goal timing, stats.
- `get_goal_timing` — goals per 15-minute bin, per team.
- `get_track_record` — the settled public prediction ledger.

## Repository artifacts

- [MCP manifest](https://raw.githubusercontent.com/api-evangelist/football-charts/refs/heads/main/mcp/football-charts-mcp.yml)
- [MCP tools/list, verbatim](https://raw.githubusercontent.com/api-evangelist/football-charts/refs/heads/main/mcp/football-charts-tools-list.json)
- [Tool crosswalk (MCP tool -> REST path)](https://raw.githubusercontent.com/api-evangelist/football-charts/refs/heads/main/mcp/football-charts-tool-crosswalk.yml)
- [Authentication](https://raw.githubusercontent.com/api-evangelist/football-charts/refs/heads/main/authentication/football-charts-authentication.yml)
- [Conventions](https://raw.githubusercontent.com/api-evangelist/football-charts/refs/heads/main/conventions/football-charts-conventions.yml)
- [Error catalog](https://raw.githubusercontent.com/api-evangelist/football-charts/refs/heads/main/errors/football-charts-problem-types.yml)
- [Rate limits](https://raw.githubusercontent.com/api-evangelist/football-charts/refs/heads/main/rate-limits/football-charts-rate-limits.yml)
- [Plans and pricing](https://raw.githubusercontent.com/api-evangelist/football-charts/refs/heads/main/plans/football-charts-plans-pricing.yml)
- [Data model](https://raw.githubusercontent.com/api-evangelist/football-charts/refs/heads/main/data-model/football-charts-data-model.yml)
- [Agent skills](https://raw.githubusercontent.com/api-evangelist/football-charts/refs/heads/main/skills/_index.yml)

## Docs

- [About & methodology](https://www.football-charts.com/about)
- [Track record](https://www.football-charts.com/track-record)
- [Insights](https://www.football-charts.com/insights)
- [Privacy](https://www.football-charts.com/privacy)
- [MCP server source (MIT)](https://github.com/ddevetak/footballcharts-mcp)
- [npm: footballcharts-mcp](https://www.npmjs.com/package/footballcharts-mcp)

## Optional

- Limits: 5,000 requests/day and 60/minute on the free tier. No rate-limit response headers are
  returned — budget against the documented ceiling.
- No odds on the free tier. A paid tier (multi-book odds, full historical archive, bulk export,
  commercial license) is announced as "coming"; contact contact@football-charts.com.
- No OpenAPI, GraphQL, AsyncAPI, webhooks, agent card, security.txt or status page are published.