World Cup 2026 API

Welcome to the BALLDONTLIE World Cup 2026 API, your premier source for FIFA World Cup 2026 data. This API provides comprehensive coverage of the 2026 FIFA World Cup including teams, stadiums, matches, standings, betting odds, and futures. An API key is required. You can obtain an API key by creating a free account on our website. Read the authentication section to learn how to use the API key.

Take a look at our other APIs.

Join us on discord.

AI-Powered Integration

Using the OpenAPI Specification with AI

Our complete OpenAPI specification allows AI assistants to automatically understand and interact with our API. Simply share the spec URL with your AI assistant and describe what you want to build—the AI will handle the technical implementation.

Getting Started with AI:

Copy this URL: https://www.balldontlie.io/openapi.yml
Share it with your preferred AI assistant (ChatGPT, Claude, Gemini, etc.)
Tell the AI what you want to build (e.g., "Create a dashboard showing World Cup 2026 matches")
The AI will read the OpenAPI spec and write the code for you

Example prompts to try:

"Using the OpenAPI spec at https://www.balldontlie.io/openapi.yml, show me how to get World Cup 2026 team information"
"Read the BALLDONTLIE OpenAPI spec and create a Python script that fetches World Cup 2026 matches"
"Help me understand the available World Cup 2026 endpoints from this OpenAPI spec: https://www.balldontlie.io/openapi.yml"

This makes it incredibly easy for non-technical users, analysts, and researchers to leverage our World Cup 2026 data without needing to learn programming from scratch.

Account Tiers

There are three different account tiers which provide you access to different types of data. Visit our website to create an account for free.

Paid tiers do not apply across sports. The tier you purchase for World Cup 2026 will not automatically be applied to other sports. You can purchase the ALL-ACCESS ($159.99/mo) tier to get access to every endpoint for every sport.

Read the table below to see the breakdown.

Endpoint	Free	ALL-STAR	GOAT
Teams	Yes	Yes	Yes
Stadiums	Yes	Yes	Yes
Group Standings	No	Yes	Yes
Matches	No	No	Yes
Odds	No	No	Yes
Futures	No	No	Yes

The feature breakdown per tier is shown in the table below.

Tier	Requests / Min	$USD / mo.
GOAT	600	39.99
ALL-STAR	60	9.99
Free	5	0

Authentication

To authorize, use this code:

curl "api_endpoint_here" -H "Authorization: YOUR_API_KEY"

const response = await fetch(
  "https://api.balldontlie.io/fifa/worldcup/v1/teams",
  {
    headers: {
      Authorization: "YOUR_API_KEY",
    },
  }
);
const data = await response.json();
console.log(data);

import requests

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

if response.status_code == 200:
    data = response.json()
    print(data)
else:
    print(f'Error: {response.status_code}')

Make sure to replace YOUR_API_KEY with your API key.

BALLDONTLIE uses API keys to allow access to the API. You can obtain an API key by creating a free account at our website

We expect the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: YOUR_API_KEY

You must replace YOUR_API_KEY with your personal API key.

Errors

The API uses the following error codes:

Error Code	Meaning
401	Unauthorized - You either need an API key or your account tier does not have access to the endpoint.
400	Bad Request -- The request is invalid. The request parameters are probably incorrect.
404	Not Found -- The specified resource could not be found.
406	Not Acceptable -- You requested a format that isn't json.
429	Too Many Requests -- You're rate limited.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Teams

Get All Teams

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

const response = await fetch(
  "https://api.balldontlie.io/fifa/worldcup/v1/teams",
  {
    headers: {
      Authorization: "YOUR_API_KEY",
    },
  }
);
const data = await response.json();
console.log(data);

import requests

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

if response.status_code == 200:
    teams = response.json()['data']
    for team in teams:
        print(f"{team['name']} ({team['abbreviation']})")

The above command returns JSON structured like this:

{
  "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"
    }
    ...
  ]
}

This endpoint retrieves all World Cup 2026 participating nations.

HTTP Request

GET https://api.balldontlie.io/fifa/worldcup/v1/teams

Response Fields

Field	Type	Description
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)

Stadiums

Get All Stadiums

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

const response = await fetch(
  "https://api.balldontlie.io/fifa/worldcup/v1/stadiums",
  {
    headers: {
      Authorization: "YOUR_API_KEY",
    },
  }
);
const data = await response.json();
console.log(data);

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']}")

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 13,
      "name": "Atlanta Stadium",
      "city": "Atlanta",
      "country": "USA"
    },
    {
      "id": 8,
      "name": "BC Place Vancouver",
      "city": "Vancouver",
      "country": "CAN"
    },
    {
      "id": 7,
      "name": "Boston Stadium",
      "city": "Boston",
      "country": "USA"
    },
    ...
  ]
}

This endpoint retrieves all World Cup 2026 host stadiums across the United States, Canada, and Mexico.

HTTP Request

GET https://api.balldontlie.io/fifa/worldcup/v1/stadiums

Response Fields

Field	Type	Description
id	int	Stadium ID
name	string	Stadium name
city	string	Host city
country	string	Country code

Group Standings

Get Group Standings

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

const response = await fetch(
  "https://api.balldontlie.io/fifa/worldcup/v1/group_standings",
  {
    headers: {
      Authorization: "YOUR_API_KEY",
    },
  }
);
const data = await response.json();
console.log(data);

import requests

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

if response.status_code == 200:
    standings = response.json()['data']
    for standing in standings:
        print(f"{standing['group']['name']}: {standing['team']['name']} - {standing['points']} pts")

The above command returns JSON structured like this:

{
  "data": [
    {
      "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
    },
    {
      "team": {
        "id": 24,
        "name": "South Africa",
        "abbreviation": "RSA",
        "country_code": "RSA",
        "confederation": "CAF"
      },
      "group": {
        "id": 1,
        "name": "Group A"
      },
      "position": 2,
      "played": 0,
      "won": 0,
      "drawn": 0,
      "lost": 0,
      "goals_for": 0,
      "goals_against": 0,
      "goal_difference": 0,
      "points": 0
    }
    ...
  ]
}

This endpoint retrieves World Cup 2026 group stage standings. Requires ALL-STAR tier or higher.

HTTP Request

GET https://api.balldontlie.io/fifa/worldcup/v1/group_standings

Response Fields

Field	Type	Description
team	object	Team object
group	object	Group object (id, name)
position	int	Position within the group
played	int	Games played
won	int	Games won
drawn	int	Games drawn
lost	int	Games lost
goals_for	int	Goals scored
goals_against	int	Goals conceded
goal_difference	int	Goal difference
points	int	Total points

Matches

Get All Matches

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

const response = await fetch(
  "https://api.balldontlie.io/fifa/worldcup/v1/matches",
  {
    headers: {
      Authorization: "YOUR_API_KEY",
    },
  }
);
const data = await response.json();
console.log(data);

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}")

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 1,
      "match_number": 1,
      "datetime": "2026-06-11T15:00:00.000Z",
      "status": "scheduled",
      "stage": {
        "id": 7,
        "name": "First Stage",
        "order": 1
      },
      "group": {
        "id": 1,
        "name": "Group A"
      },
      "stadium": {
        "id": 1,
        "name": "Mexico City Stadium",
        "city": "Mexico City",
        "country": "MEX"
      },
      "home_team": {
        "id": 8,
        "name": "Mexico",
        "abbreviation": "MEX",
        "country_code": "MEX",
        "confederation": "CONCACAF"
      },
      "away_team": {
        "id": 24,
        "name": "South Africa",
        "abbreviation": "RSA",
        "country_code": "RSA",
        "confederation": "CAF"
      },
      "home_team_source": null,
      "away_team_source": null,
      "home_score": null,
      "away_score": null,
      "home_score_penalties": null,
      "away_score_penalties": null
    },
    {
      "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
    },
    ...
  ]
}

This endpoint retrieves all World Cup 2026 matches including group stage and knockout rounds.

HTTP Request

GET https://api.balldontlie.io/fifa/worldcup/v1/matches

Response Fields

Field	Type	Description
id	int	Match ID
match_number	int	Official match number
datetime	string	Match date and time in UTC
status	string	Match status (scheduled, in_progress, completed, postponed, cancelled)
stage	object	Stage object (id, name, order)
group	object	Group object (null for knockout matches)
stadium	object	Stadium object
home_team	object	Home team (null if TBD in knockout stage)
away_team	object	Away team (null if TBD in knockout stage)
home_team_source	object	Source info when home team is TBD
away_team_source	object	Source info when away team is TBD
home_score	int	Home team score (null if not started)
away_score	int	Away team score (null if not started)
home_score_penalties	int	Home team penalty shootout score (null if no shootout)
away_score_penalties	int	Away team penalty shootout score (null if no shootout)

Team Source Object

For knockout matches where teams are not yet determined, the home_team_source or away_team_source provides information about how the team will be determined:

Field	Type	Description
type	string	Source type (group_1st, group_2nd, winner, loser, etc.)
source_match_id	int	ID of the match that determines this team
source_match_number	int	Match number that determines this team
source_group_id	int	ID of the group (for group placement sources)
source_group_name	string	Group name (e.g., "A", "B")
placeholder	string	Placeholder text
description	string	Human-readable description (e.g., "Winner of Match 49")

Understanding Knockout Match Data

The World Cup 2026 includes 104 matches total. Before the knockout rounds begin, many matches will have home_team and/or away_team set to null because the participating teams have not yet been determined. You can construct the knockout bracket in addition to the group stages with this data.

How to interpret the data:

Check if teams are determined: If home_team or away_team is null, the team has not yet qualified for that match.
Use the source object: When a team is null, look at the corresponding home_team_source or away_team_source object to understand how the team will be determined.
Source types explained:

group_1st - Winner of a group (check source_group_name for which group)
group_2nd - Runner-up of a group (check source_group_name for which group)
group_3rd - Third place finisher from a group
winner - Winner of a previous match (check source_match_id or source_match_number)
loser - Loser of a previous match (used for third-place playoff)

Display placeholder text: Use the description field for a human-readable label (e.g., "Winner of Group A" or "Winner of Match 49").

Odds

Get Betting Odds

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

const response = await fetch(
  "https://api.balldontlie.io/fifa/worldcup/v1/odds",
  {
    headers: {
      Authorization: "YOUR_API_KEY",
    },
  }
);
const data = await response.json();
console.log(data);

import requests

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

if response.status_code == 200:
    odds = response.json()['data']
    for odd in odds:
        print(f"Match {odd['match_id']}: Home {odd['moneyline_home_odds']}, Draw {odd['moneyline_draw_odds']}, Away {odd['moneyline_away_odds']}")

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 37515873,
      "match_id": 10,
      "vendor": "caesars",
      "moneyline_home_odds": -115,
      "moneyline_away_odds": 320,
      "moneyline_draw_odds": 250,
      "updated_at": "2025-12-18T20:39:00.295Z"
    },
    {
      "id": 37515874,
      "match_id": 11,
      "vendor": "caesars",
      "moneyline_home_odds": 230,
      "moneyline_away_odds": 130,
      "moneyline_draw_odds": 210,
      "updated_at": "2025-12-18T20:39:00.295Z"
    }
    ...
  ]
}

This endpoint retrieves betting odds for World Cup 2026 matches.

Available vendors: DraftKings, FanDuel, Caesars

HTTP Request

GET https://api.balldontlie.io/fifa/worldcup/v1/odds

Response Fields

Field	Type	Description
id	int	Odds ID
match_id	int	Match ID
vendor	string	Sportsbook vendor
moneyline_home_odds	int	Home team moneyline odds
moneyline_away_odds	int	Away team moneyline odds
moneyline_draw_odds	number	Draw moneyline odds
updated_at	string	Last update timestamp

Futures

Get Futures Odds

curl "https://api.balldontlie.io/fifa/worldcup/v1/odds/futures" \
  -H "Authorization: YOUR_API_KEY"

const response = await fetch(
  "https://api.balldontlie.io/fifa/worldcup/v1/odds/futures",
  {
    headers: {
      Authorization: "YOUR_API_KEY",
    },
  }
);
const data = await response.json();
console.log(data);

import requests

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

if response.status_code == 200:
    futures = response.json()['data']
    for future in futures:
        print(f"{future['subject']['name']}: {future['american_odds']} ({future['market_name']})")

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": 1297,
      "market_type": "finish_bottom",
      "market_name": "Group G",
      "subject": {
        "id": 41,
        "name": "New Zealand",
        "abbreviation": "NZL",
        "country_code": "NZL",
        "confederation": "OFC"
      },
      "vendor": "draftkings",
      "american_odds": -185,
      "decimal_odds": 1.5405,
      "updated_at": "2025-12-18T15:12:26.494Z"
    },
    {
      "id": 1283,
      "market_type": "finish_bottom",
      "market_name": "Group C",
      "subject": {
        "id": 44,
        "name": "Scotland",
        "abbreviation": "SCO",
        "country_code": "SCO",
        "confederation": "UEFA"
      },
      "vendor": "draftkings",
      "american_odds": 500,
      "decimal_odds": 6,
      "updated_at": "2025-12-18T15:12:26.494Z"
    }
    ...
  ]
}

This endpoint retrieves futures betting odds for World Cup 2026 (e.g., tournament winner odds).

Available vendors: DraftKings, FanDuel, Caesars

HTTP Request

GET https://api.balldontlie.io/fifa/worldcup/v1/odds/futures

Response Fields

Field	Type	Description
id	int	Futures odds ID
market_type	string	Type of futures market
market_name	string	Name of the futures market
subject	object	Team object the odds are for
vendor	string	Sportsbook vendor
american_odds	int	American odds format
decimal_odds	number	Decimal odds format
updated_at	string	Last update timestamp

Market Types

Market Type	Description
outright	Tournament winner
group_winner	Win their group
qualify_from_group	Advance from group stage
finish_bottom	Finish last in their group
win_all_group_games	Win all three group stage matches
to_reach_quarters	Advance to the quarterfinals
to_reach_semis	Advance to the semifinals
to_reach_final	Advance to the final
stage_of_elimination	Stage at which a team will be eliminated