worldcup.json

July 1, 2026 · View on GitHub

Update - What's news?

Q: Updates for upcoming rounds?

A: sorry for the déjà vu. yes, your help is more than welcome to fill-in the teams once known for the round of 32/16/8 etc. please note - the datasets for the knock-out (k.o.) matches are (auto-)generated from the upstream text source here https://github.com/openfootball/worldcup/blob/master/2026--usa/cup_finals.txt

thanks to Dr. Chester Ismay (maker of World Cup Viewer¹) for the upstream (auto-filler) updates getting close to post-match live score updates here!

and thanks for your updates & corrections (old school) by hand.

¹: yes, you can. add your projects using worldcup.json on this page right here.

sorry for the slow start-up on day 1. good morning it was 9am here in austria when i checked in.
please note, the datasets are (auto-)generated from the upstream text source here https://github.com/openfootball/worldcup/blob/master/2026--usa/cup.txt

yes, you can. you are more than welcome to help with updates upstream.
anyone interested, please let me know / ping me here or here (as an opt-in / to give me permission) and i send you an invite via github for the openfootball (github) org here than you can edit in-place (without pull requests AND the worldcup.json gets generated via github action on commit - see the actions log @ /worldcup).

Note

@upbound-web has put together an alternate "fast-updating" worldcup.json mirror. see upbound-web/worldcup-live.json

World Cup 2026 Frequently Asked Questions (FAQ) & Answers

Q: Will it update live match data? How live is the (worldcup.json) data?

A: Sorry, no. worldcup.json works like a wiki. everytime the upstream (source) text, that is, worldcup/2026--usa/cup.txt gets updated (by hand), the 2026/worldcup.json datatset here gets automatically generated & updated (via github action - see the actions log @ /worldcup).

Again note the upstream (source) text updates are not live or automated. I (Gerald Bauer) try to update once a day and note - I am in Austria, that is, Central European Summer Time (UTC+2).

Anyways, to guarantee updates the best way is for you to contribute and update the score yourself. yes, you can. Send a pull request and I will merge and happy to send you an invite to join the github org (if you agree and opt-in by saying yes) so you can edit "in place" from than on.

PS: For full match details incl. line-ups, (yellow/red card) bookings, player substitutions, penalty shootouts, and more I will put together an (alternate) upstream (source) text - see worldcup/more for the history from 1930 to 2022 - but again sorry, that, page will NOT be live updated.

Tip

You can use the fbtxt2json command-line tool to convert any file in the Football.TXT format to JSON (or use fbtxt2csv to convert to CSV).

worldcup.json

Free open public domain football data for the world cups (national teams and clubs) in the JSON (JavaScript Object Notation) data interchange format incl. Canada/USA/Mexico 2026, USA 2025, Qatar 2022, Russia 2018 and more - No API key required ;-).

National Teams

Example - World Cup in Canada/USA/Mexico 2026 Match Schedule (Fixtures and Results) - 2026/worldcup.json:

{
 "name": "World Cup 2026",
 "matches": [
   {"round": "Matchday 1",
    "date": "2026-06-11",
    "time": "13:00 UTC-6",
    "team1": "Mexico",
    "team2": "South Africa",
    "score": {"ft": [2, 0], "ht": [1, 0]},
    "goals1": [{"name": "Julián Quiñones", "minute": "9"},
               {"name": "Raúl Jiménez", "minute": "67"}],
    "goals2": [],
    "group": "Group A",
    "ground": "Mexico City"
   },
   {"round": "Matchday 1",
    "date": "2026-06-11",
    "time": "20:00 UTC-6",
    "team1": "South Korea",
    "team2": "Czech Republic",
    "score": {"ft": [2, 1], "ht": [0, 0]},
    "goals1": [{"name": "Hwang In-Beom", "minute": "67"},
               {"name": "Oh Hyeon-Gyu", "minute": "80"}],
    "goals2": [{"name": "Ladislav Krejcí", "minute": "59"}],
    "group": "Group A",
    "ground": "Guadalajara (Zapopan)"
   },
   {"round": "Matchday 8",
    "date": "2026-06-18",
    "time": "12:00 UTC-4",
    "team1": "Czech Republic",
    "team2": "South Africa",
    "group": "Group A",
    "ground": "Atlanta"
   },
   {"round": "Matchday 8",
    "date": "2026-06-18",
    "time": "19:00 UTC-6",
    "team1": "Mexico",
    "team2": "South Korea",
    "group": "Group A",
    "ground": "Guadalajara (Zapopan)"
   },
   ...
   {"round": "Final",
    "date": "2026-07-19",
    "time": "15:00 UTC-4",
    "team1": "W101",
    "team2": "W102",
    "ground": "New York/New Jersey (East Rutherford)"
   }
]}

Example - World Cup in Qatar 2022 Match Schedule (Fixtures and Results) - 2022/worldcup.json:

{
 "name": "World Cup 2022",
 "matches":
  [{"round": "Matchday 1",
    "date": "2022-11-20",
    "time": "19:00",
    "team1": "Qatar",
    "team2": "Ecuador",
    "score": {"ft": [0, 2], "ht": [0, 2]},
    "goals1": [],
    "goals2":
     [{"name": "Enner Valencia", "minute": "16", "penalty": true},
      {"name": "Enner Valencia", "minute": "31"}],
    "group": "Group A",
    "ground": "Al Bayt Stadium, Al Khor"
   },
   {"round": "Matchday 2",
    "date": "2022-11-21",
    "time": "19:00",
    "team1": "Senegal",
    "team2": "Netherlands",
    "score": {"ft": [0, 2], "ht": [0, 0]},
    "goals1": [],
    "goals2":
     [{"name": "Cody Gakpo", "minute": "84"},
      {"name": "Davy Klaassen", "minute": "90+9"}],
    "group": "Group A",
    "ground": "Al Thumama Stadium, Doha"
  },
  ...
  {"round": "Final",
    "date": "2022-12-18",
    "time": "18:00",
    "team1": "Argentina",
    "team2": "France",
    "score": {"p": [4, 2], "et": [3, 3], "ft": [2, 2], "ht": [2, 0]},
    "goals1":
     [{"name": "Lionel Messi", "minute": "23", "penalty": true},
      {"name": "Lionel Messi", "minute": "108"},
      {"name": "Ángel Di María", "minute": "36"}],
    "goals2":
     [{"name": "Kylian Mbappé", "minute": "80", "penalty": true},
      {"name": "Kylian Mbappé", "minute": "81"},
      {"name": "Kylian Mbappé", "minute": "118", "penalty": true}],
    "ground": "Lusail Iconic Stadium, Lusail"
  }
]}

Clubs

Example - Club World Cup in USA 2025 Match Schedule (Fixtures and Results) - 2025/clubworldcup.json:

{
 "name": "Club World Cup 2025",
 "matches":
  [{"round": "Group A",
    "date": "2025-06-14",
    "time": "20:00",
    "team1": "Al Ahly SC (EGY)",
    "team2": "Inter Miami CF (USA)",
    "score": {"ft": [0, 0]}
   },
   {"round": "Group A",
    "date": "2025-06-15",
    "time": "18:00",
    "team1": "Palmeiras (BRA)",
    "team2": "FC Porto (POR)",
    "score": {"ft": [0, 0]}
  },
  ...
  {"round": "Final",
   "date": "2025-07-13",
   "time": "15:00",
   "team1": "Chelsea FC (ENG)",
   "team2": "Paris Saint-Germain (FRA)",
   "score": {"ft": [3, 0], "ht": [3, 0]}
  }
]}

How to Use the Public JSON HTTP API (Micro) Web Service - No API Key Required ;-)

Use the "raw" links served by GitHub (otherwise you get the complete "formatted" GitHub web page). Example:

$ curl https://raw.githubusercontent.com/openfootball/worldcup.json/master/2026/worldcup.json

Updates / Contributions Welcome - Please Update the Upstream (Source) Text Files

Note: The JSON files get (auto-)generated using the football.db datasets, thus, please do NOT edit the JSON files here but the upstream (source) text files in the /worldcup (and friends) repos e.g.:

National Teams:

Note: For the World Cup 2026 please update the source text file /worldcup/2026--usa/cup.txt for the group stage and /worldcup/2026--usa/cup_finals.txt for the knockout (quarter-finals, semi-finals, etc.) stage.

Clubs:

Note: For the Club World Cup 2025 please update the source text file /club-worldcup/2025/clubworldcup.txt

Contributions Welcome - Add Your Leagues and Tournaments!

Any leagues or tournaments missing? Contributions welcome! For starting your own repo from scratch see the League Quick Starter Kit.

License

The worldcup.json schema, data and scripts are dedicated to the public domain. Use as you please with no restrictions whatsoever.

Projects in the Real-World Using worldcup.json

Yes, you're more than welcome to send a pull request (PR) with your project!

World Cup 2026

Feel free to add your project here!

Questions? Comments?

Yes, you can. More than welcome. See Help & Support »