# PitchAPI

> A read-only REST API for football data: shot-level detail with pitch and goal-line coordinates, lineups, momentum, match stats, and advanced analytics derived from the event feed. 70 leagues, full history back to 2021.

Base URL `https://api.pitchapi.dev`, HTTPS only. Every request carries an `X-API-KEY` header. Responses are a single JSON envelope with either a `data` key or an `error` key, never both. Coordinates are metres on a 105 x 68 pitch, normalised so the attacking goal is always at x = 105.

This site is a single page, so every section link below returns the same document. To read the documentation, fetch the full text file first.

## Documentation

- [Full reference, one file](https://pitchapi.dev/llms-full.txt): Every endpoint, every field and all 88 metric definitions as plain markdown. Start here.
- [Documentation site](https://pitchapi.dev/): The same reference as an HTML page.

## Fundamentals

- [Quickstart](https://pitchapi.dev/#quickstart): Base URL and a first request.
- [SDKs](https://pitchapi.dev/#sdks): Official client libraries — Python today, more to come. `pip install pitchapi`.
- [Authentication](https://pitchapi.dev/#authentication): The X-API-KEY header and key prefixes.
- [Responses](https://pitchapi.dev/#responses): The envelope, date formats and null semantics.
- [Resource IDs](https://pitchapi.dev/#ids): Prefixed opaque IDs — `m_`, `s_`, `p_`, `t_`, `l_`.
- [Plans and coverage](https://pitchapi.dev/#rate-limits): Free (70 leagues). One plan, no charge and no per-day request allowance.
- [Error codes](https://pitchapi.dev/#errors): 7 codes, each with the status it arrives on.

## API reference

- [Matches](https://pitchapi.dev/#matches): 18 endpoints. Everything attached to one fixture: the summary, shots, momentum, events, player stats, lineups, head-to-head, and team stats.
- [Leagues](https://pitchapi.dev/#leagues): 3 endpoints. The leagues in the catalogue. Every one of them is reachable with any key.
- [Teams & players](https://pitchapi.dev/#teams-players): 2 endpoints. Reference records for teams and players, resolvable from any ID returned elsewhere in the API.
- [Schedule](https://pitchapi.dev/#schedule): 1 endpoint. Find matches by date when you don't know the match ID in advance, and browse upcoming fixtures.

## Metrics

The advanced analytics, 88 in total. Each entry gives the published definition of the metric, what the count contains and the thresholds it uses.

- [Totals](https://pitchapi.dev/#metrics-totals): 2 metrics. The two fields that sit at the top level of every team and player object, outside the metric groups.
- [Possession value](https://pitchapi.dev/#metrics-possession-value): 7 metrics. What an action did to the probability of scoring. Both models are fitted on closed historical seasons and frozen, so a match is never scored by a model that saw it.
- [Pass network](https://pitchapi.dev/#metrics-pass-network): 7 metrics. The passing graph of each team, served by GET /v1/matches/{id}/advanced/network. The window closes at the team's first substitution, so these describe the starting eleven. Receivers are inferred — the player of the next action by the same team — so a pass whose receiver cannot be resolved counts in the node totals but contributes no edge.
- [Passing](https://pitchapi.dev/#metrics-passing): 10 metrics. Volume, accuracy and progression. One overlap to keep in mind throughout: passes counts crosses as well, so the two must never be added together.
- [Carrying](https://pitchapi.dev/#metrics-carrying): 10 metrics. Carries are synthesised, not observed: the event feed contains no carry event, and one is inserted wherever the ball moves between two consecutive actions by the same team, gated at the 5 m minimum of the standard published definition. That is roughly 400 movements a match that do not exist in the source.
- [Creation](https://pitchapi.dev/#metrics-creation): 8 metrics. Who made the chance. The expected-goals members attribute a per-shot xG joined in from the shot data rather than modelled by us.
- [Defending](https://pitchapi.dev/#metrics-defending): 15 metrics. Winning the ball back, and how high up the pitch. The first seven appear on players and teams; the rest are team level only.
- [Territory](https://pitchapi.dev/#metrics-territory): 5 metrics. Where the match was played. Team level only.
- [Tempo](https://pitchapi.dev/#metrics-tempo): 5 metrics. How a team moved the ball, and how quickly. Team level only. Sequences follow the standard published framework: a passage of play belonging to one team, beginning with a controlled action and ended by a defensive action, a stoppage or a shot.
- [Goalkeeping](https://pitchapi.dev/#metrics-goalkeeping): 9 metrics. Present only for the two players who started in goal, null for everyone else. Tell an outfield player from a quiet keeper by the null, not the zero — a quiet keeper has zeros.
- [Shooting](https://pitchapi.dev/#metrics-shooting): 10 metrics. The one group that does not come from the event feed. These are served through the shots and team-stats endpoints rather than through advanced analytics, so the locators below point at those responses.

## Optional

- [Get an API key](https://pitchapi.dev/get-api-key): Sign-up flow. Not needed to read the reference.