BALLDONTLIE World Cup 2026 API

https://fifa.balldontlie.io/
Admin
The BALLDONTLIE World Cup 2026 API provides comprehensive data for the FIFA World Cup 2026,...
Tokens:36,900
Snippets:180
Trust Score:3.9
Update:4 months ago
Show doc for...
Tokens:
Raw
### Get Match Lineups

Source: https://fifa.balldontlie.io/#world-cup-2026-api

Retrieve the starting and substitute players for a specific match. This is useful for understanding team formations and player roles in a given game.

```curl
curl "https://api.balldontlie.io/fifa/worldcup/v1/match_lineups?match_ids[]=1"
  -H "Authorization: YOUR_API_KEY"
```

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

### Example Match Lineup Response

Source: https://fifa.balldontlie.io/

Example JSON response structure for a match lineup query, detailing player participation and position within a specific match.

```json
{
  "data": [
    {
      "match_id": 1,
      "team_id": 8,
      "player": {
        "id": 142,
        "name": "Christian Pulisic",
        "short_name": "C. Pulisic",
        "position": "M",
        "date_of_birth": "1998-09-18T00:00:00.000Z",
        "country_code": "USA",
        "country_name": "United States",
        "height_cm": 172,
        "jersey_number": "10"
      },
      "is_starter": true,
      "is_substitute": false,
      "shirt_number": 10,
      "position": "AM",
      "formation": "4-3-3"
    }
  ],
  "meta": { "next_cursor": 100, "per_page": 25 }
}
```

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

### Example Tournament Roster Response

Source: https://fifa.balldontlie.io/

Example JSON response structure for a tournament roster query, showing player details and their tournament statistics.

```json
{
  "data": [
    {
      "season": { "id": 1, "year": 2026 },
      "team_id": 12,
      "player": {
        "id": 142,
        "name": "Christian Pulisic",
        "short_name": "C. Pulisic",
        "position": "M",
        "date_of_birth": "1998-09-18T00:00:00.000Z",
        "country_code": "USA",
        "country_name": "United States",
        "height_cm": 172,
        "jersey_number": "10"
      },
      "position": "M",
      "appearances": 4,
      "starts": 4,
      "minutes_played": 360,
      "goals": 2,
      "assists": 1,
      "yellow_cards": 1,
      "red_cards": 0,
      "avg_rating": 7.6
    }
  ],
  "meta": { "next_cursor": 200, "per_page": 25 }
}
```

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

### Example JSON Response for Teams Endpoint

Source: https://fifa.balldontlie.io/

This is an example of the JSON structure returned by the 'Get All Teams' endpoint, showing details for each participating nation.

```json
{
  "data": [
    {
      "id": 13,
      "name": "Algeria",
      "abbreviation": "ALG",
      "country_code": "ALG",
      "confederation": "CAF"
    },
    {
      "id": 1,
      "name": "Argentina",
      "abbreviation": "ARG",
      "country_code": "ARG",
      "confederation": "CONMEBOL"
    },
    {
      "id": 25,
      "name": "Australia",
      "abbreviation": "AUS",
      "country_code": "AUS",
      "confederation": "AFC"
    }
    ...
  ]
}
```

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

### Get Match Lineups

Source: https://fifa.balldontlie.io/

Retrieve the registered match-day squad for one or more matches. This includes starters and bench players.

```bash
curl "https://api.balldontlie.io/fifa/worldcup/v1/match_lineups?match_ids[]=1" \
  -H "Authorization: YOUR_API_KEY"
```

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

### Get Match Lineups

Source: https://fifa.balldontlie.io/

Returns the registered match-day squad (starters + bench) for one or more matches.

```APIDOC
## Get Match Lineups

### Description
Returns the registered match-day squad (starters + bench) for one or more matches.

### HTTP Request
`GET https://api.balldontlie.io/fifa/worldcup/v1/match_lineups`

### Query Parameters
#### Path Parameters
- **match_ids[]** (int[]) - Optional. Filter to specific match IDs.
- **team_ids[]** (int[]) - Optional. Filter to specific team IDs.
- **per_page** (int) - Optional. Page size, max 100. Default 25.
- **cursor** (int) - Optional. Cursor for the next page.

### Response Fields
#### Success Response (200)
- **match_id** (int) - Match ID
- **team_id** (int) - Team ID
- **player** (object) - Full player object
- **is_starter** (boolean) - Whether the player started the match
- **is_substitute** (boolean) - Whether the player was on the bench
- **shirt_number** (int) - Shirt number worn for this match
- **position** (string) - Position code for this match (nullable)
- **formation** (string) - Team formation, e.g. "4-3-3" (nullable)
```

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

### Match Shots Response Example

Source: https://fifa.balldontlie.io/

Example JSON response for match shots. Includes shot details like player, team, shot type, and expected goals. Coordinates and xg/xgot are available for 2022/2026 matches.

```json
{
  "data": [
    {
      "id": 5073,
      "match_id": 1030,
      "player_id": 8760,
      "team_id": 20,
      "is_home": false,
      "shot_type": "goal",
      "situation": "penalty",
      "body_part": "right-foot",
      "goal_type": "penalty",
      "xg": 0.7884,
      "xgot": 0.9937,
      "player_x": 11.5,
      "player_y": 50,
      "goal_mouth_x": 0,
      "goal_mouth_y": 46,
      "block_x": null,
      "block_y": null,
      "time_minute": 16,
      "added_time": null,
      "time_seconds": 949
    }
  ],
  "meta": { "next_cursor": 5073, "per_page": 25 }
}
```

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

### Example API Response Structure

Source: https://fifa.balldontlie.io/

This is an example of the JSON structure returned by the API for a completed match and a scheduled match. It includes details about teams, scores, stages, and stadiums.

```json
{
  "data": [
    {
      "id": 1030,
      "match_number": 1,
      "datetime": "2022-11-20T16:00:00.000Z",
      "status": "completed",
      "season": { "id": 2, "year": 2022 },
      "stage": { "id": 24, "name": "Group Stage", "order": 1 },
      "group": { "id": 1, "name": "Group A" },
      "stadium": {
        "id": 476,
        "name": "Al Bayt Stadium",
        "city": "Al Khor",
        "country": "QAT",
        "capacity": 60000,
        "latitude": 51.31667,
        "longitude": 25.76667
      },
      "home_team": {
        "id": 7,
        "name": "Qatar",
        "abbreviation": "QAT",
        "country_code": "QAT",
        "confederation": "AFC"
      },
      "away_team": {
        "id": 20,
        "name": "Ecuador",
        "abbreviation": "ECU",
        "country_code": "ECU",
        "confederation": "CONMEBOL"
      },
      "home_team_source": null,
      "away_team_source": null,
      "home_score": 0,
      "away_score": 2,
      "home_score_penalties": null,
      "away_score_penalties": null,
      "first_half_home_score": 0,
      "first_half_away_score": 2,
      "second_half_home_score": 0,
      "second_half_away_score": 0,
      "extra_time_home_score": null,
      "extra_time_away_score": null,
      "has_extra_time": false,
      "has_penalty_shootout": false,
      "round_number": 1,
      "round_name": null,
      "home_formation": "5-3-2",
      "away_formation": "4-4-2",
      "referee": {
        "id": 168,
        "name": "Daniele Orsato",
        "country_code": "ITA",
        "country_name": "Italy"
      },
      "home_manager": {
        "id": 369,
        "name": "Félix Sánchez",
        "short_name": "F. Sánchez"
      },
      "away_manager": {
        "id": 372,
        "name": "Gustavo Alfaro",
        "short_name": "G. Alfaro"
      }
    },
    {
      "id": 73,
      "match_number": 73,
      "datetime": "2026-06-28T15:00:00.000Z",
      "status": "scheduled",
      "stage": {
        "id": 6,
        "name": "Round of 32",
        "order": 2
      },
      "group": null,
      "stadium": {
        "id": 4,
        "name": "Los Angeles Stadium",
        "city": "Los Angeles",
        "country": "USA"
      },
      "home_team": null,
      "away_team": null,
      "home_team_source": {
        "type": "group_2nd",
        "source_match_id": null,
        "source_match_number": null,
        "source_group_id": 1,
        "source_group_name": "Group A",
        "placeholder": "2A",
        "description": "2nd place in Group Group A"
      },
      "away_team_source": {
        "type": "group_2nd",
        "source_match_id": null,
        "source_match_number": null,
        "source_group_id": 2,
        "source_group_name": "Group B",
        "placeholder": "2B",
        "description": "2nd place in Group Group B"
      },
      "home_score": null,
      "away_score": null,
      "home_score_penalties": null,
      "away_score_penalties": null
    },
    ...
  ]
}
```

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

### Example JSON Response for Stadiums

Source: https://fifa.balldontlie.io/

This is an example of the JSON structure returned when requesting stadium data. It includes details like stadium name, city, country, and capacity.

```json
{
  "data": [
    {
      "id": 13,
      "name": "Atlanta Stadium",
      "city": "Atlanta",
      "country": "USA",
      "capacity": 71000,
      "latitude": 33.7553,
      "longitude": -84.4006
    },
    {
      "id": 8,
      "name": "BC Place Vancouver",
      "city": "Vancouver",
      "country": "CAN",
      "capacity": 54500,
      "latitude": 49.2767,
      "longitude": -123.1119
    }
    ...
  ]
}
```

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

### Get All Matches (cURL)

Source: https://fifa.balldontlie.io/

Use this cURL command to fetch all World Cup matches. Replace 'YOUR_API_KEY' with your actual API key.

```bash
curl "https://api.balldontlie.io/fifa/worldcup/v1/matches" \
  -H "Authorization: YOUR_API_KEY"
```

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

### Team Match Stats Response Example

Source: https://fifa.balldontlie.io/

Example JSON response for team match statistics. Fields include match and team identifiers, possession percentage, expected goals, and various shot and pass metrics.

```json
{
  "data": [
    {
      "match_id": 1,
      "team_id": 8,
      "is_home": true,
      "possession_pct": 60,
      "expected_goals": 1.42,
      "big_chances": 3,
      "big_chances_missed": 1,
      "shots_total": 14,
      "shots_on_target": 6,
      "shots_off_target": 5,
      "shots_blocked": 3,
      "shots_inside_box": 9,
      "shots_outside_box": 5,
      "hit_woodwork": 0,
      "corners": 6,
      "offsides": 2,
      "fouls": 10,
      "yellow_cards": 1,
      "passes_total": 500,
      "passes_accurate": 440,
      "passes_final_third": 80,
      "long_balls_total": 30,
      "long_balls_accurate": 18,
      "crosses_total": 12,
      "crosses_accurate": 4,
      "tackles": 16,
      "interceptions": 9,
      "clearances": 11,
      "saves": 3,
      "ground_duels_won": 25,
      "ground_duels_total": 50,
      "aerial_duels_won": 10,
      "aerial_duels_total": 18,
      "dribbles_completed": 8,
      "dribbles_total": 14,
      "throw_ins": 22,
      "goal_kicks": 6,
      "free_kicks": 14
    }
  ],
  "meta": { "next_cursor": 200, "per_page": 25 }
}
```

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

### Get All Stadiums using cURL

Source: https://fifa.balldontlie.io/

Use this command to fetch a list of all stadiums used in the World Cup. Replace 'YOUR_API_KEY' with your actual API key.

```bash
curl "https://api.balldontlie.io/fifa/worldcup/v1/stadiums" \
  -H "Authorization: YOUR_API_KEY"
```

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

### Get Match Team Form

Source: https://fifa.balldontlie.io/

Use this command to retrieve the form summary for a specific match. Replace 'YOUR_API_KEY' with your actual API key.

```shell
curl "https://api.balldontlie.io/fifa/worldcup/v1/match_team_form?match_ids[]=1" \
  -H "Authorization: YOUR_API_KEY"
```

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

### Get All Stadiums using Python Requests

Source: https://fifa.balldontlie.io/

This Python code uses the 'requests' library to get stadium information. Remember to substitute 'YOUR_API_KEY' with your key.

```python
import requests

response = requests.get(
    'https://api.balldontlie.io/fifa/worldcup/v1/stadiums',
    headers={'Authorization': 'YOUR_API_KEY'}
)

if response.status_code == 200:
    stadiums = response.json()['data']
    for stadium in stadiums:
        print(f"{stadium['name']} - {stadium['city']}")
```

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

### Get Tournament Rosters

Source: https://fifa.balldontlie.io/

Retrieve the per-tournament squad for a specific team. This includes cumulative tournament stats for each player.

```bash
curl "https://api.balldontlie.io/fifa/worldcup/v1/rosters?team_ids[]=12" \
  -H "Authorization: YOUR_API_KEY"
```

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

### Get All Matches (Python Requests)

Source: https://fifa.balldontlie.io/

Retrieve all World Cup matches using the Python Requests library. Remember to substitute 'YOUR_API_KEY' with your key.

```python
import requests

response = requests.get(
    'https://api.balldontlie.io/fifa/worldcup/v1/matches',
    headers={'Authorization': 'YOUR_API_KEY'}
)

if response.status_code == 200:
    matches = response.json()['data']
    for match in matches:
        home = match['home_team']['name'] if match['home_team'] else 'TBD'
        away = match['away_team']['name'] if match['away_team'] else 'TBD'
        print(f"{home} vs {away}")
```

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

### Get Player Match Stats

Source: https://fifa.balldontlie.io/

Fetch per-player performance statistics for a given match. You can filter by `match_ids[]`, `player_ids[]`, or `team_ids[]`.

```bash
curl "https://api.balldontlie.io/fifa/worldcup/v1/player_match_stats?match_ids[]=1" \
  -H "Authorization: YOUR_API_KEY"
```

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

### Sample Betting Odds JSON Response

Source: https://fifa.balldontlie.io/

This is an example of the JSON structure returned by the betting odds endpoint, showing details for different vendors and markets.

```json
{
  "data": [
    {
      "id": 236503332,
      "match_id": 1,
      "vendor": "fanduel",
      "moneyline_home_odds": -270,
      "moneyline_away_odds": 700,
      "moneyline_draw_odds": 350,
      "spread_home_value": null,
      "spread_home_odds": null,
      "spread_away_value": null,
      "spread_away_odds": null,
      "total_value": null,
      "total_over_odds": null,
      "total_under_odds": null,
      "updated_at": "2026-06-03T23:00:37.273Z",
      "markets": [
        {
          "id": 222,
          "key": "spread_match_away_team_away_2_way_spread_away_team_-1.5_goals_-1.5",
          "name": "2 Way Spread Away Team -1.5 Goals",
          "type": "spread",
          "period": "match",
          "scope": "away_team",
          "team_side": "away",
          "line_value": "-1.5",
          "updated_at": "2026-06-03T23:00:37.273Z",
          "outcomes": [
            {
              "id": 1354,
              "key": "other_mexico_+1.5_goals_-1.5",
              "name": "Mexico +1.5 Goals",
              "type": "other",
              "side": null,
              "line_value": "-1.5",
              "handicap": "-1.5",
              "american_odds": -8000,
              "decimal_odds": 1.0125,
              "updated_at": "2026-06-03T23:00:37.273Z"
            },
            {
              "id": 1355,
              "key": "other_south_africa_-1.5_goals_-1.5",
              "name": "South Africa -1.5 Goals",
              "type": "other",
              "side": null,
              "line_value": "-1.5",
              "handicap": "-1.5",
              "american_odds": 1420,
              "decimal_odds": 15.2,
              "updated_at": "2026-06-03T23:00:37.273Z"
            }
          ]
        },
        {
          "id": 215,
          "key": "total_match_match_over/under_1.5_goals_1.5",
          "name": "Over/Under 1.5 Goals",
          "type": "total",
          "period": "match",
          "scope": "match",
          "team_side": null,
          "line_value": "1.5",
          "updated_at": "2026-06-03T23:00:37.273Z",
          "outcomes": [
            {
              "id": 1263,
              "key": "over_over_1.5_goals_1.5",
              "name": "Over 1.5 Goals",
              "type": "over",
              "side": null,
              "line_value": "1.5",
              "handicap": null,
              "american_odds": -310,
              "decimal_odds": 1.322581,
              "updated_at": "2026-06-03T23:00:37.273Z"
            },
            {
              "id": 1264,
              "key": "under_under_1.5_goals_1.5",
              "name": "Under 1.5 Goals",
              "type": "under",
              "side": null,
              "line_value": "1.5",
              "handicap": null,
              "american_odds": 230,
              "decimal_odds": 3.3,
              "updated_at": "2026-06-03T23:00:37.273Z"
            }
          ]
        }
      ]
    },
    {
      "id": 236503364,
      "match_id": 1,
      "vendor": "draftkings",
      "moneyline_home_odds": -225,
      "moneyline_away_odds": 700,
      "moneyline_draw_odds": 340,
      "spread_home_value": null,
      "spread_home_odds": null,
      "spread_away_value": null,
      "spread_away_odds": null,
      "total_value": null,
      "total_over_odds": null,
      "total_under_odds": null,
      "updated_at": "2026-06-03T23:00:33.918Z",
      "markets": [
        {
          "id": 14412,
          "key": "double_chance_match_match_double_chance",
          "name": "Double Chance",
          "type": "double_chance",
          "period": "match",
          "scope": "match",
          "team_side": null,
          "line_value": null,
          "updated_at": "2026-06-03T23:00:33.918Z",
          "outcomes": [
            {
              "id": 76427,
              "key": "double_chance_mexico_or_tie",
              "name": "Mexico or Tie",
              "type": "double_chance",
              "side": null,
              "line_value": null,
              "handicap": null,
              "american_odds": -1100,
              "decimal_odds": 1.090909,
              "updated_at": "2026-06-03T23:00:33.918Z"
            },
            {
              "id": 76428,
              "key": "double_chance_south_africa_or_tie",
              "name": "South Africa or Tie",
              "type": "double_chance",
              "side": null,
              "line_value": null,
              "handicap": null,
              "american_odds": 300,
              "decimal_odds": 4.0,
              "updated_at": "2026-06-03T23:00:33.918Z"
            },
            {
              "id": 76429,
              "key": "double_chance_mexico_or_south_africa",
              "name": "Mexico or South Africa",
              "type": "double_chance",
              "side": null,
              "line_value": null,
              "handicap": null,
              "american_odds": -165,
              "decimal_odds": 1.606061,
              "updated_at": "2026-06-03T23:00:33.918Z"
            }
          ]
        }
      ]
    }
  ]
}
```

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

### Example JSON Response for Group Standings

Source: https://fifa.balldontlie.io/

This JSON structure represents the data returned for group standings, including team, group, and performance metrics.

```json
{
  "data": [
    {
      "season": { "id": 1, "year": 2026 },
      "team": {
        "id": 8,
        "name": "Mexico",
        "abbreviation": "MEX",
        "country_code": "MEX",
        "confederation": "CONCACAF"
      },
      "group": {
        "id": 1,
        "name": "Group A"
      },
      "position": 1,
      "played": 0,
      "won": 0,
      "drawn": 0,
      "lost": 0,
      "goals_for": 0,
      "goals_against": 0,
      "goal_difference": 0,
      "points": 0
    }
    ...
  ]
}
```

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

### Search Players (cURL)

Source: https://fifa.balldontlie.io/

This cURL command searches for players by name, using 'pulisic' as an example query. Remember to include your API key in the Authorization header.

```bash
curl "https://api.balldontlie.io/fifa/worldcup/v1/players?search=pulisic" \
  -H "Authorization: YOUR_API_KEY"
```

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

### Get All Teams with cURL

Source: https://fifa.balldontlie.io/

Retrieve all participating nations for the World Cup by making a GET request to the teams endpoint with your API key.

```bash
curl "https://api.balldontlie.io/fifa/worldcup/v1/teams" \
  -H "Authorization: YOUR_API_KEY"
```

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

### Fetch FIFA World Cup Matches using OpenAPI and Python

Source: https://fifa.balldontlie.io/#world-cup-2026-api

Generate a Python script to fetch FIFA World Cup matches by sharing the BALLDONTLIE OpenAPI spec URL with an AI assistant.

```text
Read the BALLDONTLIE OpenAPI spec and create a Python script that fetches FIFA World Cup matches
```

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

### Get FIFA World Cup Team Information using OpenAPI

Source: https://fifa.balldontlie.io/#world-cup-2026-api

Use this prompt with an AI assistant to retrieve FIFA World Cup team data by providing the OpenAPI specification URL.

```text
Using the OpenAPI spec at https://www.balldontlie.io/openapi/fifa.yml, show me how to get FIFA World Cup team information
```

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

### Get All Teams

Source: https://fifa.balldontlie.io/

Retrieves all participating nations for the requested World Cup edition(s). Defaults to 2026 when `seasons[]` is omitted.

```APIDOC
## GET /fifa/worldcup/v1/teams

### Description
Retrieves all participating nations for the requested World Cup edition(s). Defaults to 2026 when `seasons[]` is omitted.

### Method
GET

### Endpoint
https://api.balldontlie.io/fifa/worldcup/v1/teams

### Query Parameters
#### Query Parameters
- **seasons[]** (int[]) - Optional - World Cup years to include. Allowed: `2018`, `2022`, `2026`. Default: `[2026]`.

### Response
#### Success Response (200)
- **id** (int) - Team ID
- **name** (string) - Full country name
- **abbreviation** (string) - Three-letter country code (e.g., USA, BRA, GER)
- **country_code** (string) - ISO country code
- **confederation** (string) - FIFA confederation (UEFA, CONMEBOL, CONCACAF, CAF, AFC, OFC)

### Response Example
```json
{
  "data": [
    {
      "id": 13,
      "name": "Algeria",
      "abbreviation": "ALG",
      "country_code": "ALG",
      "confederation": "CAF"
    },
    {
      "id": 1,
      "name": "Argentina",
      "abbreviation": "ARG",
      "country_code": "ARG",
      "confederation": "CONMEBOL"
    },
    {
      "id": 25,
      "name": "Australia",
      "abbreviation": "AUS",
      "country_code": "AUS",
      "confederation": "AFC"
    }
    ...
  ]
}
```
```

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

### Example Betting Odds Data

Source: https://fifa.balldontlie.io/

This snippet shows the structure of betting odds data, including market details like odds and updated timestamps. It illustrates different market types such as 'double_chance'.

```json
{
  "id": 76428,
  "key": "double_chance_mexico_or_south_africa",
  "name": "Mexico or South Africa",
  "type": "double_chance",
  "side": null,
  "line_value": null,
  "handicap": null,
  "american_odds": -475,
  "decimal_odds": 1.210526,
  "updated_at": "2026-06-03T23:00:33.918Z"
}
{
  "id": 76429,
  "key": "double_chance_tie_or_south_africa",
  "name": "Tie or South Africa",
  "type": "double_chance",
  "side": null,
  "line_value": null,
  "handicap": null,
  "american_odds": 170,
  "decimal_odds": 2.7,
  "updated_at": "2026-06-03T23:00:33.918Z"
}
```

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

### Get Betting Odds

Source: https://fifa.balldontlie.io/

Fetches the betting odds for FIFA World Cup matches. Requires an API key for authentication.

```APIDOC
## GET /fifa/worldcup/v1/odds

### Description
Retrieves betting odds for FIFA World Cup matches.

### Method
GET

### Endpoint
https://api.balldontlie.io/fifa/worldcup/v1/odds

### Parameters
#### Headers
- **Authorization** (string) - Required - Your API key for authentication.

### Request Example
```bash
curl "https://api.balldontlie.io/fifa/worldcup/v1/odds" \
  -H "Authorization: YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **data** (array) - An array of betting odds objects.
  - **id** (integer) - Unique identifier for the odds entry.
  - **match_id** (integer) - The ID of the match.
  - **vendor** (string) - The name of the betting odds vendor.
  - **moneyline_home_odds** (integer) - The moneyline odds for the home team.
  - **moneyline_away_odds** (integer) - The moneyline odds for the away team.
  - **moneyline_draw_odds** (integer) - The moneyline odds for a draw.
  - **spread_home_value** (any) - The spread value for the home team (null if not applicable).
  - **spread_home_odds** (any) - The odds for the home team spread (null if not applicable).
  - **spread_away_value** (any) - The spread value for the away team (null if not applicable).
  - **spread_away_odds** (any) - The odds for the away team spread (null if not applicable).
  - **total_value** (any) - The total value for over/under bets (null if not applicable).
  - **total_over_odds** (any) - The odds for the over total (null if not applicable).
  - **total_under_odds** (any) - The odds for the under total (null if not applicable).
  - **updated_at** (string) - The timestamp when the odds were last updated.
  - **markets** (array) - An array of betting markets available for the match.
    - **id** (integer) - Unique identifier for the market.
    - **key** (string) - A unique key for the market.
    - **name** (string) - The name of the market.
    - **type** (string) - The type of market (e.g., 'spread', 'total').
    - **period** (string) - The period the market applies to (e.g., 'match').
    - **scope** (string) - The scope of the market (e.g., 'match', 'away_team').
    - **team_side** (any) - The team side the market applies to (null if not applicable).
    - **line_value** (any) - The line value for the market (e.g., spread or total line).
    - **updated_at** (string) - The timestamp when the market was last updated.
    - **outcomes** (array) - An array of outcomes within the market.
      - **id** (integer) - Unique identifier for the outcome.
      - **key** (string) - A unique key for the outcome.
      - **name** (string) - The name of the outcome.
      - **type** (string) - The type of outcome (e.g., 'other', 'over', 'under').
      - **side** (any) - The side the outcome applies to (null if not applicable).
      - **line_value** (any) - The line value for the outcome.
      - **handicap** (any) - The handicap for the outcome.
      - **american_odds** (integer) - The American odds for the outcome.
      - **decimal_odds** (float) - The decimal odds for the outcome.
      - **updated_at** (string) - The timestamp when the outcome was last updated.

#### Response Example
```json
{
  "data": [
    {
      "id": 236503332,
      "match_id": 1,
      "vendor": "fanduel",
      "moneyline_home_odds": -270,
      "moneyline_away_odds": 700,
      "moneyline_draw_odds": 350,
      "spread_home_value": null,
      "spread_home_odds": null,
      "spread_away_value": null,
      "spread_away_odds": null,
      "total_value": null,
      "total_over_odds": null,
      "total_under_odds": null,
      "updated_at": "2026-06-03T23:00:37.273Z",
      "markets": [
        {
          "id": 222,
          "key": "spread_match_away_team_away_2_way_spread_away_team_-1.5_goals_-1.5",
          "name": "2 Way Spread Away Team -1.5 Goals",
          "type": "spread",
          "period": "match",
          "scope": "away_team",
          "team_side": "away",
          "line_value": "-1.5",
          "updated_at": "2026-06-03T23:00:37.273Z",
          "outcomes": [
            {
              "id": 1354,
              "key": "other_mexico_+1.5_goals_-1.5",
              "name": "Mexico +1.5 Goals",
              "type": "other",
              "side": null,
              "line_value": "-1.5",
              "handicap": "-1.5",
              "american_odds": -8000,
              "decimal_odds": 1.0125,
              "updated_at": "2026-06-03T23:00:37.273Z"
            },
            {
              "id": 1355,
              "key": "other_south_africa_-1.5_goals_-1.5",
              "name": "South Africa -1.5 Goals",
              "type": "other",
              "side": null,
              "line_value": "-1.5",
              "handicap": "-1.5",
              "american_odds": 1420,
              "decimal_odds": 15.2,
              "updated_at": "2026-06-03T23:00:37.273Z"
            }
          ]
        },
        {
          "id": 215,
          "key": "total_match_match_over/under_1.5_goals_1.5",
          "name": "Over/Under 1.5 Goals",
          "type": "total",
          "period": "match",
          "scope": "match",
          "team_side": null,
          "line_value": "1.5",
          "updated_at": "2026-06-03T23:00:37.273Z",
          "outcomes": [
            {
              "id": 1263,
              "key": "over_over_1.5_goals_1.5",
              "name": "Over 1.5 Goals",
              "type": "over",
              "side": null,
              "line_value": "1.5",
              "handicap": null,
              "american_odds": -310,
              "decimal_odds": 1.322581,
              "updated_at": "2026-06-03T23:00:37.273Z"
            },
            {
              "id": 1264,
              "key": "under_under_1.5_goals_1.5",
              "name": "Under 1.5 Goals",
              "type": "under",
              "side": null,
              "line_value": "1.5",
              "handicap": null,
              "american_odds": 230,
              "decimal_odds": 3.3,
              "updated_at": "2026-06-03T23:00:37.273Z"
            }
          ]
        }
      ]
    },
    {
      "id": 236503364,
      "match_id": 1,
      "vendor": "draftkings",
      "moneyline_home_odds": -225,
      "moneyline_away_odds": 700,
      "moneyline_draw_odds": 340,
      "spread_home_value": null,
      "spread_home_odds": null,
      "spread_away_value": null,
      "spread_away_odds": null,
      "total_value": null,
      "total_over_odds": null,
      "total_under_odds": null,
      "updated_at": "2026-06-03T23:00:33.918Z",
      "markets": [
        {
          "id": 14412,
          "key": "double_chance_match_match_double_chance",
          "name": "Double Chance",
          "type": "double_chance",
          "period": "match",
          "scope": "match",
          "team_side": null,
          "line_value": null,
          "updated_at": "2026-06-03T23:00:33.918Z",
          "outcomes": [
            {
              "id": 76427,
              "key": "double_chance_mexico_or_tie",
              "name": "Mexico or Tie",
              "type": "double_chance",
              "side": null,
              "line_value": null,
              "handicap": null,
              "american_odds": -1100,
              "decimal_odds": 1.090909,
              "updated_at": "2026-06-03T23:00:33.918Z"
            }
          ]
        }
      ]
    }
  ]
}
```
```

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

### Player Props API Response Structure

Source: https://fifa.balldontlie.io/

This is an example of the JSON response structure you can expect when querying the Player Props API. It includes details for multiple prop instances for a given player and match.

```json
{
  "data": [
    {
      "id": 8489679587,
      "match_id": 10,
      "player_id": 557,
      "vendor": "draftkings",
      "prop_type": "anytime_goal",
      "line_value": "1",
      "market": {
        "type": "milestone",
        "odds": 1800
      },
      "updated_at": "2026-06-05T16:08:43.729Z"
    },
    {
      "id": 8489679635,
      "match_id": 10,
      "player_id": 557,
      "vendor": "draftkings",
      "prop_type": "anytime_goal",
      "line_value": "2",
      "market": {
        "type": "milestone",
        "odds": 25000
      },
      "updated_at": "2026-06-05T16:08:43.729Z"
    },
    {
      "id": 8489679721,
      "match_id": 10,
      "player_id": 557,
      "vendor": "draftkings",
      "prop_type": "anytime_goal",
      "line_value": "3",
      "market": {
        "type": "milestone",
        "odds": 80000
      },
      "updated_at": "2026-06-05T16:08:43.729Z"
    }
  ],
  "meta": {
    "per_page": 3
  }
}
```

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

### Get Match Best Players

Source: https://fifa.balldontlie.io/

Returns the top-rated players for each match, including the best XI per side and the man of the match.

```APIDOC
## GET /fifa/worldcup/v1/match_best_players

### Description
Returns the top-rated players for each match (best XI per side plus the man of the match).

### Method
GET

### Endpoint
https://api.balldontlie.io/fifa/worldcup/v1/match_best_players

### Query Parameters
#### Optional Parameters
- **match_ids[]** (int[]) - Filter to specific match IDs.
- **per_page** (int) - Page size, max 100. Default 25.
- **cursor** (int) - Cursor for the next page.

### Response Fields
#### Success Response (200)
- **match_id** (int) - Match ID
- **player_id** (int) - Player ID
- **team_id** (int) - Team ID
- **is_home** (boolean) - Whether the player was on the home side
- **side_rank** (int) - Rank within the player's side (1 = top)
- **is_man_of_match** (boolean) - Whether the player was named MOTM
- **rating** (number) - Match rating (nullable)
- **reason** (string) - Highlight summary (nullable)

### Request Example
```
curl "https://api.balldontlie.io/fifa/worldcup/v1/match_best_players?match_ids[]=1" \
  -H "Authorization: YOUR_API_KEY"
```

### Response Example
```json
{
  "data": [
    {
      "match_id": 1,
      "player_id": 142,
      "team_id": 8,
      "is_home": true,
      "side_rank": 1,
      "is_man_of_match": true,
      "rating": 9.1,
      "reason": "scored 1 goal, 3 key passes"
    }
  ],
  "meta": { "next_cursor": 200, "per_page": 25 }
}
```
```

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

### Get Match Events

Source: https://fifa.balldontlie.io/

Retrieve time-ordered events for a specific match, such as goals, cards, and substitutions. Use the `match_ids[]` parameter to filter.

```bash
curl "https://api.balldontlie.io/fifa/worldcup/v1/match_events?match_ids[]=1" \
  -H "Authorization: YOUR_API_KEY"
```
Tokens:
Raw