### SDK - Install and Setup

Source: https://pitchapi.dev/

Install the official Python SDK and set up the client. The key can be passed directly or read from the PITCHAPI_API_KEY environment variable.

```APIDOC
## SDK Installation and Setup

### Description
Install the `pitchapi` Python package and initialize the client. The API key can be passed as `api_key=` or read from the `PITCHAPI_API_KEY` environment variable.

### Installation
```
pip install pitchapi
```

### Requirements
- Python 3.9+
- One dependency: `httpx`

### Usage
```python
from pitchapi import PitchAPI

with PitchAPI(api_key="pk_live_...") as client:
    # Use the client
    pass
```

### Environment Variable
- `PITCHAPI_API_KEY` - Your API key, read automatically if not passed explicitly.
```

--------------------------------

### Quickstart - Get a day of fixtures

Source: https://pitchapi.dev/

Make your first request to the PitchAPI REST API to retrieve fixtures for a given date. Requires an API key passed via the X-API-KEY header.

```APIDOC
## GET /v1/date/{date}

### Description
Retrieve all matches for a given date. This is the first request to make to get a day of fixtures.

### Method
GET

### Endpoint
`https://api.pitchapi.dev/v1/date/{date}`

### Parameters
#### Path Parameters
- **date** (string) - Required - Date in YYYY-MM-DD format.

#### Headers
- **X-API-KEY** (string) - Required - Your API key.

### Request Example
```
curl https://api.pitchapi.dev/v1/date/2025-11-09 \
  -H "X-API-KEY: $PITCH_KEY"
```

### Response
#### Success Response (200)
Returns a list of matches for the date.

#### Response Example
(Not provided in source)
```

--------------------------------

### Install the PitchAPI Python SDK

Source: https://pitchapi.dev/

Installs the official Python client library via pip. Requires Python 3.9+ and the httpx dependency. The API key can be passed as api_key= or read from the PITCHAPI_API_KEY environment variable.

```bash
pip install pitchapi
```

--------------------------------

### Retrieve a league - JSON response

Source: https://pitchapi.dev/

Example response for a single league, including its current season.

```json
{
  "data": {
    "id": "l_4Kd0Wq",
    "name": "Premier League",
    "country_code": "ENG",
    "season": "2025/2026",
    "image_url": "https://cdn.pitchapi.dev/leagues/47.webp"
  }
}
```

--------------------------------

### List league matches - JSON response

Source: https://pitchapi.dev/

Example response with league info and a list of matches, including status, scores, and team details.

```json
{
  "data": {
    "league": {
      "id": "l_4Kd0Wq",
      "name": "Premier League",
      "season": "2025/2026",
      "image_url": "https://cdn.pitchapi.dev/leagues/47.webp"
    },
    "matches": [
      {
        "id": "m_B8x2K9",
        "date": "2025-11-09",
        "time_utc": "2025-11-09T16:30:00Z",
        "status": "finished",
        "home_team": { "id": "t_9aB2xQ", "name": "Manchester City" },
        "away_team": { "id": "t_2mLp7C", "name": "Manchester United" },
        "score_home": 3,
        "score_away": 1
      }
    ]
  }
}
```

--------------------------------

### GET /v1/matches/{id}/lineups

Source: https://pitchapi.dev/

Retrieves the predicted lineup for an upcoming match within 48 hours of kickoff. Returns formation, starting eleven, bench, and coach for each side, with a 'confirmed' boolean indicating whether the lineup is predicted or confirmed.

```APIDOC
## GET /v1/matches/{id}/lineups

### Description
Retrieves the predicted lineup for an upcoming match within 48 hours of kickoff. Returns formation, starting eleven, bench, and coach for each side, with a 'confirmed' boolean indicating whether the lineup is predicted or confirmed.

### Method
GET

### Endpoint
/v1/matches/{id}/lineups

### Parameters
#### Path Parameters
- **id** (string) - Required - The match ID (e.g., m_9Xk2Qv).

### Request Example
```
curl -s "https://api.pitchapi.dev/v1/matches/m_9Xk2Qv/lineups" \
  -H "X-API-KEY: $PITCH_KEY"
```

### Response
#### Success Response (200)
- **confirmed** (boolean) - Indicates whether the lineup is predicted (false) or confirmed/actual (true).
- **lineup_type** (string) - When confirmed is false, indicates the prediction type (e.g., "lastStarting11").
- **formation** (string) - The formation used.
- **starting_eleven** (array) - The starting eleven players.
- **bench** (array) - The bench players.
- **coach** (string) - The coach name.

#### Response Example
```
{
  "confirmed": false,
  "lineup_type": "lastStarting11",
  "formation": "4-3-3",
  "starting_eleven": ["player1", "player2"],
  "bench": ["player12", "player13"],
  "coach": "Coach Name"
}
```
```

--------------------------------

### Shot response JSON

Source: https://pitchapi.dev/

Example response for the shot endpoint, showing a single shot's details.

```json
{
  "data": {
    "id": "s_Q1pR6z",
    "player": { "id": "p_7YtX4q", "name": "E. Haaland" },
    "team_id": "t_9aB2xQ",
    "x": 88.5,
    "y": 42.3,
    "expected_goals": 0.38,
    "is_on_target": true,
    "shot_type": "RightFoot",
    "situation": "RegularPlay",
    "minute": 34,
    "event_type": "Goal"
  }
}
```

--------------------------------

### Retrieve lineups - curl request

Source: https://pitchapi.dev/

Use this endpoint to get formations, starters, and benches for both teams. Requires match ID. The API key is passed via the X-API-KEY header.

```bash
curl https://api.pitchapi.dev/v1/matches/{id}/lineups \
  -H "X-API-KEY: $PITCH_KEY"
```

--------------------------------

### List leagues - JSON response

Source: https://pitchapi.dev/

Example response showing a league object with id, name, country_code, image_url, seasons array, and is_free flag.

```json
{
  "data": {
    "leagues": [
      {
        "id": "l_4Kd0Wq",
        "name": "Premier League",
        "country_code": "ENG",
        "image_url": "https://cdn.pitchapi.dev/leagues/47.webp",
        "seasons": ["2025/2026", "2024/2025"],
        "is_free": true
      }
    ]
  }
}
```

--------------------------------

### Match summary JSON response

Source: https://pitchapi.dev/

Example response for the match summary endpoint, showing league, teams, score, status, referee, and stadium.

```json
{
  "data": {
    "id": "m_B8x2K9",
    "league": {
      "id": "l_4Kd0Wq",
      "name": "Premier League",
      "image_url": "https://cdn.pitchapi.dev/leagues/47.webp"
    },
    "home_team": {
      "id": "t_9aB2xQ",
      "name": "Manchester City",
      "image_url": "https://cdn.pitchapi.dev/teams/8456.webp"
    },
    "away_team": {
      "id": "t_2mLp7C",
      "name": "Manchester United",
      "image_url": "https://cdn.pitchapi.dev/teams/10260.webp"
    },
    "date": "2025-11-09",
    "time_utc": "2025-11-09T16:30:00Z",
    "status": "finished",
    "score_home": 3,
    "score_away": 1,
    "round_name": "11",
    "has_playoff": false,
    "referee": "Michael Oliver",
    "stadium": "Etihad Stadium"
  }
}
```

--------------------------------

### Retrieve head-to-head - JSON response

Source: https://pitchapi.dev/

Example response for the head-to-head endpoint. Contains match info, win/draw/loss counts, and recent matches with scores and finished status.

```json
{
  "data": {
    "match_id": "m_B8x2K9",
    "home_team": { "id": "t_9aB2xQ", "name": "Manchester City" },
    "away_team": { "id": "t_2mLp7C", "name": "Manchester United" },
    "home_wins": 12,
    "draws": 5,
    "away_wins": 7,
    "total_matches": 24,
    "recent_matches": [
      {
        "time_utc": "2025-04-06T15:30:00.000Z",
        "home": { "id": "t_2mLp7C", "name": "Manchester United" },
        "away": { "id": "t_9aB2xQ", "name": "Manchester City" },
        "score_home": 1,
        "score_away": 2,
        "finished": true
      },
      {
        "time_utc": "2026-01-25T14:00:00.000Z",
        "home": { "id": "t_9aB2xQ", "name": "Manchester City" },
        "away": { "id": "t_2mLp7C", "name": "Manchester United" },
        "score_home": null,
        "score_away": null,
        "finished": false
      }
    ]
  }
}
```

--------------------------------

### GET /v1/matches/{id}/advanced/network

Source: https://pitchapi.dev/

Retrieves the passing graph of each team for a given match. The window closes at the team's first substitution, describing the starting eleven. Receivers are inferred from the next action by the same team.

```APIDOC
## GET /v1/matches/{id}/advanced/network

### Description
Retrieves the passing graph of each team for a given match. The window closes at the team's first substitution, describing the starting eleven. Receivers are inferred from the next action by the same team.

### Method
GET

### Endpoint
/v1/matches/{id}/advanced/network

### Parameters
#### Path Parameters
- **id** (string) - Required - The match identifier.

### Response
#### Success Response (200)
- **networks[].nodes[].avg_x** (number) - The mean origin of that player's completed passes in the window (x coordinate). Null for a player who received passes but never played one.
- **networks[].nodes[].avg_y** (number) - The mean origin of that player's completed passes (y coordinate). Null when the player attempted no pass in the window.
- **networks[].nodes[].degree** (number) - Distinct teammates the player exchanged at least one pass with. Nullable as a group with strength, betweenness and clustering.
- **networks[].nodes[].strength** (number) - Weighted degree — total passes to and from the player. Nullable as a group with the other centrality measures.
- **networks[].nodes[].betweenness** (number) - How much passing flow between others routes through this player. Computed on an edge distance of 1/passes. Nullable as a group with the other centrality measures.
- **networks[].nodes[].clustering** (number) - Local clustering coefficient: the fraction of the player's passing pairs that are themselves connected. Nullable as a group with the other centrality measures.
- **networks[].centralization** (number) - Freeman centralization on degree: 0 when every player is equally connected, approaching 1 when one hub touches everything. Null when the graph had no edges.

#### Response Example
{
  "networks": [
    {
      "nodes": [
        {
          "avg_x": 50.0,
          "avg_y": 30.0,
          "degree": 5,
          "strength": 12,
          "betweenness": 0.2,
          "clustering": 0.5
        }
      ],
      "centralization": 0.3
    }
  ]
}
```

--------------------------------

### SDK - Namespaces

Source: https://pitchapi.dev/

Overview of the five namespaces exposed by both clients and their available methods.

```APIDOC
## SDK Namespaces

### Description
Both `PitchAPI` and `AsyncPitchAPI` expose the same five namespaces.

### Namespaces

#### `client.date`
- `get(date, status=None)` - Get every match on a day. `date` takes a YYYY-MM-DD string or a `datetime.date`.

#### `client.matches`
- `get`
- `shots`
- `shot`
- `events`
- `lineups`
- `momentum`
- `stats`
- `players`
- `player`
- `players_halves`
- `player_halves`
- `player_shots`
- `h2h`
- `advanced`
- `advanced_network`
- `advanced_players`
- `advanced_player`
- `heatmaps`

#### `client.leagues`
- `list`
- `get`
- `matches(id, season=None, status=None)` - Season defaults to the latest one with data.

#### `client.teams`
- `get` - Get the team profile.

#### `client.players`
- `get` - Get the player profile.
```

--------------------------------

### Authenticated Request

Source: https://pitchapi.dev/

Example of an authenticated request to the Pitch API using the X-API-KEY header.

```APIDOC
## GET /v1/matches/{match_id}

### Description
Retrieves a match by its ID. Requires authentication via the X-API-KEY header.

### Method
GET

### Endpoint
/v1/matches/{match_id}

### Parameters
#### Path Parameters
- **match_id** (string) - Required - The unique identifier of the match (e.g., m_B8x2K9).

#### Headers
- **X-API-KEY** (string) - Required - Your API key (production: pk_live_, test: pk_test_).

### Request Example
```
curl https://api.pitchapi.dev/v1/matches/m_B8x2K9 \
  -H "X-API-KEY: pk_live_xxxxxxxxxxxxxxxxxxxxxxxx"
```

### Response
#### Success Response (200)
- **data** (object) - The match data.
  - **id** (string) - The match ID.
  - **status** (string) - The match status (e.g., "finished").
  - **score_home** (integer) - Home team score.
  - **score_away** (integer) - Away team score.

#### Response Example
```
{
  "data": {
    "id": "m_B8x2K9",
    "status": "finished",
    "score_home": 3,
    "score_away": 1
  }
}
```

#### Error Response (404)
- **error** (object) - Error details.
  - **code** (string) - Error code (e.g., "RESOURCE_NOT_FOUND").
  - **message** (string) - Error message.

#### Error Example
```
{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "match not found"
  }
}
```
```

--------------------------------

### GET /v1/matches/{id}/lineups

Source: https://pitchapi.dev/

Retrieves formations, starters, and benches for both sides. Starters carry normalised coordinates for drawing the formation; subs are always zero. For a fixture that has not kicked off the sides may still be a pre-match prediction, so check `confirmed` before trusting the XI; `lineup_type` names the prediction and is omitted once the lineup is confirmed.

```APIDOC
## GET /v1/matches/{id}/lineups

### Description
Retrieves formations, starters, and benches for both sides. Starters carry normalised coordinates for drawing the formation; subs are always zero. For a fixture that has not kicked off the sides may still be a pre-match prediction, so check `confirmed` before trusting the XI; `lineup_type` names the prediction and is omitted once the lineup is confirmed.

### Method
GET

### Endpoint
/v1/matches/{id}/lineups

### Parameters
#### Path Parameters
- **id** (string) - Required - Match ID, for example m_B8x2K9

### Request Example
```
curl https://api.pitchapi.dev/v1/matches/{id}/lineups \
  -H "X-API-KEY: $PITCH_KEY"
```

### Response
#### Success Response (200)
- **data** (object) - Contains match_id, home_team, away_team, home, away
- **match_id** (string) - Match ID
- **home_team** (object) - Home team details (id, name)
- **away_team** (object) - Away team details (id, name)
- **home** (object) - Home lineup details
  - **formation** (string) - Formation string (e.g., 4-2-3-1)
  - **confirmed** (boolean) - Whether lineup is confirmed
  - **coach** (object) - Coach details (name)
  - **starters** (array) - List of starter objects
    - **player_id** (string) - Player ID
    - **name** (string) - Player name
    - **shirt_number** (string) - Shirt number
    - **position_id** (integer) - Position ID
    - **is_captain** (boolean) - Whether player is captain
    - **pitch_x** (number) - Normalised x coordinate
    - **pitch_y** (number) - Normalised y coordinate
  - **subs** (array) - List of substitutes
- **away** (object) - Away lineup details (same structure as home)

#### Response Example
```
{
  "data": {
    "match_id": "m_B8x2K9",
    "home_team": { "id": "t_9aB2xQ", "name": "Manchester City" },
    "away_team": { "id": "t_2mLp7C", "name": "Manchester United" },
    "home": {
      "formation": "4-2-3-1",
      "confirmed": true,
      "coach": { "name": "Pep Guardiola" },
      "starters": [
        {
          "player_id": "p_7YtX4q",
          "name": "E. Haaland",
          "shirt_number": "9",
          "position_id": 4,
          "is_captain": false,
          "pitch_x": 0.5,
          "pitch_y": 0.89
        }
      ],
      "subs": []
    },
    "away": { "formation": "4-3-3", "confirmed": true, "starters": [], "subs": [] }
  }
}
```
```

--------------------------------

### Retrieve lineups - JSON response

Source: https://pitchapi.dev/

Example response for the lineups endpoint. Contains home and away team info, formations, confirmed status, coach, starters with pitch coordinates, and subs.

```json
{
  "data": {
    "match_id": "m_B8x2K9",
    "home_team": { "id": "t_9aB2xQ", "name": "Manchester City" },
    "away_team": { "id": "t_2mLp7C", "name": "Manchester United" },
    "home": {
      "formation": "4-2-3-1",
      "confirmed": true,
      "coach": { "name": "Pep Guardiola" },
      "starters": [
        {
          "player_id": "p_7YtX4q",
          "name": "E. Haaland",
          "shirt_number": "9",
          "position_id": 4,
          "is_captain": false,
          "pitch_x": 0.5,
          "pitch_y": 0.89
        }
      ],
      "subs": []
    },
    "away": { "formation": "4-3-3", "confirmed": true, "starters": [], "subs": [] }
  }
}
```

--------------------------------

### GET /v1/matches/{id}/shots/{shot_id}

Source: https://pitchapi.dev/

Retrieves a single shot by its match-scoped shot ID.

```APIDOC
## GET /v1/matches/{id}/shots/{shot_id}

### Description
Retrieves a single shot by its match-scoped shot ID.

### Method
GET

### Endpoint
/v1/matches/{id}/shots/{shot_id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Match ID, for example m_B8x2K9
- **shot_id** (string) - Required - Shot ID scoped to the match, for example s_Q1pR6z

### Request Example
```
curl https://api.pitchapi.dev/v1/matches/{id}/shots/{shot_id} \
  -H "X-API-KEY: $PITCH_KEY"
```

### Response
#### Success Response (200)
- **data** (object) - Shot object
- **data.id** (string) - Shot ID
- **data.player** (object) - Player information
- **data.team_id** (string) - Team ID
- **data.x** (number) - X coordinate
- **data.y** (number) - Y coordinate
- **data.expected_goals** (number) - Expected goals
- **data.is_on_target** (boolean) - Whether shot is on target
- **data.shot_type** (string) - Shot type
- **data.situation** (string) - Situation
- **data.minute** (integer) - Minute of shot
- **data.event_type** (string) - Event type

#### Response Example
```
{
  "data": {
    "id": "s_Q1pR6z",
    "player": { "id": "p_7YtX4q", "name": "E. Haaland" },
    "team_id": "t_9aB2xQ",
    "x": 88.5,
    "y": 42.3,
    "expected_goals": 0.38,
    "is_on_target": true,
    "shot_type": "RightFoot",
    "situation": "RegularPlay",
    "minute": 34,
    "event_type": "Goal"
  }
}
```
```

--------------------------------

### List matches by date with GET /v1/date/{date}

Source: https://pitchapi.dev/

Returns matches for a given calendar date (YYYY-MM-DD). By default only played matches are returned; pass status=upcoming or status=all to include fixtures. Requires an API key in the X-API-KEY header.

```bash
curl https://api.pitchapi.dev/v1/date/{date} \
  -H "X-API-KEY: $PITCH_KEY"
```

```json
{
  "data": {
    "date": "2025-11-09",
    "matches": [
      {
        "id": "m_B8x2K9",
        "league": { "id": "l_4Kd0Wq", "name": "Premier League" },
        "home_team": { "id": "t_9aB2xQ", "name": "Manchester City" },
        "away_team": { "id": "t_2mLp7C", "name": "Manchester United" },
        "time_utc": "2025-11-09T16:30:00Z",
        "status": "finished",
        "score_home": 3,
        "score_away": 1
      }
    ]
  }
}
```

--------------------------------

### GET /v1/teams/{id}

Source: https://pitchapi.dev/

Retrieves a team's name and image URL by team ID.

```APIDOC
## GET /v1/teams/{id}

### Description
Retrieves a team's name and image URL.

### Method
GET

### Endpoint
/v1/teams/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Team ID, for example t_9aB2xQ

### Request Example
```
curl https://api.pitchapi.dev/v1/teams/{id} \
  -H "X-API-KEY: $PITCH_KEY"
```

### Response
#### Success Response (200)
- **data.id** (string) - Team ID
- **data.name** (string) - Team name
- **data.image_url** (string) - URL to team image

#### Response Example
```
{
  "data": {
    "id": "t_9aB2xQ",
    "name": "Manchester City",
    "image_url": "https://cdn.pitchapi.dev/teams/8456.webp"
  }
}
```
```

--------------------------------

### Retrieve a player with GET /v1/players/{id}

Source: https://pitchapi.dev/

Fetches a player's name, shirt number, position, country, and image URL. Requires the player ID as a path parameter (e.g., p_7YtX4q) and an API key in the X-API-KEY header.

```bash
curl https://api.pitchapi.dev/v1/players/{id} \
  -H "X-API-KEY: $PITCH_KEY"
```

```json
{
  "data": {
    "id": "p_7YtX4q",
    "name": "Erling Haaland",
    "short_name": "E. Haaland",
    "shirt_number": "9",
    "position_id": 4,
    "country_code": "NOR",
    "image_url": "https://cdn.pitchapi.dev/players/994226.webp"
  }
}
```

--------------------------------

### Momentum response JSON

Source: https://pitchapi.dev/

Example response for the momentum endpoint, showing a list of points with minute and value.

```json
{
  "data": {
    "match_id": "m_B8x2K9",
    "points": [
      { "minute": 1.00, "value": 0.02 },
      { "minute": 2.00, "value": 0.15 },
      { "minute": 34.00, "value": 0.87 },
      { "minute": 45.75, "value": 0.18 }
    ]
  }
}
```

--------------------------------

### Retrieve a team with GET /v1/teams/{id}

Source: https://pitchapi.dev/

Fetches a team's name and image URL. Requires the team ID as a path parameter (e.g., t_9aB2xQ) and an API key in the X-API-KEY header.

```bash
curl https://api.pitchapi.dev/v1/teams/{id} \
  -H "X-API-KEY: $PITCH_KEY"
```

```json
{
  "data": {
    "id": "t_9aB2xQ",
    "name": "Manchester City",
    "image_url": "https://cdn.pitchapi.dev/teams/8456.webp"
  }
}
```

--------------------------------

### Make a request with curl

Source: https://pitchapi.dev/get-api-key

Use this curl command to make your first request to the Pitch API. The response is wrapped in a data key on success and an error key on failure; the two never appear together.

```bash
curl https://api.pitchapi.dev/v1/date/2025-11-09 \
  -H "X-API-KEY: $PITCH_KEY"
```

--------------------------------

### GET /v1/date/{date}

Source: https://pitchapi.dev/

Lists matches by date, with optional status filter for played, upcoming, or all matches.

```APIDOC
## GET /v1/date/{date}

### Description
Lists the covered matches on a given date. By default only played matches are returned; use the status query parameter to include upcoming or all matches.

### Method
GET

### Endpoint
/v1/date/{date}

### Parameters
#### Path Parameters
- **date** (string) - Required - Calendar date as YYYY-MM-DD

#### Query Parameters
- **status** (string) - Optional - Which matches to return: played (default), upcoming, or all.

### Request Example
```
curl https://api.pitchapi.dev/v1/date/{date} \
  -H "X-API-KEY: $PITCH_KEY"
```

### Response
#### Success Response (200)
- **data.date** (string) - The requested date
- **data.matches** (array) - List of matches
  - **id** (string) - Match ID
  - **league** (object) - League info (id, name)
  - **home_team** (object) - Home team info (id, name)
  - **away_team** (object) - Away team info (id, name)
  - **time_utc** (string) - Match time in UTC
  - **status** (string) - Match status (e.g., finished)
  - **score_home** (integer) - Home score
  - **score_away** (integer) - Away score

#### Response Example
```
{
  "data": {
    "date": "2025-11-09",
    "matches": [
      {
        "id": "m_B8x2K9",
        "league": { "id": "l_4Kd0Wq", "name": "Premier League" },
        "home_team": { "id": "t_9aB2xQ", "name": "Manchester City" },
        "away_team": { "id": "t_2mLp7C", "name": "Manchester United" },
        "time_utc": "2025-11-09T16:30:00Z",
        "status": "finished",
        "score_home": 3,
        "score_away": 1
      }
    ]
  }
}
```
```

--------------------------------

### GET /v1/matches/{id}

Source: https://pitchapi.dev/

Retrieves the match summary including league, teams, score, status, referee, and stadium.

```APIDOC
## GET /v1/matches/{id}

### Description
Retrieves the match summary including league, teams, score, status, referee, and stadium.

### Method
GET

### Endpoint
/v1/matches/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Match ID, for example m_B8x2K9

### Request Example
```
curl https://api.pitchapi.dev/v1/matches/{id} \
  -H "X-API-KEY: $PITCH_KEY"
```

### Response
#### Success Response (200)
- **data** (object) - Match summary object
- **data.id** (string) - Match ID
- **data.league** (object) - League information
- **data.home_team** (object) - Home team information
- **data.away_team** (object) - Away team information
- **data.date** (string) - Match date
- **data.time_utc** (string) - Match time in UTC
- **data.status** (string) - Match status
- **data.score_home** (integer) - Home team score
- **data.score_away** (integer) - Away team score
- **data.round_name** (string) - Round name
- **data.has_playoff** (boolean) - Whether match has playoff
- **data.referee** (string) - Referee name
- **data.stadium** (string) - Stadium name

#### Response Example
```
{
  "data": {
    "id": "m_B8x2K9",
    "league": {
      "id": "l_4Kd0Wq",
      "name": "Premier League",
      "image_url": "https://cdn.pitchapi.dev/leagues/47.webp"
    },
    "home_team": {
      "id": "t_9aB2xQ",
      "name": "Manchester City",
      "image_url": "https://cdn.pitchapi.dev/teams/8456.webp"
    },
    "away_team": {
      "id": "t_2mLp7C",
      "name": "Manchester United",
      "image_url": "https://cdn.pitchapi.dev/teams/10260.webp"
    },
    "date": "2025-11-09",
    "time_utc": "2025-11-09T16:30:00Z",
    "status": "finished",
    "score_home": 3,
    "score_away": 1,
    "round_name": "11",
    "has_playoff": false,
    "referee": "Michael Oliver",
    "stadium": "Etihad Stadium"
  }
}
```
```

--------------------------------

### Asynchronous PitchAPI client usage

Source: https://pitchapi.dev/

Shows the AsyncPitchAPI client, which is the exact twin of PitchAPI with the same names, arguments, and models. The key is read from the PITCHAPI_API_KEY environment variable. Uses asyncio.run() to execute the async main function.

```python
import asyncio
from pitchapi import AsyncPitchAPI

async def main():
    async with AsyncPitchAPI() as client:  # key from PITCHAPI_API_KEY
        league = await client.leagues.get("l_0bfbkO")
        matches = await client.leagues.matches(league.id, season="2025/2026")

asyncio.run(main())
```

--------------------------------

### GET /v1/matches/{id}/events

Source: https://pitchapi.dev/

Lists goals, cards, subs, and penalties in order, each with the running score at that moment.

```APIDOC
## GET /v1/matches/{id}/events

### Description
Lists goals, cards, subs, and penalties in order, each with the running score at that moment.

### Method
GET

### Endpoint
/v1/matches/{id}/events

### Parameters
#### Path Parameters
- **id** (string) - Required - Match ID, for example m_B8x2K9

### Request Example
```
curl https://api.pitchapi.dev/v1/matches/{id}/events \
  -H "X-API-KEY: $PITCH_KEY"
```

### Response
#### Success Response (200)
- **data** (object) - Events data
- **data.match_id** (string) - Match ID
- **data.events** (array) - Array of events
- **data.events[].event_type** (string) - Type of event (e.g., Goal, Substitution)
- **data.events[].minute** (integer) - Minute of event
- **data.events[].minute_added** (integer) - Added minutes
- **data.events[].period** (string) - Period (inferred from minute)
- **data.events[].team_id** (string) - Team ID
- **data.events[].player** (object) - Player information
- **data.events[].score_home** (integer) - Home score at event
- **data.events[].score_away** (integer) - Away score at event
- **data.events[].is_own_goal** (boolean) - Whether own goal
- **data.events[].is_penalty** (boolean) - Whether penalty
- **data.events[].sub_in_player** (object) - Substituted-in player (for substitutions)

#### Response Example
```
{
  "data": {
    "match_id": "m_B8x2K9",
    "events": [
      {
        "event_type": "Goal",
        "minute": 34,
        "minute_added": 0,
        "period": "FirstHalf",
        "team_id": "t_9aB2xQ",
        "player": { "id": "p_7YtX4q", "name": "E. Haaland" },
        "score_home": 1,
        "score_away": 0,
        "is_own_goal": false,
        "is_penalty": false
      },
      {
        "event_type": "Substitution",
        "minute": 62,
        "minute_added": 0,
        "period": "SecondHalf",
        "team_id": "t_2mLp7C",
        "player": { "id": "p_3XvN8w", "name": "M. Mount" },
        "sub_in_player": { "id": "p_5RtY2k", "name": "A. Garnacho" },
        "is_own_goal": false,
        "is_penalty": false
      }
    ]
  }
}
```
```

--------------------------------

### SDK - Asynchronous Client

Source: https://pitchapi.dev/

Use the asynchronous AsyncPitchAPI client, which is the exact twin of PitchAPI with the same names, arguments, and models.

```APIDOC
## Asynchronous Client Usage

### Description
Use the asynchronous `AsyncPitchAPI` client for async/await support. It mirrors the synchronous client exactly.

### Example
```python
import asyncio
from pitchapi import AsyncPitchAPI

async def main():
    async with AsyncPitchAPI() as client:  # key from PITCHAPI_API_KEY
        league = await client.leagues.get("l_0bfbkO")
        matches = await client.leagues.matches(league.id, season="2025/2026")

asyncio.run(main())
```
```

--------------------------------

### GET /v1/leagues/{id}

Source: https://pitchapi.dev/

Retrieves a single league and its current season. The league ID is required as a path parameter.

```APIDOC
## GET /v1/leagues/{id}

### Description
Retrieves a single league and its current season.

### Method
GET

### Endpoint
/v1/leagues/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - League ID, for example l_4Kd0Wq.

#### Headers
- **X-API-KEY** (string) - Required - API key for authentication.

### Request Example
```
curl https://api.pitchapi.dev/v1/leagues/{id} \
  -H "X-API-KEY: $PITCH_KEY"
```

### Response
#### Success Response (200)
- **data.id** (string) - League ID.
- **data.name** (string) - League name.
- **data.country_code** (string) - Country code.
- **data.season** (string) - Current season.
- **data.image_url** (string) - URL to league image.

#### Response Example
```
{
  "data": {
    "id": "l_4Kd0Wq",
    "name": "Premier League",
    "country_code": "ENG",
    "season": "2025/2026",
    "image_url": "https://cdn.pitchapi.dev/leagues/47.webp"
  }
}
```
```

--------------------------------

### GET /v1/matches/{id}/shots

Source: https://pitchapi.dev/

Lists every shot in the match, grouped by half, with pitch coordinates and goal-line coordinates.

```APIDOC
## GET /v1/matches/{id}/shots

### Description
Lists every shot in the match, grouped by half, with pitch coordinates and goal-line coordinates.

### Method
GET

### Endpoint
/v1/matches/{id}/shots

### Parameters
#### Path Parameters
- **id** (string) - Required - Match ID, for example m_B8x2K9

### Request Example
```
curl https://api.pitchapi.dev/v1/matches/{id}/shots \
  -H "X-API-KEY: $PITCH_KEY"
```

### Response
#### Success Response (200)
- **data** (object) - Shots data
- **data.match_id** (string) - Match ID
- **data.periods** (array) - Array of periods
- **data.periods[].period** (string) - Period name (e.g., FirstHalf)
- **data.periods[].shots** (array) - Array of shots
- **data.periods[].shots[].id** (string) - Shot ID
- **data.periods[].shots[].player** (object) - Player information
- **data.periods[].shots[].team_id** (string) - Team ID
- **data.periods[].shots[].x** (number) - X coordinate
- **data.periods[].shots[].y** (number) - Y coordinate
- **data.periods[].shots[].expected_goals** (number) - Expected goals
- **data.periods[].shots[].expected_goals_on_target** (number) - Expected goals on target
- **data.periods[].shots[].is_on_target** (boolean) - Whether shot is on target
- **data.periods[].shots[].goal_crossed_y** (number) - Goal crossed Y coordinate
- **data.periods[].shots[].goal_crossed_z** (number) - Goal crossed Z coordinate
- **data.periods[].shots[].is_inside_box** (boolean) - Whether shot is inside box
- **data.periods[].shots[].shot_type** (string) - Shot type (e.g., RightFoot)
- **data.periods[].shots[].situation** (string) - Situation (e.g., RegularPlay)
- **data.periods[].shots[].minute** (integer) - Minute of shot
- **data.periods[].shots[].event_type** (string) - Event type (e.g., Goal)

#### Response Example
```
{
  "data": {
    "match_id": "m_B8x2K9",
    "periods": [
      {
        "period": "FirstHalf",
        "shots": [
          {
            "id": "s_Q1pR6z",
            "player": {
              "id": "p_7YtX4q",
              "name": "E. Haaland",
              "position_id": 4,
              "image_url": "https://cdn.pitchapi.dev/players/994226.webp"
            },
            "team_id": "t_9aB2xQ",
            "x": 88.5,
            "y": 42.3,
            "expected_goals": 0.38,
            "expected_goals_on_target": 0.32,
            "is_on_target": true,
            "goal_crossed_y": 35.98,
            "goal_crossed_z": 0.8,
            "is_inside_box": true,
            "shot_type": "RightFoot",
            "situation": "RegularPlay",
            "minute": 34,
            "event_type": "Goal"
          }
        ]
      }
    ]
  }
}
```
```

--------------------------------

### GET /v1/leagues

Source: https://pitchapi.dev/

Lists all leagues in the catalogue, each with available seasons. The is_free flag is always true and is kept for backward compatibility.

```APIDOC
## GET /v1/leagues

### Description
Lists all leagues in the catalogue, each with available seasons. The is_free flag is always true and is kept for backward compatibility.

### Method
GET

### Endpoint
/v1/leagues

### Parameters
#### Headers
- **X-API-KEY** (string) - Required - API key for authentication.

### Request Example
```
curl https://api.pitchapi.dev/v1/leagues \
  -H "X-API-KEY: $PITCH_KEY"
```

### Response
#### Success Response (200)
- **data.leagues** (array) - List of leagues.
  - **id** (string) - League ID.
  - **name** (string) - League name.
  - **country_code** (string) - Country code.
  - **image_url** (string) - URL to league image.
  - **seasons** (array of strings) - Available seasons.
  - **is_free** (boolean) - Always true.

#### Response Example
```
{
  "data": {
    "leagues": [
      {
        "id": "l_4Kd0Wq",
        "name": "Premier League",
        "country_code": "ENG",
        "image_url": "https://cdn.pitchapi.dev/leagues/47.webp",
        "seasons": ["2025/2026", "2024/2025"],
        "is_free": true
      }
    ]
  }
}
```
```